1. 项目概述:DeerFlow 是什么?
DeerFlow 是字节跳动开源的一款面向深度调研场景的多智能体协作框架。它通过预置的 Agent 团队和 LangGraph 驱动的工作流引擎,将复杂的调研任务自动化、流程化。简单来说,它就像是一个由多个 AI 专家组成的调研小组,能够自动完成从需求理解到最终报告生成的全过程。
提示:DeerFlow 的核心价值在于将传统上需要人工完成的调研工作流程化、自动化,特别适合需要处理大量信息来源的技术选型、竞品分析等场景。
与直接使用大模型进行问答不同,DeerFlow 强调调研过程的结构化和可追溯性。它会在调研过程中保留中间产物(如检索到的资料、分析笔记等),并确保最终报告中的每个结论都有明确的来源依据。这种设计使得调研结果更加可靠,也便于后续的验证和复用。
2. 核心架构解析
2.1 多智能体团队设计
DeerFlow 的核心是由多个专业 Agent 组成的协作团队,每个 Agent 都有明确的职责:
-
协调者 (Coordinator)
- 负责接收用户请求并初始化调研任务
- 协调各个 Agent 之间的工作流程
- 监控整体进度并在必要时进行干预
-
规划者 (Planner)
- 将用户需求拆解为具体的调研子任务
- 确定任务优先级和执行顺序
- 根据调研进展动态调整计划
-
研究员 (Researcher)
- 执行信息检索任务(支持多种数据源)
- 从原始资料中提取关键信息
- 生成结构化的调研发现(包含结论和引用)
-
程序员 (Coder)
- 执行代码验证和实验
- 分析技术方案的实现细节
- 提供技术可行性评估
-
报告生成器 (Reporter)
- 整合所有调研发现
- 生成结构化的最终报告
- 确保结论与证据的对应关系
2.2 LangGraph 工作流引擎
DeerFlow 使用 LangGraph 作为底层的工作流引擎,这种设计带来了几个关键优势:
-
状态管理:整个调研过程的状态被完整记录,包括当前进度、已收集的资料、中间分析结果等。
-
流程可视化:工作流可以直观地表示为有向图,便于理解和调试。
-
灵活扩展:新的 Agent 或工具可以方便地集成到现有工作流中。
-
错误恢复:当某个环节出现问题时,系统可以从最近的有效状态继续执行。
注意:理解 LangGraph 的状态机模型对于深度定制 DeerFlow 工作流非常重要。建议在实际部署前先通过官方文档熟悉其基本概念。
3. 环境准备与安装
3.1 硬件与系统要求
在开始部署 DeerFlow 前,请确保你的环境满足以下要求:
-
操作系统:
- Linux (推荐 Ubuntu 20.04+)
- macOS (10.15+)
- Windows (需要 WSL2)
-
硬件配置:
- CPU: 4核以上
- 内存: 8GB 以上
- 存储: 至少 10GB 可用空间
-
网络连接:
- 稳定的互联网连接
- 能够访问 GitHub 和所选 LLM 提供商的 API
3.2 软件依赖安装
-
基础工具:
bash复制# 安装 Git sudo apt update && sudo apt install -y git # 安装 Python 3.10+ sudo apt install -y python3.10 python3.10-venv python3.10-dev -
获取 DeerFlow 源代码:
bash复制# 从 GitHub 克隆仓库 git clone https://github.com/bytedance/deer-flow.git cd deer-flow # 或者使用 GitCode 镜像(国内访问可能更快) # git clone https://gitcode.com/GitHub_Trending/de/deer-flow.git -
创建并激活虚拟环境:
bash复制python3.10 -m venv venv source venv/bin/activate
3.3 依赖安装与配置
-
安装 Python 依赖:
bash复制
pip install --upgrade pip pip install -r requirements.txt -
配置环境变量:
创建.env文件并配置必要的 API 密钥:bash复制# 示例 .env 配置 LLM_PROVIDER=openai LLM_API_KEY=your_api_key_here LLM_MODEL=gpt-4-turbo # 如果需要网络搜索功能 SEARCH_API_PROVIDER=serpapi SERPAPI_API_KEY=your_serpapi_key -
可选:Docker 部署:
如果项目提供了 docker-compose 文件,可以使用以下命令快速启动:bash复制
docker compose up -d
4. 运行第一个调研任务
4.1 启动服务
根据你的部署方式选择相应的启动命令:
-
直接运行:
bash复制
uvicorn deer_flow.api.main:app --host 0.0.0.0 --port 2026 -
通过 Docker:
bash复制
docker compose up -d
服务启动后,你可以通过以下方式验证是否运行正常:
- 访问
http://localhost:2026/docs查看 API 文档 - 或者直接发送测试请求:
bash复制
curl http://localhost:2026/api/health
4.2 发起调研请求
使用以下命令发起一个简单的调研任务:
bash复制curl -X POST "http://localhost:2026/api/langgraph/run" \
-H "Content-Type: application/json" \
-d '{
"query": "比较 Redis 和 MongoDB 在缓存场景下的性能特点",
"max_depth": 2,
"report_format": "markdown"
}'
请求参数说明:
query: 调研主题描述max_depth: 调研深度(控制Agent的递归调用次数)report_format: 输出报告格式(markdown/html)
4.3 监控与获取结果
-
获取任务状态:
bash复制curl "http://localhost:2026/api/langgraph/status?task_id=YOUR_TASK_ID" -
获取最终报告:
bash复制curl "http://localhost:2026/api/langgraph/report?task_id=YOUR_TASK_ID" -
获取中间结果:
bash复制curl "http://localhost:2026/api/langgraph/artifacts?task_id=YOUR_TASK_ID"
5. 实际应用场景示例
5.1 技术选型调研
场景:为新的微服务项目选择消息队列系统
DeerFlow 配置:
json复制{
"query": "比较 Kafka、RabbitMQ 和 NATS 在微服务架构中的适用性",
"criteria": [
"性能(吞吐量/延迟)",
"可靠性(消息持久化/故障恢复)",
"运维复杂度",
"社区生态"
],
"max_depth": 3
}
预期输出:
- 各消息队列在指定维度的对比表格
- 针对不同规模项目的推荐方案
- 相关性能测试数据的引用来源
5.2 竞品分析
场景:分析竞争对手产品的功能特点
DeerFlow 配置:
json复制{
"query": "分析 Notion、Confluence 和 ClickUp 的文档协作功能差异",
"focus_areas": [
"实时协作体验",
"模板生态系统",
"第三方集成",
"移动端支持"
],
"sources": ["official_docs", "user_reviews", "tech_articles"]
}
预期输出:
- 功能对比矩阵
- 用户评价摘要(正面/负面)
- 市场定位分析
5.3 学术文献综述
场景:收集某个研究领域的最新进展
DeerFlow 配置:
json复制{
"query": "收集2020年后关于联邦学习隐私保护技术的研究论文",
"constraints": {
"publication_years": ["2020", "2021", "2022", "2023"],
"venues": ["NeurIPS", "ICML", "AAAI"]
},
"output_format": "latex"
}
预期输出:
- 按技术方向分类的论文列表
- 各方法的核心贡献摘要
- 实验结果的横向比较
6. 高级配置与定制
6.1 工作流定制
DeerFlow 的工作流可以通过修改 workflow_definitions.py 进行定制:
-
添加新的 Agent:
python复制@agent(name="domain_expert") async def domain_expert_agent(state: dict): # 实现专业领域逻辑 return {"analysis": expert_analysis} -
修改工作流逻辑:
python复制def create_custom_workflow(): workflow = StateGraph(initial_state) # 添加节点 workflow.add_node("domain_analysis", domain_expert_agent) # 修改边逻辑 workflow.add_conditional_edges( "planner", decide_next_step, {"continue": "researcher", "expert": "domain_analysis"} ) return workflow
6.2 集成自定义工具
-
添加新的数据源:
python复制@tool(name="internal_wiki_search") async def search_internal_wiki(query: str): # 实现企业内部Wiki搜索 return search_results -
注册工具到 Agent:
python复制
researcher = ResearcherAgent( tools=[WebSearchTool(), ArxivTool(), InternalWikiTool()] )
6.3 性能优化技巧
-
缓存策略:
- 对频繁查询的外部数据实现本地缓存
- 使用 Redis 存储中间结果
-
并行执行:
python复制async def parallel_research(topics): tasks = [researcher.run(topic) for topic in topics] return await asyncio.gather(*tasks) -
LLM 调用优化:
- 对批量请求使用流式处理
- 设置合理的超时和重试策略
7. 常见问题与解决方案
7.1 部署问题
问题1:依赖安装失败
- 检查 Python 版本是否为 3.10+
- 确保系统已安装必要的开发工具包(如 build-essential)
问题2:服务启动后无法访问
- 检查防火墙设置
- 确认端口未被占用
- 查看服务日志排查具体错误
7.2 运行问题
问题1:调研任务卡住不动
- 检查 LLM API 是否可用
- 查看任务状态端点获取详细错误
- 适当降低
max_depth参数值
问题2:报告质量不理想
- 提供更明确的查询指令
- 调整 Planner 的提示词模板
- 增加相关度过滤条件
7.3 性能问题
问题1:任务执行时间过长
- 限制每个子任务的时间预算
- 优化网络请求的并行度
- 考虑使用更高效的 LLM 模型
问题2:API 调用超限
- 实现请求速率限制
- 使用指数退避重试策略
- 考虑本地模型替代方案
8. 最佳实践与经验分享
8.1 提示词工程技巧
-
明确调研目标:
- 避免模糊的描述,提供具体标准
- 示例:不要用"好的数据库",而是"支持水平扩展、具有强一致性的OLTP数据库"
-
结构化约束条件:
json复制{ "must_have": ["分布式事务", "SQL支持"], "nice_to_have": ["图形界面", "托管服务"] } -
结果格式要求:
- 明确指定报告的结构
- 示例:"包含执行摘要、技术对比表格、推荐理由三个部分"
8.2 团队协作模式
-
知识共享:
- 建立常用调研模板库
- 共享已验证的数据源配置
-
版本控制:
- 对重要调研结果进行版本管理
- 使用 Git 跟踪工作流定义变更
-
质量评审:
- 建立人工复核机制
- 收集反馈持续优化 Agent 表现
8.3 扩展应用场景
-
企业内部知识管理:
- 连接公司内部文档系统
- 自动化更新技术知识库
-
持续监测:
- 设置定期运行的监测任务
- 跟踪技术趋势变化
-
教育培训:
- 作为新员工培训工具
- 快速构建领域知识概览