1. 项目从哪来DeerFlow 到底解决什么问题先说个场景。你手上有个选题比如“对比一下主流的向量数据库在物联网场景下的选型差异”或者“拆解某开源框架的缓存淘汰策略实现”。搁以前怎么办自己开十几个网页一个个翻文档、刷 issue、看性能对比图边看边做笔记运气好一小时能理出个大概运气不好一下午就泡进去了。更烦的是信息源杂乱有些资料已经过时有些是营销软文整理出来的结果还需要二次核实。DeerFlow 这个框架走的路线不一样。它把“深度调研”这件事拆成了多个智能体协作的流程规划方向的、阅读材料的、写初稿的、审校把关的各管一段。你只需要给出一个研究主题它会自动拆解成调研计划从你配置的搜索渠道里抓取和主题相关的材料然后逐条分析、交叉验证最后输出一份带引用结构的调研报告。整个过程你可以全程围观每个环节都有日志可以翻中间结果也能落盘。它的应用场景简单说就是“重阅读、轻创作”的活儿。需求调研报告、竞品分析、技术选型评估、某个方向的资料汇编这些以信息收集和整理为主的工作DeerFlow 能帮你跑出一个相对可靠的底稿。它不是替代你做判断而是把最耗时的那部分——找资料、筛信息、做初步归纳——自动化。适合谁来玩两类人。一类是做技术选型、行业调研的开发者手上正好有一批反复出现的调研类需求想要一套可以二次开发的工作流。另一类是搞 RAG 和智能体应用的同学把 DeerFlow 当现成的多智能体参考实现来读源码、改流程、做二次开发。前者直接跑起来用后者把它当教材拆。我最初看到这个项目的时候第一反应是又一个大模型套壳。真正读进源码才发现它把“搜索、阅读、写作、审查”这四个环节做成了流水线每个环节都有独立的模型配置和提示词管理这不是套壳能套出来的。直接把项目拉下来跑了一遍又顺手改了几个配置项做了几轮验证算是把整个执行链路摸了一遍。2. 框架核心链路四个角色分工与执行流程解析2.1 调研规划到报告产出的完整流程DeerFlow 的整个执行逻辑可以用一句话概括把“人类研究员的工作习惯”翻译成“智能体协作流程”。一个合格的研究员拿到选题后不会直接去读文章。他会先列大纲想清楚这个题目需要覆盖哪些方面每个方面大概需要什么证据支撑然后才带着问题去检索。DeerFlow 的发布规划模块Planner做的是同样的事。它接收你给出的研究主题通过一轮大模型调用输出一份结构化的调研计划。这份计划不是简单地列几个关键词而是会细化到章节结构、每个章节需要回答的核心问题以及计划检索的相关方向。我实际测了一个偏技术选型的题目它的规划输出相当具体。计划里甚至写明了某个章节需要对比哪些维度比如吞吐量、可用性、客户端生态。这份计划后续会作为任务清单分发给执行模块去落地。这里有个容易忽略的细节规划模块生成的计划会作为任务分发的依据所以如果你对输出结构有特殊要求比如“只要对比结论不要背景介绍”最好在研究主题里就写明不要留太多发挥空间。接下来是信息采集环节对应框架里的研究执行模块Drafter。它要做的事有两件根据计划里的检索方向生成具体的搜索词把返回的搜索结果逐条读取并做内容抽取。这两个动作是反复进行的因为第一轮搜索可能发现某些方向信息量不够它会按照预设策略调整搜索词再搜一轮。信息抽取也不只是简单地把网页正文存下来而是会做清洗去掉导航、底部声明这类噪音内容再截取与主题相关的段落。然后是内容生成环节。执行模块把采集到的资料按计划组织起来起草各个章节的正文。写完之后审查模块Reviewer会对全文做一轮质量检查。这个检查覆盖几个维度内容的准确性还是结构层面的合理性比如章节之间的逻辑衔接、引用标注是否到位。审查模块发现问题后会返回修改意见让草稿模块做针对性修订而不是整篇重写。最后是报告渲染环节。DeerFlow 会把审核通过的内容组装成一份带标题层级、引用标注的 Markdown 报告写入输出目录。以 JSON 格式保存的结构化信息也同时落盘包含报告全文、引用来源列表、中间产出的规划明细和执行日志方便做后续的程序化处理。这整套流程的设计思路是模块化。熟悉 LangChain 或自研智能体框架的人很容易把每个模块映射到对应的抽象层。但 DeerFlow 做得更重一些的地方在于它对每一步的输入输出格式做了严格约定模块之间通过结构化的数据对象交互而不是直接拼接字符串。这对于流程的可调试性帮助很大。2.2 为什么是“规划-执行-审查”的分层设计很多初学智能体开发的人容易犯一个毛病把什么逻辑都塞进一个 Agent 里让它又当规划器又当执行器又当审查员。表面上看省事实际跑起来就会发现上下文窗口根本不够用而且任务一多就容易乱。DeerFlow 的分层设计思路刚好相反它把不同职责拆到不同的智能体里每个智能体只做一件事反而更容易控制质量。拿“审查”这个环节举例。如果没有独立的审查模块草稿生成完之后就直接输出大概率会出现一个问题跑出来的报告内容空泛或者大段文字是从原文里直接拼过来的。加了审查员之后它会站在读者的角度审视全文发现哪些地方逻辑有跳跃、哪些章节明显材料不足再把这些问题作为反馈传给执行模块。这种分层设计还有一个实际好处可以针对不同环节使用不同的模型。调研规划需要较强的结构化输出能力草稿写作需要较强的总结归纳能力审查环节需要的是挑剔的眼光。DeerFlow 在配置上允许给每个环节指定不同的模型比如规划用推理能力强的模型草稿用中档模型压缩成本审查再用回强模型。我实际测试下来把草稿环节换成小模型输出质量会略有下降但配合审查修订最终结果和全流程用大模型相比差距不大成本却能省下不少。如果你的预算有限这个配置角度值得仔细调一调。2.3 配置模型与密钥把“骨架”变为“可用系统”项目拉下来之后第一步是配置模型服务。DeerFlow 的设计里大模型作为推理引擎贯穿规划、草稿、审查等环节同时还有一个相对轻量的小模型承担生成搜索词等辅助任务。小模型和大模型是分开配置的这意味着如果你的场景里某些环节不需要辅助模型也可以只配置大模型通道把用到小模型的功能绕开。配置方式上DeerFlow 通过环境变量的方式读取模型服务地址、密钥和模型名称。它针对常见的大模型 API 服务做了适配接入方式基本是“填服务地址、填密钥、填模型名”。如果你用的是国内可以直接访问的大模型服务在环境变量里配置好对应的服务地址、模型名和密钥就可以跑起来。提示第一次配置的时候建议先只开一个最简单的调研主题来验证链路是否通畅。不需要一上来就上大题目。主题越简单越容易快速跑通整个流程也方便排查配置问题。2.4 搜索与数据源接入Web 搜索的机制与配置要点DeerFlow 的调研能力高度依赖搜索这一环。看源码时你会发现它支持配置多个网络搜索服务商并且给每个搜索服务源设定了超时时间与重试参数。实际跑任务的时候它会优先使用你配置的服务如果某个来源请求失败会自动尝试下一个可用的来源。这个多来源备用机制非常实用。我一开始只配置了一个搜索服务跑到一半任务直接失败了日志显示是搜索接口限流。后来把备用服务也配置上再跑同样任务虽然在搜索阶段偶尔还会看到重试日志但整个流程不会再因为单一来源的限流而中断。有一点值得注意DeerFlow 有些组件涉及网页内容抓取。它在抓取时会使用默认的请求头发起访问但部分网站对非浏览器请求的拦截比较严格容易导致抓取失败。遇到这种情况可以考虑调整抓取请求的默认头在请求中携带更接近浏览器的标识。但修改的时候要留意目标网站的服务协议合理控制抓取频率、设置合适的延时避免给对方站点造成压力。搜索和数据抓取这块需要根据你自己的实际场景调整参数没有一套配置通吃所有场景的银弹。3. 环境与部署从 Clone 到跑通第一个任务3.1 环境准备与依赖安装DeerFlow 的部署方式兼顾了本地开发模式和容器化部署模式。本地模式适合快速调试和二次开发容器化模式适合想省去环境折腾、直接跑服务的人。先看本地模式的准备步骤。项目使用uv作为 Python 依赖管理工具。Python 版本建议使用较新的 3.11 或 3.12 版本uv会按项目配置文件自动处理依赖解析和安装。把项目代码克隆下来之后在项目根目录执行环境同步命令即可把依赖包装好。实际跑的时候因为依赖里包含一些需要编译的 Python 包如果系统里缺少编译工具链可能会在安装过程报错。Linux 环境一般需要确认build-essential这类基础工具已安装Windows 环境需要确认 Visual C 构建工具可用。执行启动命令之后框架会启动一个本地服务监听默认端口。终端里会输出服务地址其中/workflow路径对应的就是任务发起入口。3.2 后端工作流 API 的调用方式启动服务之后需要通过 HTTP 请求把调研任务提交给工作流服务。请求路径是/workflow方式为 POST请求体是一个 JSON 对象核心字段是研究主题。这里给一个最精简的请求体示例{ research_topic: 对比开源向量数据库的持久化策略 }发起请求之后服务端会返回一个任务 ID。这个 ID 很重要后续查看执行状态、获取执行日志、确认输出路径都要用到它。理论上如果不发起 HTTP 调用也可以直接进入工作流模块内部去调用底层节点但我不推荐。DeerFlow 的服务层已经做了一套较完整的状态管理和上下文传递绕开 API 直接调用底层节点容易丢失部分中间状态信息不便于问题排查。注意请求里最好明确输出语言。DeerFlow 的底层模型默认情况下可能根据提示词缓存或模型自身习惯输出非目标语言。你可以在研究主题末尾直接追加一句“请使用中文输出报告”实测下来这是规避语言漂移最有效的办法。3.3 执行任务与监控运行状态任务提交成功后工作流开始执行。整个流程耗时取决于主题复杂度和配置的模型响应速度。一个中等复杂度的调研主题完整跑完通常在数分钟级别大部分时间消耗在搜索采集和草稿生成的多次调用上。执行期间值得关注的是日志输出。DeerFlow 的服务端日志会实时打印当前执行到哪个环节每个环节的耗时、是否重试、是否跳过都能看到。你不需要一直盯着但跑完任务之后翻一遍日志是很有价值的习惯尤其是你想知道某个环节为什么耗时高或者为什么某些引用没有写入报告的时候日志里的细粒度记录都能给出答案。如果集成配置了可观测性工具执行过程中的模型调用记录、Token 消耗、调用耗时这些指标都会被记录在案。后续做成本分析、性能调优的时候这些数据比拍脑袋靠谱得多。3.4 执行产物与输出目录报告、JSON 和对话记录任务跑完以后输出目录里会多出几类文件。最直观的是报告全文格式是 Markdown带清晰的标题层级。我见过有人直接把这套报告的 Markdown 内容贴到文档平台排版几乎不用改省了不少事。除了报告全文同目录下还会生成一份结构化 JSON 文件。里面不只包含正文还包含生成报告的中间信息比如规划阶段产出的章节安排执行阶段产出的各章节草稿内容以及全文引用来源列表的完整清单。对想要做后处理的人来说这份 JSON 比 Markdown 报告更有价值因为它是机器可读的可以直接作为下游输入。最后就是执行过程的对话记录和运行日志。对话记录按轮次保存了各个模块的大模型请求与响应这对于调试提示词、分析某一章节生成质量低的原因非常有用。提示输出目录默认在项目下的某个固定路径。如果你在用容器方式运行记得确认该目录是否做了挂载否则容器重建之后产物会丢失别问我是怎么踩到这个坑的。4. 可观测性怎么看清调研 Agent 的内部状态多智能体应用有一个天然的痛点黑盒感太强。你只知道输入了一个问题输出了一份报告中间发生了什么一概不知。DeerFlow 在可观测性上做了集成设计这也是它比一般的脚本式爬虫方案更像一个“框架”的原因。默认情况下DeerFlow 通过环境变量开关来决定是否把追踪数据导出到外部链路追踪系统。你可以配置好对应的服务地址并打开跟踪开关。配置好之后执行任务的过程中每一步的细节——当前智能体在做什么、调用模型的输入输出、Token 用量、耗时数据——都会实时上报。日志里能直接查看到大模型的原始请求与回复内容。Debug 模式下每条日志消息都标记了请求来源模块、目标模型和耗时。这种日志详细程度对于定位问题太关键了它能快速区分“是哪一步慢”和“是哪一步返回了异常格式”而不是靠猜。外部追踪服务里呈现的是一个端到端的执行泳道图。每个节点标注了耗时和输入输出摘要一眼能看到时间花在了哪个环节。对于想要把现状摸清楚、再做针对性优化的人来说这套信息比直接看报告有价值得多。当然不上外部追踪服务也不影响基本使用因为本地文件系统和终端日志已经覆盖了大部分调试需求。但如果你打算在多智能体应用上加一些观测能力DeerFlow 的配置方式可以直接作为参考。5. 二次开发方向把框架接入自己的工作流从项目结构上可以看出DeerFlow 不仅仅是一个“能用”的应用它更像是一个骨架清晰的多智能体应用模板。拿到手之后除了直接用至少有三个方向值得自己动手改一改。第一个方向是改提示词。各模块的提示词都是独立维护的核心模块之间的提示词互不干扰。这意味着如果你想给调研报告加一段固定的方法论章节或者想控制某个章节的写作风格直接修改对应模块的提示词即可不用动其他模块。第二个方向是调整模块间的数据流转。DeerFlow 在各模块之间传递的是结构化数据这意味着你可以中途插一段自己的逻辑。举个实际例子你可以把草稿模块产出的中间结果接出去走一步本地知识库的检索把检索到的补充材料合并回流程里再把结果传给审查模块。这种改动在代码层面只需要小范围修改。第三个方向是改输出格式。默认输出是 Markdown但如果你需要的是特定格式的交付物比如要发布到内部文档平台的 JSON 结构、要投喂到内部知识库的分块格式可以直接在后处理阶段写自己的渲染逻辑替换掉默认的生成逻辑。我觉得多数拿这个项目做二次开发的人目标不会是做一个通用的“报告生成器”而是以此为底座改造成适配自己行业场景的垂直调研工具。比如做行业研究的可以把默认的搜索渠道改成垂直站点再做一轮信息抽取的清洗。比如做产品分析的可以加一层舆情热度排行逻辑。这类改造建立在理解框架数据流的基础上难度不大但价值是实打实的。6. 实际踩坑记录部署与运行中的典型问题6.1 依赖安装失败与 Python 版本兼容DeerFlow 依赖一些需要编译的 Python 包在不同系统上表现不一样。最容易遇到的问题是某些预编译包在当前平台没有对应的 wheel安装时退回到源码编译然后编译失败。这类问题的通用解法是先升级pip和构建工具链再重装那个包。如果不想折腾系统级工具链可以考虑用容器化版本运行它会预装好运行时依赖相当于把环境问题整体隔离掉了。实测下来在比较干净的 Linux 服务器上部署最省事Windows 上容易遇到个别包的编译问题虽然也能解决但需要多花些时间在环境准备上。6.2 模型服务配置不生效这类问题通常出现在首次部署时。配置了环境变量但服务没有重新加载导致实际运行时仍然尝试连接默认的模型服务地址然后连接失败。排查方式不复杂先确认进程是重启后加载了新配置再确认环境变量的命名和取值格式正确。有些新增配置项在旧版本里是不支持的如果你同时用了旧文档和新代码也会发现配置不生效这时候需要查阅当前版本的配置说明核对一下。在我的实际经验里这类问题九成是环境变量没加载进当前进程剩下的一成是变量名对不上。重启服务前先确认这两点能省掉不少排查时间。6.3 调研结果为空或信息量不足任务跑完报告生成出来了但内容很空或者围绕同一个点反复说这种情况主要和搜索环节有关。一种可能是搜索服务返回的结果相关性差另一种可能是网页抓取环节大面积失败材料没进来后续步骤只能“无米下锅”。排查时先打开执行日志看搜索环节返回了多少条结果、抓取成功了多少条。如果失败率高可以看具体错误信息超时、被限流、被反爬拦截原因不同应对方式不同。常见调整包括更换搜索服务源、降低单次任务的查询密度、调长超时时间。对于网页抓取被拦截的情况可以修改默认的抓取请求头让它更像真实浏览器的访问行为。但要注意合理配置抓取频率避免给目标站点带去不必要的压力。信息采集合规始终是优先考虑的问题不应对目标站点做激进的高频抓取。6.4 常见错误速查表现象常见原因处理思路启动时提示无法连接模型服务模型服务地址/密钥未生效检查环境变量、确认服务重启任务提交后长时间没有日志输出模型服务响应超时或 API 限流查看模型服务状态、检查超时配置搜索环节全部失败搜索服务限流或密钥失效更换备用搜索源、确认密钥有效报告语言不符合预期未明确指定输出语言在研究主题中追加语言要求输出目录没有文件任务未执行成功查看任务状态与日志排查部分引用来源缺失抓取环节失败率高优化请求头、调参重试策略7. 提升调研质量的一些经验DeerFlow 跑出来的结果质量并不只是由模型决定的。多个环节的配置和输入方式都会直接影响最终报告的水平。这里说几个实际调优的心得。研究主题的写法比想象中更关键。把主题写得具体一点效果立竿见影。比如你想调研分布式数据库的存储引擎单纯写“分析分布式数据库存储引擎”会让整个调研方向发散但写成“对比 LSM-Tree 和 BTree 在分布式数据库中的应用侧重写入性能和空间放大给出典型应用案例”之后规划和搜索环节都会聚焦得多报告质量提升明显。我个人的习惯是主题描述里把自己当成年底写汇报的人先说背景再说关注点最后说希望报告中回答的问题。这样跑出来的报告基本不需要大幅返工。模型选择上规划模块值得给较强的模型。规划是整个流程的“定调者”规划做偏了后面执行和审查都是在错误方向上使劲。审查模块同样建议给强模型它的工作方式和人类审稿人很像。草稿模块可以考虑用中档模型它的任务是在给定材料下做总结归纳容错度相对高一些。跑完第一轮之后不要急着用结果。把日志里的规划内容、搜索词记录、各章节引用来源都翻一遍能发现很多有意思的信息。比如你会发现某个搜索词效果不佳于是在后续任务里主动调整主题描述里的关键词设置或者给执行模块补充背景信息这些都会直接体现在报告质量上。8. 写到后面想说的话如果用一句话来评价 DeerFlow我觉得它是一个“把调研这个抽象目标拆成可执行流水线”的框架而且拆得足够细细到每个环节都有日志、每个环节都可以干预。对想深入智能体应用而不只是停留在调 API 层面的人来说它是一份很好的参考代码。进程跑起来之后围观四个角色在管道里依次作业的感觉和单纯从接口拿一个 JSON 回包是完全不同的体验。刚开始用的时候别把目标定太大。选一个垂直的小方向先跑通链路确认日志、报告、JSON 产物都符合预期了再去横向扩展。我见过太多人跑第一次就上大而全的题目最后输出报告不理想又不知道是哪一步的问题很容易劝退。后面如果有时间我还计划把整套框架迁移到自己的私有化环境中运行接入内部的文档库和知识库作为搜索源之一。到时候各个模块的接入方式、接口数据结构改动这些应该又是一篇可以聊的内容。这次先把基础链路和相关配置讲清楚也算是一个从 0 到 1 的完整记录了。