Agent 框架 08:DeerFlow——字节跳动 Deep Research 深度研究框架架构拆解

2025 年初,OpenAI Deep Research 与 Perplexity Deep Research 的发布引发了业界广泛关注:面对一个宏大而复杂的问题,AI 不再仅仅依赖单次模型推理给出简短答案,而是能够像一位资深行业分析师一样,自主规划数十个研究子方向,进行多轮网络检索、阅读上百篇网页长文、提取关键论据,并在 10~30 分钟内产出一篇结构严谨、数据详实且带标注引用的长篇万字研报。

这类商业产品虽然体验惊艳,但属于完全闭源的 SaaS 云端黑盒,企业无法将其接入内部私有数据,也无法将核心敏感数据送往境外。字节跳动开源的 DeerFlow(GitHub 仓库:bytedance/deer-flow)正是一个能够完全私有化部署的开源深度研究框架。更有意思的是,DeerFlow 底层基于 LangGraph 构建,是业内“用通用图框架构建垂类复杂 Agent”的极佳工程范本。


核心系统架构:多智能体协作拓扑

在 DeerFlow 中,完成一次深度研究绝非简单的“搜索 + 总结”,而是通过一套多角色协同的分层图拓扑进行驱动:

核心智能体角色分工

角色 核心职责 模型选型考量
Coordinator Agent 前置把关,判断用户问题是否值得启动高成本的深度检索流 强调速度:GPT-4o-mini / 豆包 Lite
Planner Agent 分析研究广度与深度,按相互独立原则拆解研究提纲 强调规划与推理:o3-mini / DeepSeek-R1
Researcher Agent 针对单一提纲生成定向搜索词,调用 API 抓取并精简信息 强调长上下文阅读与抗噪:Claude 3.5 Sonnet / 豆包 Pro
Writer Agent 汇总所有研究员事实,组织章节脉络,生成符合专业标准的排版与引用 强调文风与长文连贯度:GPT-4o / Claude 3.5 Sonnet

环境配置与模型双轨制

DeerFlow 在设计上采用了“双模型分工”模式(基础模型处理长文本提取,深度推理模型负责任务拆解与逻辑归纳):

1
2
3
git clone https://github.com/bytedance/deer-flow.git
cd deer-flow
pip install -r requirements.txt

核心配置文件 conf.yaml 示范:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 通用基础模型 (负责爬虫数据清洗、常规生成)
BASIC_MODEL:
base_url: "https://api.openai.com/v1"
model: "gpt-4o"
api_key: "sk-your-openai-key"

# 强逻辑推理模型 (负责前置提纲规划与最终论证)
REASONING_MODEL:
base_url: "https://api.openai.com/v1"
model: "o3-mini"
api_key: "sk-your-openai-key"

# 外部搜索服务配置 (支持 Tavily、Serper、DuckDuckGo)
SEARCH_API: "tavily"
TAVILY_API_KEY: "tvly-your-api-key"

核心流程剖析:基于 LangGraph 的状态图编排

下面通过精简的代码逻辑,展示 DeerFlow 如何利用 LangGraph 的 StateGraph 和 TypedDict 管理跨节点状态流转:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
import operator
from typing import TypedDict, Annotated, List
from langgraph.graph import StateGraph, END

# 1. 定义全链路共享的全局状态契约
class DeepResearchState(TypedDict):
user_input: str # 原始课题
is_deep_needed: bool # 是否启动深度研究
research_plan: List[str] # 拆解出的子任务清单
search_results: Annotated[List[str], operator.add] # 累加各研究员的事实
final_report: str # 最终输出的 Markdown

# 2. Coordinator 节点:意图路由
def coordinator_node(state: DeepResearchState) -> dict:
prompt = f"判断以下问题是否需要启动深度网络研究(涉及多方对比、最新动态或复杂行业):{state['user_input']}"
# 假设 LLM 返回布尔判定
return {"is_deep_needed": True}

# 3. Planner 节点:拆解子任务提纲
def planner_node(state: DeepResearchState) -> dict:
question = state["user_input"]
prompt = f"""请将以下课题拆解为 3~4 个相互独立的子研究方向,每行一条:
课题:{question}"""
# 模拟 LLM 拆解出的研究提纲
sub_tasks = [
"1. 核心技术路线与技术成熟度现状",
"2. 全球主要头部厂商的量产时间表与产能规划",
"3. 成本瓶颈、供应链挑战与未来商业化预测",
]
return {"research_plan": sub_tasks}

# 4. Researcher 节点:多轮检索与事实蒸馏
def researcher_node(state: DeepResearchState) -> dict:
distilled_findings = []
for task in state["research_plan"]:
# 实际逻辑中调用 Tavily 搜索并用 LLM 摘要
summary = f"【研究方向:{task}】\n- 事实 1: 产业界在特定材料方案取得突破。\n- 事实 2: 预计 2027 年实现规模化装车。"
distilled_findings.append(summary)
return {"search_results": distilled_findings}

# 5. Writer 节点:长文结构化归纳
def writer_node(state: DeepResearchState) -> dict:
context = "\n\n".join(state["search_results"])
prompt = f"""基于以下各维度的详细事实输入,为课题 '{state['user_input']}' 撰写一份深度专业报告:
{context}

报告结构要求:
1. 报告概述与执行摘要
2. 核心技术与产业现状
3. 关键竞争格局与时间表
4. 综合结论与未来展望"""

# 实际调用强写作模型合成
generated_report = "# 深度研究报告\n\n## 1. 报告概述\n..."
return {"final_report": generated_report}

# 6. 拓扑装配
workflow = StateGraph(DeepResearchState)
workflow.add_node("coordinator", coordinator_node)
workflow.add_node("planner", planner_node)
workflow.add_node("researcher", researcher_node)
workflow.add_node("writer", writer_node)

workflow.set_entry_point("coordinator")
workflow.add_edge("coordinator", "planner")
workflow.add_edge("planner", "researcher")
workflow.add_edge("researcher", "writer")
workflow.add_edge("writer", END)

app = workflow.compile()

前端全栈交互:Next.js Web UI

DeerFlow 不仅是一个纯后端脚本,它还配套提供了一个基于 Next.js 的全栈 Web 控制台:

1
2
3
4
cd web
npm install
npm run dev
# 浏览器打开 http://localhost:3000

前端界面重点解决了长任务等待过程中的用户体验问题:

  • 实时阶段动效:可视化展示当前正在处于“提纲规划中”、“搜索节点 2 数据抓取中”还是“正在合成第三章节”。
  • 流式事实呈现:研究员抓取到的关键引用链接和网页摘要实时滚动展示,让用户确信 Agent 并没有死锁或偷懒。
  • 研报一键导出:支持直接导出排版优美的 Markdown 或 PDF 格式文档。

企业级私有化扩展:接入内部知识源

在企业落地时,最有价值的往往是内网的 Confluence、知识库或自建 ElasticSearch。DeerFlow 支持轻量级重写检索工具适配器:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
from src.tools.base_search import BaseSearchTool

class EnterpriseKBSearchTool(BaseSearchTool):
"""自定义接入企业内网知识库"""

def search(self, query: str, max_results: int = 5) -> list[dict]:
# 访问内网向量库或内部搜索引擎
resp = internal_search_client.query(query, limit=max_results)
return [
{
"title": doc.title,
"content": doc.summary,
"url": f"https://wiki.corp.internal/{doc.id}",
}
for doc in resp.items
]

选型对比:自建 LangGraph vs 直接使用 DeerFlow

考量维度 直接基于 DeerFlow 二次开发 自己从零用 LangGraph 编写
启动速度 极快(已有成熟提纲、提示词与 Web 界面) 慢(需要从头打磨长文本处理与流式交互)
定制自由度 依赖其既定的 4 角色分工结构 完全自由,可随心设计更复杂的条件审校分支
工程成熟度 经过字节跳动内部实际测试,错误重试完善 取决于团队自身的 LangGraph 架构功底
学习价值 极高:直接学习“如何用 LangGraph 写大项目” 适合对每个图节点生命周期进行微观掌控

优缺点分析与工程选型边界

核心优势

  1. 开源可私有化:填补了类似 OpenAI Deep Research 无法私有化部署和数据合规出境的空白。
  2. 架构清爽规范:依托 LangGraph 状态图,没有自造晦涩的私有图抽象,代码可读性极强。
  3. 开箱即用的前端:省去了算法团队开发可演示前端界面(Demo UI)的时间。

现实痛点与妥协

  1. 搜索 API 成本较高:深度研究通常需要调用 10~30 次外部搜索请求,依赖商用 Tavily/Serper 计费接口。
  2. 端到端耗时较长:一次完整的高质量调研往往需要 3~5 分钟以上,必须依靠后台异步队列和 WebSocket 流式通知。

关联导航