DeerFlow：字节跳动开源的深度智能体研究框架

为什么需要 DeerFlow：让「深度研究」从人工苦力变成自动化流水线

传统方式有两类痛点。第一类是直接问大模型：单轮回答依赖模型记忆，缺乏最新信息，且面对「某行业 2025 年政策变化及影响」这类开放问题，输出往往泛泛而谈、没有来源。第二类是 RAG（检索增强生成，即先检索资料库再把相关内容拼进提示词让模型回答）：它只做「一次检索 + 一次生成」，不会多轮追问、不会主动拆解子问题，覆盖面和深度都有限。而真正高质量的深度研究——搜索几十个网页、交叉比对、归纳成文——过去只能靠人工，耗时数小时甚至数天。

DeerFlow 的解法是把研究过程建成显式流水线：先由模型规划研究思路并拆解子问题，再并行执行多轮搜索，读取并摘要网页内容，最后汇总成带引用的报告。整个过程由「思考-行动-观察」（TAO）循环驱动——模型判断信息是否足够，不够就继续搜、继续读，够了才进入写作。这套设计让大模型从「答题者」变成「研究者」，回答质量显著提升且每一步都可追溯。

与同类工具的气质差异在于：相比 LangGraph 这类通用 Agent 编排框架，DeerFlow 把研究流程做成了开箱即用的产品，开发者不需要自己设计状态机和节点；相比 OpenAI Deep Research 这类闭源 SaaS，它开源、模型中立、自托管，成本和数据合规完全可控。代价是它只擅长「研究」这一类任务，不是万能的 Agent 底座。

安装与环境配置：3 步就绪

步骤一：拉取代码并安装依赖。 需要 Python 3.10+。建议先创建虚拟环境再安装，避免污染系统 Python。

步骤二：配置 .env 环境变量。 DeerFlow 的环境变量全部集中在 .env 文件（复制 .env.example 得到）。必须配置两类凭据：LLM（大模型）接口与本机的搜索服务。下面是兼容 OpenAI 接口的配置形态，DeepSeek、Kimi、通义等国产模型通过改 LLM_BASE_URL 接入；具体键名以仓库 .env.example 中注释为准。

步骤三：启动并验证。 用 Streamlit 启动 Web 界面，浏览器打开 http://localhost:8501，在侧边栏选择模型中可用的模型（预置列表来自 config/default_models.py），提交一个简单问题并选择 Simple 模式。能正常输出报告即说明安装成功。

git clone https://github.com/ByteDance-Seed/DeerFlow.gitcd DeerFlowpython -m venv .venvsource .venv/bin/activatepip install -r requirements.txt

cp .env.example .env# 编辑 .env：# LLM_MODEL=deepseek-v3# LLM_API_KEY=sk-你的密钥# LLM_BASE_URL=https://api.deepseek.com/v1# SEARCH_PROVIDER=tavily# SEARCH_API_KEY=tvly-你的密钥

streamlit run app.py# 浏览器访问 http://localhost:8501

快速上手：10 分钟跑通第一个研究报告

最小可用流程的思路是「不写一行业务代码，只做选择和配置」：DeerFlow 的 Web 界面已封装完整的 Deep/Simple 双模式，使用者只负责选题、选模型、选模式、看结果。

1. 启动服务：执行 streamlit run app.py，在浏览器打开 Web 界面。

2. 配置模型：在模型选择区分提供商和模型名。首次使用务必确认 .env 中对应 API Key 有效，界面上的模型列表只是预置项，不包含任何厂商凭据。

3. 选择模式：轻量事实核对用 Simple（单轮搜索，快）；开放式研究课题用 Deep（多轮搜索 + 阅读 + 子问题拆解，慢但深）。

4. 输入研究问题：建议用「为 X 做一个决策所需的背景调研」这类句式，例如「对比 A 与 B 两款数据库在金融场景的适用性」。

5. 提交并等待：Deep 模式通常需要数分钟。界面按环节展示中间过程（思考计划、搜索摘要、阅读笔记），结束后输出完整报告，报告中保留引用来源链接，可下载保存。

进阶技巧：在 config/config.py 中可以调整搜索轮数、单轮结果条数、阅读网页数量上限等参数。想要更快的 Deep 模式，可降低搜索轮数或换用更快的模型（如 gpt-4o-mini、deepseek-v3）；想要更严的报告，可调大阅读轮数。

核心能力详解：4 大支柱

支柱一 · TAO 推理循环（Thought-Action-Observation）。 TAO 是 DeerFlow 的方法论核心：模型先「思考」当前需要什么信息，再「行动」（执行搜索或打开网页），然后「观察」结果并判断信息是否足够。不足则带着新问题进入下一轮循环，直到达到终止条件才交给写作模块。这个循环保证了研究不是一锤子买卖，而是随信息逐步收敛的迭代过程。

支柱二 · 四 Agent 研究流水线与双模式。 Deep 模式下工作流由四个角色分工：Agent T 负责规划与拆解子问题，Agent S 负责将子问题转化为搜索词并调用搜索 API，Agent R 负责阅读并抽取网页关键内容，Agent W 负责把各子问题的结论整合成结构化报告。Simple 模式砍掉多轮拆解，用单次「搜索 + 阅读 + 写作」快速响应简单查询。两条路径共用同一套模型和搜索配置，按需切换。

支柱三 · 模型中立与多搜索源适配。 DeerFlow 采用 OpenAI 兼容的模型接入协议，因此 OpenAI、DeepSeek、Kimi、通义、GLM、Anthropic 等都能通过改模型名、API Key、Base URL 三件套接入，不绑定任何一家。搜索侧抽象出 Provider 接口，官方已适配 Tavily、博查、有道、DuckDuckGo 等；插件体系允许开发者注册自定义搜索源或工具，扩展研究流水线的能力边界。

支柱四 · 报告生成与引用体系。 研究报告不是模型的自由发挥，而是基于各轮搜索与阅读的中间产物汇总生成。报告中的关键结论附带来源链接，便于回溯核验。产出支持在界面直接下载，适合直接进入文档库或人工复核流程。这套「可追溯」设计是它区别于普通问答机器人的关键——结论错了能定位到是哪个信源导致的。

生产部署与监控：从上线到运维

部署方式一：单机进程托管。 官方默认入口是 Streamlit Web 服务，监听 8501 端口。生产环境建议用 systemd 将 streamlit run app.py 托管为常驻服务，实现开机自启与崩溃重启；如需公网访问，在前面加 Nginx 反向代理并做访问控制（如 Basic Auth 或内网 VPN），避免研究接口裸奔。每请求的模型调用和搜索请求都要经公网，提前确认服务器与目标 API 的网络连通性及防火墙白名单。

部署方式二：API 服务模式。 仓库提供 API 服务脚本（server.py，基于 FastAPI），可以把研究能力封装成内部 REST 服务供上层产品调用。典型做法是提交研究任务后异步轮询结果，避免长连接阻塞。该模式适合把 DeerFlow 嵌入已有的知识库、情报系统或办公自动化流程，而非让用户直接接触 Streamlit 界面。接入前用 Simple 模式做连通性冒烟测试。

可观测性。 DeerFlow 按环节输出日志（思考、搜索、阅读、写作），排查失败时先看日志定位是模型调用失败、搜索 API 失败还是阅读环节超时。成本方面，LLM 调用是主要开销，Deep 模式多轮检索的 token 消耗远高于 Simple，记下每类问题的平均耗时与 token 量再定预算。搜索 API 免费额度普遍偏紧（如 Tavily 每月有限免费次数），生产环境建议配置多 Provider 互为兜底，并对配额设置监控告警。最后，对产出报告做人工抽检，比对引用来源与结论的一致性，这是评估系统质量最直接的手段。

<p class="para-label">避坑清单：</p>

<ul class="dash-list"><li>只配 LLM Key、漏配搜索服务：Deep 模式的搜索环节会持续失败或空转，整个流程卡死；务必配置至少一个搜索 API Key，并确认免费配额充足。</li><li>换模型只改 UI 下拉、不同步 .env：模型名、API Key、Base URL 三者必须匹配，否则鉴权失败或反复超时；先在 Simple 模式用一句话验证连通性。</li><li>Deep 模式时间与成本失控：单次深度研究视问题复杂度可能耗时数分钟到十几分钟、消耗大量 token；上线前统计 10-20 条真实查询的平均成本，并在 config 中限定搜索轮数上限。</li><li>把带引用的报告当权威结论：引用来自自动抽取的信源，低质网页也会被纳入；关键决策数据必须人工二次核验后再使用。</li></ul>

版本迭代

DeerFlow 于 2025 年 9 月首次开源，凭借「深度研究」定位迅速进入 GitHub Trending，随后以高频率小版本迭代，主线从「跑通研究流程」转向「工程稳定性与可扩展生态」：早期集中修复多模型、多搜索源接入问题，v0.2.0 引入插件体系作为第二次关键跳跃（截至训练数据，可能已有更新版本）。

AI 应用场景

常见误区

面试题

参考来源

• webpageDeerFlow GitHub 仓库官方源码、README 文档与使用指南（即官方文档主站）
• webpageByteDance Seed 开源组织字节跳动 Seed 团队全部开源项目入口，了解生态全景