deer-flow

🦌 DeerFlow

English | 简体中文 | 日本語

源自开源，回馈开源。

DeerFlow（Deep Exploration and Efficient Research **Flow，深度探索与高效研究流程）是一个由社区驱动的深度研究框架，基于开源社区的卓越成果构建。我们的目标是将语言模型与网页搜索、网页抓取和 Python 代码执行等专用工具相结合，同时回馈让这一切成为可能的社区。

请访问我们的官方网站了解更多详情。

演示

视频

https://github.com/user-attachments/assets/f3786598-1f2a-4d07-919e-8b99dfa1de3e

在此演示中，我们展示了如何使用 DeerFlow：

• 无缝集成 MCP 服务
• 执行深度研究流程，并生成包含图片的综合报告
• 根据生成的报告创建播客音频

回放

• 埃菲尔铁塔与最高建筑相比有多高？
• GitHub 上最热门的仓库有哪些？
• 撰写一篇关于南京传统菜肴的文章
• 如何装饰出租公寓？
• 访问我们的官方网站，探索更多回放。

---

📑 目录

• 🚀 快速开始
• 🌟 功能
• 🏗️ 架构
• 🛠️ 开发
• 🗣️ 文本转语音集成
• 📚 示例
• ❓ 常见问题
• 📜 许可证
• 💖 致谢
• ⭐ Star 历史

快速开始

DeerFlow 使用 Python 开发，并配有使用 Node.js 编写的 Web UI。为确保安装过程顺利，我们建议使用以下工具：

推荐工具

• uv: 简化 Python 环境和依赖管理。uv 会自动在根目录创建虚拟环境，并为你安装所有必需的软件包，无需手动安装 Python 环境。

• nvm: 轻松管理多个版本的 Node.js 运行时。

• pnpm: 安装和管理 Node.js 项目的依赖。

环境要求

请确保系统满足以下最低要求：

• Python: 版本 3.12+
• Node.js: 版本 22+

安装

# Clone the repository
git clone https://github.com/bytedance/deer-flow.git
cd deer-flow

# Install dependencies, uv will take care of the python interpreter and venv creation, and install the required packages
uv sync

# Configure .env with your API keys
# Tavily: https://app.tavily.com/home
# Brave_SEARCH: https://brave.com/search/api/
# volcengine TTS: Add your TTS credentials if you have them
cp .env.example .env

# See the 'Supported Search Engines' and 'Text-to-Speech Integration' sections below for all available options

# Configure conf.yaml for your LLM model and API keys
# Please refer to 'docs/configuration_guide.md' for more details
cp conf.yaml.example conf.yaml

# Install marp for ppt generation
# https://github.com/marp-team/marp-cli?tab=readme-ov-file#use-package-manager
brew install marp-cli

你也可以选择通过 pnpm 安装 Web UI 依赖：

cd deer-flow/web
pnpm install

配置

更多详情请参阅配置指南。

说明

启动项目之前，请仔细阅读指南，并根据你的具体设置和需求更新配置。

控制台 UI

运行项目最快捷的方式是使用控制台 UI。

# Run the project in a bash-like shell
uv run main.py

Web UI

本项目还包含 Web UI，提供更动态、更具吸引力的交互体验。

说明

你需要先安装 Web UI 的依赖。

# Run both the backend and frontend servers in development mode
# On macOS/Linux
./bootstrap.sh -d

# On Windows
bootstrap.bat -d

打开浏览器并访问 http://localhost:3000，即可探索 Web UI。

在 web 目录中了解更多详情。

支持的搜索引擎

DeerFlow 支持多种搜索引擎，可通过 .env 文件中的 SEARCH_API 变量进行配置：

• Tavily（默认）：专为 AI 应用打造的搜索 API

  • 需要在 .env 文件中设置 TAVILY_API_KEY
  • 在此注册：https://app.tavily.com/home

• DuckDuckGo：注重隐私的搜索引擎

  • 无需 API 密钥

• Brave Search：注重隐私且具备高级功能的搜索引擎

  • 需要在 .env 文件中设置 BRAVE_SEARCH_API_KEY
  • 在此注册：https://brave.com/search/api/

• Arxiv：面向学术研究的科学论文搜索

  • 无需 API 密钥
  • 专用于搜索科学和学术论文

如需配置首选搜索引擎，请在 .env 文件中设置 SEARCH_API 变量：

# Choose one: tavily, duckduckgo, brave_search, arxiv
SEARCH_API=tavily

功能特性

核心能力

• 🤖 大模型集成
  • 支持通过 litellm 集成大多数模型。
  • 支持 Qwen 等开源模型
  • 兼容 OpenAI 的 API 接口
  • 针对不同任务复杂度的多层级大模型系统

工具和 MCP 集成

• 🔍 搜索与检索

  • 通过 Tavily、Brave Search 等进行网页搜索
  • 使用 Jina 抓取网页
  • 高级内容提取

• 🔗 MCP 无缝集成

  • 扩展私有域访问、知识图谱、网页浏览等能力
  • 便于集成各种研究工具和方法

人机协作

• 🧠 人在回路

  • 支持使用自然语言交互式修改研究计划
  • 支持自动接受研究计划

• 📝 报告后期编辑

  • 支持类似 Notion 的区块编辑
  • 支持 AI 优化，包括 AI 辅助润色、缩短句子和扩写
  • 基于 tiptap

内容创作

• 🎙️ 播客和演示文稿生成
  • AI 驱动的播客脚本生成和音频合成
  • 自动创建简单的 PowerPoint 演示文稿
  • 可自定义模板，打造个性化内容

架构

DeerFlow 实现了一个模块化多 Agent 系统架构，旨在自动化研究和代码分析。系统基于 LangGraph 构建，采用灵活的状态式工作流，各组件通过定义明确的消息传递系统进行通信。

在 deerflow.tech 查看实时演示

系统采用精简的工作流，包含以下组件：

1. 协调器：管理工作流生命周期的入口

   • 根据用户输入启动研究流程
   • 适时将任务委派给规划器
   • 作为用户与系统之间的主要交互界面

2. 规划器：负责任务分解和规划的策略组件

   • 分析研究目标并创建结构化执行计划
   • 判断现有上下文是否充足，或是否需要进一步研究
   • 管理研究流程，并决定何时生成最终报告

3. 研究团队：由执行计划的专业 Agent 组成：

   • 研究员：使用网页搜索引擎、网页抓取工具，甚至 MCP 服务等工具进行网页搜索和信息收集。
   • 编码员：使用 Python REPL 工具处理代码分析、执行和技术任务。 每个 Agent 都可使用针对其职责优化的特定工具，并在 LangGraph 框架内运行。

4. 报告生成器：处理研究结果的最终阶段

   • 汇总研究团队的发现
   • 处理并整理收集到的信息
   • 生成全面的研究报告

文本转语音集成

DeerFlow 现已支持文本转语音（TTS）功能，可将研究报告转换为语音。此功能使用 volcengine TTS API，将文本转换为高质量音频。您还可以自定义语速、音量和音调等设置。

使用 TTS API

您可以通过 /api/tts 端点使用 TTS 功能：

# Example API call using curl
curl --location 'http://localhost:8000/api/tts' \
--header 'Content-Type: application/json' \
--data '{
    "text": "This is a test of the text-to-speech functionality.",
    "speed_ratio": 1.0,
    "volume_ratio": 1.0,
    "pitch_ratio": 1.0
}' \
--output speech.mp3

开发

测试

运行测试套件：

# Run all tests
make test

# Run specific test file
pytest tests/integration/test_workflow.py

# Run with coverage
make coverage

代码质量

# Run linting
make lint

# Format code
make format

使用 LangGraph Studio 调试

DeerFlow 使用 LangGraph 构建工作流架构。您可以使用 LangGraph Studio 实时调试和可视化工作流。

在本地运行 LangGraph Studio

DeerFlow 包含一个 langgraph.json 配置文件，用于定义 LangGraph Studio 的图结构和依赖项。此文件指向项目中定义的工作流图，并自动从 .env 文件加载环境变量。

Mac

# Install uv package manager if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies and start the LangGraph server
uvx --refresh --from "langgraph-cli[inmem]" --with-editable . --python 3.12 langgraph dev --allow-blocking

Windows / Linux

# Install dependencies
pip install -e .
pip install -U "langgraph-cli[inmem]"

# Start the LangGraph server
langgraph dev

启动 LangGraph 服务后，您会在终端中看到几个 URL：

• API： http://127.0.0.1:2024
• Studio UI： https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024
• API 文档： http://127.0.0.1:2024/docs

在浏览器中打开 Studio UI 链接，即可访问调试界面。

使用 LangGraph Studio

在 Studio UI 中，您可以：

1. 可视化工作流图，并查看各组件如何连接
2. 实时跟踪执行过程，查看数据如何在系统中流动
3. 检查工作流每个步骤的状态
4. 查看各组件的输入和输出，以调试问题
5. 在规划阶段提供反馈，完善研究计划

在 Studio UI 中提交研究主题后，您可以查看整个工作流的执行过程，包括：

• 创建研究计划的规划阶段
• 可修改计划的反馈循环
• 各个章节的研究和撰写阶段
• 最终报告生成

示例

以下示例展示了 DeerFlow 的功能：

研究报告

1. OpenAI Sora 报告 - 分析 OpenAI 的 Sora AI 工具

   • 讨论其功能、访问方式、提示词工程、局限性和伦理考量
   • 查看完整报告

2. Google 的 Agent to Agent Protocol 报告 - 概述 Google 的 Agent to Agent（A2A）协议

   • 讨论该协议在 AI Agent 通信中的作用，以及它与 Anthropic 的 Model Context Protocol（MCP）之间的关系
   • 查看完整报告

3. 什么是 MCP？ - 全面分析“MCP”一词在多种语境下的含义

   • 探讨 AI 领域的 Model Context Protocol、化学领域的磷酸一钙，以及电子领域的微通道板
   • 查看完整报告

4. 比特币价格波动 - 分析近期比特币价格走势

   • 考察市场趋势、监管影响和技术指标
   • 根据历史数据提供建议
   • 查看完整报告

5. 什么是 LLM？ - 深入探讨大语言模型

   • 讨论架构、训练、应用和伦理考量
   • 查看完整报告

6. 如何使用 Claude 进行深度研究？ - 使用 Claude 进行深度研究的最佳实践和工作流

   • 涵盖提示词工程、数据分析以及与其他工具的集成
   • 查看完整报告

7. 医疗健康领域的 AI 采用：影响因素 - 分析推动医疗健康领域采用 AI 的因素

   • 讨论 AI 技术、数据质量、伦理考量、经济评估、组织准备情况和数字基础设施
   • 查看完整报告

8. 量子计算对密码学的影响 - 分析量子计算对密码学的影响

   • 讨论经典密码学的漏洞、后量子密码学和抗量子密码解决方案
   • 查看完整报告

9. Cristiano Ronaldo 的表现亮点 - 分析 Cristiano Ronaldo 的表现亮点

   • 讨论他的职业生涯成就、国际比赛进球和各类比赛中的表现
   • 查看完整报告

要运行这些示例或创建自己的研究报告，可以使用以下命令：

# Run with a specific query
uv run main.py "What factors are influencing AI adoption in healthcare?"

# Run with custom planning parameters
uv run main.py --max_plan_iterations 3 "How does quantum computing impact cryptography?"

# Run in interactive mode with built-in questions
uv run main.py --interactive

# Or run with basic interactive prompt
uv run main.py

# View all available options
uv run main.py --help

交互模式

应用现已支持交互模式，内置问题涵盖英语和中文：

1. 启动交互模式：

   uv run main.py --interactive
   

2. 选择偏好的语言（English 或 中文）

3. 从内置问题列表中选择，或选择提问选项来提出自己的问题

4. 系统将处理你的问题并生成全面的研究报告

人在回路

DeerFlow 包含一个人在回路机制，允许你在执行研究计划之前进行审阅、编辑和批准：

1. 计划审阅：启用人在回路后，系统会在执行前显示生成的研究计划供你审阅

2. 提供反馈：你可以：

   • 回复 [ACCEPTED] 以接受计划
   • 提供反馈来编辑计划（例如，[EDIT PLAN] Add more steps about technical implementation）
   • 系统会采纳你的反馈并生成修订后的计划

3. 自动接受：你可以启用自动接受以跳过审阅流程：

   • 通过 API：在请求中设置 auto_accepted_plan: true

4. API 集成：使用 API 时，你可以通过 feedback 参数提供反馈：

   {
     "messages": [{"role": "user", "content": "What is quantum computing?"}],
     "thread_id": "my_thread_id",
     "auto_accepted_plan": false,
     "feedback": "[EDIT PLAN] Include more about quantum algorithms"
   }
   

命令行参数

该应用支持多个命令行参数，用于自定义其行为：

• query：要处理的研究查询（可以包含多个单词）
• --interactive：以交互模式运行，并使用内置问题
• --max_plan_iterations：规划周期的最大次数（默认：1）
• --max_step_num：研究计划中的最大步骤数（默认：3）
• --debug：启用详细的调试日志

常见问题

更多详情请参阅 FAQ.md。

许可证

本项目采用开源方式发布，并遵循 MIT License。

致谢

DeerFlow 建立在开源社区的卓越成果之上。我们由衷感谢所有为 DeerFlow 的诞生贡献力量的项目和贡献者。诚然，我们站在巨人的肩膀上。

谨向以下项目致以诚挚谢意，感谢它们作出的宝贵贡献：

• LangChain：其出色的框架为我们的 LLM 交互和链提供了支持，实现了无缝集成并丰富了功能。
• LangGraph：其创新的多 Agent 编排方式，对实现 DeerFlow 复杂的工作流发挥了重要作用。

这些项目充分展现了开源协作的变革力量，我们很荣幸能在它们的基础上继续前行。

核心贡献者

谨向 DeerFlow 的核心作者致以诚挚谢意。他们的愿景、热情与奉献让这个项目得以诞生：

• Daniel Walnut
• Henry Li

你们坚定的投入和专业能力是 DeerFlow 成功的推动力。我们很荣幸能由你们引领这段旅程。

星标历史