DeerFlow实战：用LLM构建数据分析自动化流水线

先聊个真实感受：这两年我在数据分析上花的时间，大头从来不是写SQL或者调Pandas，而是浪费在“拿到一份不知道底细的数据后，先得做一堆探索性分析，才能决定下一步怎么写”。这种活极其重复，每次都要清洗、看分布、算相关性、画几个图、再决定怎么建模。直到我接触到DeerFlow这个开源项目，第一次让我觉得“数据分析这件事，确实可以被流程化、自动化地拆开”，所以这篇内容不是单纯介绍某一个工具，而是把它当成一个引子，聊聊数据分析自动化框架的整体设计思路、实操细节和踩坑记录。

如果你平时的工作是处理表格、做报表、跑探索性分析，又对LLM参与数据链路这件事感兴趣，这篇文章应该能帮你在十分钟内搭出一个能用的自动化分析雏形。如果你是做数据平台或者AI应用开发的，里面关于Agent调用和数据工具的编排方式，也有可以直接抄作业的部分。

1. DeerFlow是什么：把“分析经验”沉淀成流水线

建议先放下“这个框架叫什么”这件事，先看它做了什么。DeerFlow本质上是一套面向数据处理场景的LLM自动化编排框架，它做的事情可以概括成一句话：把你的数据问题丢给大模型，让模型通过调用数据分析工具，自动完成清洗、探索、统计、可视化和结论生成。

这和“直接把CSV丢给ChatGPT”是完全不同的玩法。直接把数据丢给对话模型，你会遇到几个很现实的问题：上下文长度不够、模型算不准数值、结果不可复现、没法处理大文件。而DeerFlow这类框架的思路是，让LLM去当“分析师”而不是“计算器”——模型只负责拆解任务、写代码、调用工具、解释结果，真正跑数和计算的活交给Pandas、DuckDB、Spark这些专业引擎去做。

1.1 数据分析老问题，为什么一直没被解决

传统的数据分析流程是这样的：拿到数据 → 用Pandas或Excel做清洗 → 画图 → 观察规律 → 写结论。这套流程的问题在于决策链太长，而且每个环节都依赖人的经验。比如“是否删除缺失值”，老手会先看缺失比例、再看字段含义、还得分缺失是否随机，新手通常直接dropna()，一步就把信息扔了。

DeerFlow希望做的，就是把“老手的判断经验”以提示词和流程模板的方式固化下来，让LLM在每一步都做决策，但执行还是交给那些经过验证的数据工具。这样做有三个层面的好处：

• 一致性：同一套流程跑同一份数据，结果稳定可复现，不会因为操作者不同而结果完全不同。
• 效率：探索性分析的日常操作，比如describe、value_counts、相关性矩阵，这些完全可以让LLM自动生成并执行，人只需要看结论。
• 沉淀：跑过的流程、写过的Prompt、调过的参数，都能沉淀成可复用的配置文件，团队内部能直接共享。

1.2 核心模块与整体工作流程

以我接触到的版本来看，DeerFlow的整体设计是“三个角色 + 一个调度器”的模式。

• Planner（规划器）：负责理解用户的数据问题，把它拆解成可执行的分析步骤。比如用户问“哪个品类的复购率最高”，Planner会先拆成：字段梳理 → 数据清洗 → 计算复购率 → 排序输出 → 生成图表。
• Executor（执行器）：真正干活的模块，负责调用数据工具执行Planner给出的具体操作。每一步操作可能是一段Pandas代码，也可能是一条DuckDB SQL，或者一个Spark Job。
• Reflector（反思器）：在我看来这是DeerFlow最有价值的一部分。它会把Executor的执行结果和Planner的预期做对比，如果发现结果异常（比如数据量为0、字段缺失、分布诡异），会自动触发修正流程，典型场景是清洗规则调整后再跑一轮。
• Scheduler（调度器）：把这些模块串起来，控制任务的流转，同时也负责上下文管理和中间结果缓存的清理。

整个流程环环相扣，看起来就像在跑一条自动化的“分析流水线”。第一轮结果出来后，Reflector先判断可信度，再决定要不要重新执行。这个设计对真实数据分析非常关键，因为脏数据的坑实在太多了，一次跑成功是运气好，起码得跑两到三轮才靠谱。

1.3 谁适合用，谁暂时别碰

先说实话，DeerFlow不是给完全不懂数据的人准备的“傻瓜分析机”。你用它的前提是：你得理解数据分析的常见概念，比如缺失值、去重、聚合、透视，你得知道自己想要什么分析结果。DeerFlow帮你省的是“具体步骤的执行时间”，而不是“制定分析目标的能力”。

我总结下来，这几类人收益最明显：

• 数据产品经理/业务分析师：每周固定产出各类数据报表，分析思路相对固定，可以用DeerFlow把整个分析流程沉淀下来。
• 数据平台的研发工程师：经常要写临时的数据探索脚本，或者给业务方搭自助分析工具，用DeerFlow做底层引擎非常合适。
• 刚入门的数据分析师：想看看老手的分析思路是什么样，DeerFlow跑出来的流程和代码本身就是很好的学习样本。

反过来，如果你的分析场景非常单一，比如每天只是跑同一个SQL然后出表，那直接写死脚本更划算，DeerFlow的LLM调度部分反而是多余的。

2. 技术设计思路拆解：为什么框架要这么搭

指采用“LLM做决策、工具做执行”的混合架构，是有非常实际的原因的。这直接和数据工具的特点有关，下面拆开说。

2.1 大模型的“认知能力”和“计算能力”必须分离

再聪明的LLM，直接让它做1万行数据的求和，可能都能算错；但让它“写一段Pandas代码做求和”，它可以做得又快又稳。核心原因是：LLM擅长的是模式识别和任务分解，不擅长确定性计算。

DeerFlow的设计正好抠住了这点。它把“数据分析”这个高层任务切分成两层：

• 决策层（LLM）：负责理解、规划、反思、解释。
• 执行层（Pandas/DuckDB/Spark）：负责加载数据、做计算、出数字、画图。

两层之间通过结构化指令通信。Planner产出的是“操作计划”，本质上像一份伪代码清单；Executor把清单翻译成真实代码并在沙箱里执行，返回执行结果和耗时的结构化摘要。这种设计避免了让大模型直接面对整份原始数据，既绕开了上下文窗口限制，又大大提升了计算精度和速度。

我实际用下来的体会是，90%的计算错误都跟“让模型直接算数”有关，而一旦切换成“模型写代码，引擎算数”的模式，正确率几乎能追平手写代码的水平。

2.2 工具调用的关键：给工具做一层“描述层”

在DeerFlow里，Executor能调用的数据工具，并不是每个都直接暴露原始API，而是经过了一层“描述层”封装。说白了，就是给每个工具写清楚三件事：功能说明、输入参数格式、输出结果结构。

比如DuckDB这个引擎，封装之后它的描述可能是：“执行SQL查询，返回DataFrame；适合用于多表关联和聚合类操作；不支持需要UDF的复杂计算”。这样Planner在规划时就能快速判断“这一步该用Pandas还是DuckDB”，不会傻傻地用Pandas跑一个1GB文件的group by。

这个设计思路特别值得借鉴。如果你也在做Agent或自动化流程，千万不要把几十个工具一把梭全部暴露给LLM，而是要像写API文档一样把每个工具的能力边界写清楚。模型不是万能的，你给的信息越结构化，它选对工具的概率就越高。

2.3 流程编排：把分析从“自由对话”变成“状态机”

另一个让我印象深刻的点是DeerFlow的流程编排。它没有把Planner、Executor、Reflector做成“自由对话”式的循环，而是设计成了带有明确状态转移的流程，大致是这样：

• Init：接收任务，加载数据集元数据（列名、类型、行数）。
• Planning：Planner生成分析计划，包含步骤列表和每步所需工具。
• Execution：Executor循环执行计划步骤。
• Reflection：Reflector对执行结果做校验，判断是否满足预期。
• Adjustment：不满足则回到Planning，重新生成修正后的计划。
• Finalization：满足则汇总结果、生成结论报告。

这样的状态机设计带来的直接好处是“可控”。每次进入Reflection时，系统都会记录当前的数据快照、执行日志和反思意见，出问题能回溯到具体是哪一步产生的。这比一长串自由上下文可靠得多，也方便做并行调度——多个分析任务可以独立跑在不同状态上，互相不干扰。

2.4 可观测性与人工复核机制

数据分析自动化最忌讳的就是“黑盒”，如果模型自己改了一个清洗规则，而用户完全不知道，那最终结论的可信度就归零了。所以DeerFlow把可观测性也纳入到了框架的底层设计中。

几个关键的机制包括：

• 操作日志：每一步Executor执行的操作（比如“删除ProductName列中3条空记录”）都会记录在案。
• 数据血缘：每个输出字段都能追溯来源，这份数据是从原始表的哪个字段、经过什么变换得到的。
• 人工复核点：支持在流程的任意位置插入“人工确认”步骤，如果某个环节的自动判断置信度不够，会暂停执行并等待人工输入。

这些机制让整个流程在自动化和可控之间找到了平衡。做技术方案的时候，很多人只盯着“自动化率有多高”，却忽略了“出了问题能不能解释清楚”，这两者其实是同等重要的。DeerFlow把这一点想清楚了，这也是我愿意长期用它做原型验证的原因。

3. 环境准备与快速上手：把DeerFlow跑起来再说

实操部分我尽量写得细一点。以下内容基于我本地的真实环境：MacBook Pro（Apple Silicon）、Python 3.11、Docker Desktop 4.x。如果你用Windows或Linux，大部分步骤是通用的，个别路径差异我会标注。

3.1 安装与依赖清单

首先确认Python版本，建议用3.10及以上，3.9在一些新版本依赖上会有兼容问题。我踩过一个坑：Python 3.9环境下装pandas 2.x会编译报错，换3.11之后一次通过。

# 检查Python版本 python --version # 创建虚拟环境（强烈建议） python -m venv deerflow-env source deerflow-env/bin/activate # Windows用: deerflow-env\Scripts\activate # 安装DeerFlow主包 pip install deer-flow # 如果希望在流程中调用DuckDB或Spark，需要额外安装对应插件 pip install deer-flow[duckdb] pip install deer-flow[spark]

安装完成之后，输入deer-flow --version能打出版本号就说明装好了。如果没有，大概率是网络源的问题，换成国内镜像源试试：

pip install deer-flow -i https://pypi.tuna.tsinghua.edu.cn/simple

再说一下Docker的事。如果你打算把DeerFlow和它的执行沙箱跑在容器里，建议参考项目里的docker-compose.yml模板，直接起一套带完整依赖的环境。但本地快速试验时完全没必要上Docker，直接裸环境跑就行，内存方面，至少留4GB给Python进程，因为分析框架本身会缓存一定量的中间数据。

3.2 最小示例：让DeerFlow分析一份CSV

装好后我建议你先跑一个最小例子，感受一下流程。创建一份销售数据sales.csv，大概包含日期、地区、产品、销售额、订单量这几个字段，造个几十行数据就行。接下来写一个极简脚本：

from deer_flow import DeerFlow # 初始化 flow = DeerFlow( model_name="gpt-4o-mini", # 如果用本地模型，改成 "local/qwen2.5:7b" tools=["pandas", "duckdb", "matplotlib"], ) # 传入数据和问题 result = flow.analyze( data_path="./sales.csv", question="按地区统计总销售额和订单量，并排出前三名", output_dir="./output", ) print(result.summary) print(result.chart_paths) print(result.execution_log)

这段代码的逻辑很直白：初始化一个DeerFlow实例，指定模型和允许使用的工具，然后调用analyze方法，传入数据文件路径和分析问题，最后输出结论摘要、图表路径和执行日志。

第一次跑的时候，你会看到控制台输出类似这样的信息：

[Planner] 正在拆解任务... [Planner] 计划生成: 步骤1 读取数据并打印列名与类型 [Planner] 步骤2 按地区分组聚合销售额、订单量 [Planner] 步骤3 排序并输出Top3 [Executor] 执行步骤1: 加载CSV并做概要检查 [Executor] 执行成功, 返回DataFrame形状(100, 5) [Executor] 执行步骤2: groupby聚合 [Reflector] 校验结果：输出包含5行3列，字段类型正确，合格 [Final] 生成结论报告: report.md

看到Final输出之后，去output目录下找report.md和对应的图表文件。如果一切正常，report.md里面会有一段类似“华东地区销售额最高，达xx万元，主要贡献产品是空调和冰箱”这类结论文字，以及一张柱状图。

3.3 配置文件：不用每次改代码

每个任务都写一遍Python脚本虽然也能用，但在真实项目里我更推荐用配置文件的方式。DeerFlow支持YAML格式的配置，把模型、工具、数据源、输出目录、甚至Prompt模板都抽出来：

# flow_config.yaml model: provider: openai name: gpt-4o-mini temperature: 0.1 tools: enabled: - pandas - duckdb - matplotlib matplotlib: style: whitegrid dpi: 150 data: path: ./sales.csv output: dir: ./output save_intermediate: true reflection: max_adjustments: 3 check_schema: true check_row_count: true

然后在Python里加载配置：

from deer_flow import DeerFlow flow = DeerFlow.from_yaml("flow_config.yaml") result = flow.analyze(question="按地区统计总销售额并画柱状图")

用配置文件的好处是后续调参很灵活。比如同一个分析任务，今天用OpenAI的模型跑，明天想换成本地模型，只需要改配置里的model.provider和model.name，不用动分析逻辑。这个模式在做团队协作时尤其舒服。

3.4 理解输出：别只盯着summary

刚上手的人容易只读result.summary，认为那才是分析结论，实际上这只是最表面的一层。更值得看的是execution_log和intermediate_files。

execution_log里记录了每一步操作的细节，比如“步骤2使用了duckdb执行SQL，扫描行数100，耗时0.03s”。这个日志的价值在于：当你发现结论不对时，可以快速定位是哪一步出了偏差，而不是对着最终结果干瞪眼。

intermediate_files是每一轮分析后保存的中间结果文件。开启save_intermediate: true之后，每一步的数据快照都会存到本地。这有点像数据分析的“检查点”，万一最后一步跑挂了，你还能从最近的步骤继续，不用从头再来。

4. 实战案例：从一份销售CSV到可视化报告

这一部分我会用一次完整的实战过程，把DeerFlow从“能跑”推进到“能用的顺手”。里面的问题和解法都是我实际遇到过的，不是编出来的。

4.1 数据分析的第一步：先定义问题

这次案例的数据是我模拟生成的一份电商销售数据，包含以下几个字段：

我给DeerFlow的问题只有一句：“分析各品类的月度销售趋势，找出增长最快的品类，并分析它主要增长在哪些地区。”

这个问题的难点不在于“统计”，而在于“增长最快”的定义。是环比增长率最高？还是绝对增量最大？还是连续多月正增长？不同定义会得出不同结论。所以我在调用时额外加了一个提示，要求DeerFlow在报告中明确说明“增长”的定义方式。

4.2 编写分析流程与关键Prompt

DeerFlow支持在question之外单独传入hints，用来约束分析方向：

result = flow.analyze( question="分析各品类的月度销售趋势，找出增长最快的品类，并分析它主要增长在哪些地区。", hints=[ "先按category和order_date（按月）做聚合", "增长率使用环比增长率，即本月销售额/上月销售额-1", "如果某月没有销售额，视为0" ] )

加hints的做法非常有用。让LLM完全自由发挥，它可能会用一个很冷门的指标定义，导致后续结论不可比。加上hints之后，模型的决策空间被约束在合理范围内，最终结果也更容易解释。

循环执行之后，DeerFlow会生成两类主要产物：

• 分析报告：Markdown格式的完整报告，包含表格、结论、图表引用。
• 过程代码：执行过的Python代码片段，分为多个单元保存，方便人工复核。

4.3 结果复核：出错了不要慌

第一次跑这个案例时，我的结果明显有问题：报告显示“家居”品类环比增长率达到340%，但这个结论明显失真，因为上一月销售额基数太低，只有几千元，稍微增长一点就能翻几倍。DeerFlow不会自动理解“低基数效应”这个业务概念，它只负责忠实执行计算规则。

这个情况就很需要人工复核介入。我做了两件事：

第一，查看execution_log，确认它确实用了我给定的环比公式，没有算错数。计算逻辑没错，那问题就出在指标定义上。

第二，我手动追加了一个筛选条件，“只考虑月销售额大于5万元的品类”。重新跑一遍之后，结论变成了“电子”品类增长最稳健，连续4个月保持8%以上的环比增长，且增量主要来自华东和华南地区。这个结论明显更有业务意义。

这里分享一个心得：数据分析自动化不代表你可以做甩手掌柜。模型采用哪种指标、如何定义“增长”、如何处理异常值，这些决策直接影响结论质量。好的做法是让模型多轮迭代，并在关键节点加入人工确认。DeerFlow的reflector能拦截明显的技术错误，但业务层面的判断还得靠人。

4.4 把流程固化成定时任务

分析跑通之后，下一步就是把它固化成定期执行的报表任务。我直接把写好的脚本接到crontab上：

# 每天早上9点执行一次分析 0 9 * * * cd /path/to/project && /path/to/deerflow-env/bin/python run_daily_analysis.py >> logs/analysis.log 2>&1

run_daily_analysis.py里的逻辑就是读取前一天的增量数据，调用同一个question和hints，把最新分析结果输出到当日目录。这样运营同事每天早上就能看到一份自动生成的前一天销售分析报告，不需要等人工跑数。

这个“固化”环节看起来简单，但有几个细节必须处理：数据源的读取路径要支持日期参数，输出目录要按日期隔离，日志要保留足够长的时间方便排查问题。否则定时任务连跑一周之后，就会因为文件覆盖或路径不对而出各种幺蛾子。

5. 常见问题、避坑清单与实战心得

这部分是全文含金量最高的一部分。我整理了这段时间用DeerFlow写过十几个场景后遇到的典型问题，按主题分成几个小类，针对每个问题都给出排查思路。

5.1 实操中的典型问题速查表

排查这类问题的核心思路，永远是先分清是模型决策的问题，还是工程执行的问题。模型决策问题看Planner的输出，如果计划本身就跑偏了，后面全废；工程执行问题看Executor的日志和中间数据，那里有每一步的实际输入输出，定位起来非常快。

5.2 模型选择的经验：有多大脚穿多大鞋

说实话，DeerFlow对模型的依赖比我想象中高。最初我用本地7B模型跑简单的“分组求和”任务，结果能爆出“FieldNotFoundError”，因为模型写的代码里字段名拼错了。关掉重跑好几次，还是有类似的低级错误。后来换成70B级别或GPT-4级别的模型，这类基础错误大幅减少。

所以我的建议是可以分场景来选择模型：

• 复杂多步分析、生成正式报告：用GPT-4或Claude级别的大模型，推理能力是关键，多花点token成本也值。
• 日常探索、格式相对固定的分析：用中等尺寸模型，成本低，响应快，出错的概率也可以接受。
• 本地隐私数据、不允许外传时：用本地部署的70B级别模型，配合反射机制多跑几轮，做好人工复核兜底。

另外，temperature这个参数要特别注意。我一般设成0.1或0，数据分析场景对“创造性”要求不高，对准确性和一致性要求极高，温度越高越容易出错。

5.3 数据安全与权限控制

最后说一个很多人忽略的问题。DeerFlow这类框架默认会把数据路径、字段名、甚至部分样例数据发给模型去做计划生成。如果你处理的医保、财务、用户隐私等敏感数据，这一步就有隐患。

我的做法分两步：

• 第一步，在DeerFlow的配置里开启字段脱敏选项。它会在把数据信息发送给模型前，把列名替换成虚拟字段（col1、col2），并对样例数据做截断和模糊化处理。
• 第二步，优先级更高的场景，我直接把DeerFlow部署在内网环境，接入本地大模型服务，完全不走外部API。这样既能享受自动化分析的好处，又避免数据出境风险。

在使用这类LLM自动化工具之前，一定要先评估数据敏感性，再看清楚框架调用外部模型的行为路径。框架默认可能是“最大可用模式”，什么都往外发，这个默认选项不一定适合你的业务。

5.4 关于成本控制的提醒

LLM自动分析不是免费的，每一步Planning和Reflection都在消耗Token。我在一个中等规模的数据分析任务里，跑一轮大概消耗5k~10k Token，如果触发多次Reflection调整，成本会进一步增加。

控制成本的几个实用技巧：

• 给Reflector设上限：max_adjustments不要设太大，2~3次够了，太多轮调整成本几乎不可控。
• 复用中间结果：如果原始数据没变，不要重复跑完整的Planning和清洗流程，直接缓存读取。
• 用小模型跑粗筛，大模型跑精分析：先用小模型做数据概览和清洗，只有核心结论部分调用大模型，成本能省不少。

我甚至见过有人把DeerFlow的Planner换成免费的本地小模型，只让最后的报告生成调用GPT-4，效果也不错。这就是DeerFlow组件化设计的好处，每个模块都可以单独替换，并不会被绑定死。

6. 一些个人实践感受

用了DeerFlow一段时间后，我对“数据分析自动化”这件事的看法确实发生了一些变化。它确实不能替代分析师，但能非常明显地减少机械性劳动。以前做一个新数据源的探索性分析，从拿到数据到出第一版结论，怎么也得一两个小时；现在用DeerFlow搭个流程，十几分钟就能得到一份结构清晰的初版报告，之后我再花时间去验证关键结论、修正业务口径。

如果说有什么经验最想分享给刚接触这类框架的人，我想是这句话：把精力花在“定义问题”上，而不是“写代码”上。你在Prompt里把问题定义得越清晰、指标口径约束得越死，后面全流程跑起来就越顺利。反过来，如果只丢一句“帮我分析一下”给模型，哪怕再强的LLM也很难给出可用的结果。

另外，这个框架后续值得探索的方向也很多。比如把DeerFlow接入到BI系统里，让业务人员用自然语言直接查数出报表；或者把它跟数据质量监控工具结合起来，当某个字段的异常波动触发了阈值，自动触发一次深度归因分析。这些场景本质上都是DeerFlow这一套“规划-执行-反思”模式在不同业务侧的延展。

如果你现在手头正好有一堆Excel或CSV等着分析，不妨花个周末把DeerFlow跑通，用它重新走一遍你以前手动做过的分析流程。我相信你会和我一样，第一次看到自动化报告生成的时候有点惊喜，然后开始琢磨怎么把更多重复工作交给它。