🔬 格物 · Gewu Deep Research

一个开箱即用的多 Agent 深度研究系统 —— 主管调度 · 研究员并行 · 报告带引用 · 自带中文控制台

格物致知：让 AI 像一支研究团队一样，替你穷究一事

💭 格物致知，穷究一事

深度研究（Deep Research）是当下最热门的 AI Agent 应用之一。格物把它做成一套简单、可配置、完全开源的多智能体系统：你给它一个研究问题（比如「对比 OpenAI 和 Anthropic 的 AI 安全策略」），它会自动澄清问题、拆解课题、并行搜索互联网，最终交出一份带引用来源的深度研究报告——报告语言自动跟随提问语言。

用户提问 → AI 澄清问题 → 制定研究计划 → 多个子 Agent 并行搜索
    → 压缩研究结果 → 生成最终报告（带引用来源）

✨ 功能全景

🧠 多 Agent 协作编排 — 主管子图拆解调度 + 多个研究员子图并行 ReAct 搜索，模拟真实研究团队分工（deep_researcher.py）
🔄 全自动研究流水线 — 澄清 → 简报 → 并行检索 → 压缩 → 报告，全程无需人工干预
🧾 高质量引用 — 最终报告带来源引用，可追溯、可验证（final_report_generation）
🔀 多模型提供商 — init_chat_model() 一套代码切换 OpenAI / Anthropic / Google / DeepSeek / DashScope 等（configuration.py）
🔍 多搜索后端 — Tavily / OpenAI / Anthropic 原生网页搜索，或仅用 MCP（utils.py · get_search_tool）
🔌 MCP 工具生态 — 通过 Model Context Protocol 动态挂载数据库、API 等外部工具（utils.py · load_mcp_tools）
🈶 中文深度优化 — prompts_zh.py 中文提示词套件；中文提问 → 中文简报与中文报告
🛡️ 多层错误恢复 — 结构化输出自动重试、四厂商 Token 超限识别与截断重试、工具执行安全捕获（utils.py · is_token_limit_exceeded）
🖥️ 自研前端控制台 — React 18 + Vite：实时事件流、研究员卡片、流式报告渲染，并内置无后端也能跑的演示模式（frontend/）
🔐 平台级认证 — Supabase JWT 认证 + 资源级鉴权，部署到开放平台也安全（src/security/auth.py）

🏗️ 架构总览

flowchart TB
    U["👤 用户"] <--> FE

    subgraph FE["🖥️ 前端控制台 · React 18 + Vite + Tailwind :5173"]
        CON["🎮 ConsoleView<br/>实时研究控制台"]
        CFG["🎛️ ConfigPopover<br/>运行配置面板"]
        CARD["👥 WorkerCards / EventLog<br/>研究员卡片 · 事件日志"]
        RPT["📄 ReportView<br/>流式 Markdown 报告"]
        DEMO["🎬 demo.js 演示模式<br/>无需后端"]
    end

    FE <-->|"LangGraph SDK · SSE 流式 · :2024"| BE

    subgraph BE["⚙️ LangGraph 服务器 :2024 · src/open_deep_research"]
        MAIN["deep_researcher.py<br/>主图编排"]
        SUP["🎯 supervisor 子图<br/>拆解任务 · 调度研究员"]
        RES["🔍 researcher 子图 ×N<br/>并行 ReAct 搜索"]
        COM["🗜️ compress_research<br/>压缩研究发现"]
        FIN["📝 final_report_generation<br/>带引用最终报告"]
        UTIL["🧰 utils.py<br/>搜索 · MCP · Token 治理"]
    end

    MAIN --> SUP --> RES --> COM --> FIN
    RES --> UTIL

    subgraph EXT["☁️ 外部服务"]
        LLM["🤖 LLM 提供商<br/>OpenAI · Anthropic · Google<br/>DeepSeek · DashScope"]
        SRCH["🔎 搜索 API<br/>Tavily · OpenAI · Anthropic"]
        MCP["🔌 MCP 服务器<br/>数据库 · 外部工具"]
        AUTH["🔐 Supabase 认证<br/>src/security/auth.py"]
    end

    BE <--> LLM
    UTIL --> SRCH
    UTIL --> MCP
    BE --> AUTH

技术栈：LangGraph（多 Agent 编排）· LangChain init_chat_model · Pydantic（结构化输出）· Tavily / MCP · React 18 · Vite 6 · Tailwind CSS 4 · react-markdown

🔬 一次研究的生命周期

sequenceDiagram
    autonumber
    participant U as 👤 用户
    participant M as 🧠 主图
    participant S as 🎯 主管子图
    participant R as 🔍 研究员子图 ×N
    participant W as ☁️ 搜索 / LLM

    U->>M: 提出研究问题
    alt 问题不够清晰
        M-->>U: 追问细节（可配置跳过）
        U->>M: 补充回答
    end
    M->>M: write_research_brief<br/>生成结构化研究简报
    loop 研究迭代（上限 max_researcher_iterations）
        S->>S: think_tool 战略性思考<br/>决定下一步研究方向
        S->>R: 派发子课题
        R->>W: 多关键词并行搜索（ReAct）
        W-->>R: 搜索结果 + 自动摘要
        R->>R: compress_research 压缩发现
        R-->>S: 汇入 notes 研究笔记
    end
    S-->>M: 研究完成
    M->>M: final_report_generation<br/>（token 超限自动截断重试）
    M-->>U: 📄 带引用来源的深度研究报告

🧩 核心技术亮点

亮点	机制	代码落点
Command 动态路由	所有节点返回 `Command(goto=…, update=…)`，实现动态条件跳转	`deep_researcher.py`
结构化输出	Pydantic 模型约束 LLM 输出格式，程序可可靠解析、自动重试	`state.py`
think_tool 战略思考	虚拟工具让研究员在工具循环中「停下来想想」，被证明可提升研究质量	`utils.py`
三层状态隔离	主图 / 主管 / 研究员各自独立 State，子图之间互不污染	`state.py`
多厂商 Token 治理	识别 OpenAI / Anthropic / Gemini / DashScope 超限错误 → 自动截断重试	`utils.py`
SSE 流式解析	前端逐事件解析子图运行流，实时渲染研究员动态与报告	`frontend/src/lib/api.js`

💡 想深入理解每一行代码？请阅读 ZHIDAO.md —— 项目中文导读，包含逐文件代码讲解、运行流程全景图、配置系统详解、复刻建议与学习路线。

🚀 快速开始

环境要求

组件	版本	说明
Python	3.10+	后端运行时
uv	最新	Python 包与虚拟环境管理器
Node.js	≥ 18	前端控制台（可选）
API Key	—	默认配置需 `OPENAI_API_KEY` + `TAVILY_API_KEY`，见配置说明

1️⃣ 克隆仓库并激活虚拟环境

git clone https://github.com/langchain-ai/open_deep_research.git
cd open_deep_research
uv venv
source .venv/bin/activate  # Windows 系统：.venv\Scripts\activate

2️⃣ 安装依赖

uv sync
# 或者
uv pip install -r pyproject.toml

3️⃣ 设置 `.env` 文件来自定义环境变量（用于模型选择、搜索工具和其他配置）：

cp .env.example .env

4️⃣ 使用 LangGraph 本地服务器启动 Agent

# 安装依赖并启动 LangGraph 服务器
$env:PYTHONUTF8=1; 
.venv\Scripts\langgraph dev --allow-blocking

这将在浏览器中打开 LangGraph Studio 界面：

- 🚀 API: http://127.0.0.1:2024
- 🎨 Studio 界面: https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024
- 📚 API 文档: http://127.0.0.1:2024/docs

在 messages 输入框中提问，然后点击 Submit（提交）。在 "Manage Assistants"（管理助手）标签页中选择不同的配置。

5️⃣ 启动前端控制台（推荐）

自带 React + Vite 中文控制台（frontend/），实时流式展示「澄清 → 简报 → 主管调度 → 并行研究 → 报告生成」全过程：

视图	文件	内容
🎮 控制台	`ConsoleView.jsx`	直连 / 演示双模式、事件日志、研究员卡片、流式报告
🏗️ 架构	`ArchitectureView.jsx`	交互式研究架构图（GraphDiagram）
📊 基准	`BenchmarksView.jsx`	Deep Research Bench 成绩对比
⚙️ 配置	`ConfigurationView.jsx`	全量配置项中文手册

# 1. 先启动后端（见上方"快速开始"）
.venv\Scripts\langgraph dev --allow-blocking

# 2. 新开一个终端，启动前端
cd frontend
npm install    # 首次运行需要
npm run dev

启动后在浏览器打开 **http://127.0.0.1:5173**：

切到「直连后端」模式（默认后端地址 http://127.0.0.1:2024），点击「检测连接」确认后端可达
输入研究问题，点击「开始深度研究」，实时观察多智能体运行进度与最终报告
「运行配置」面板可调整模型、搜索方式、并发数（与 configuration.py 一致）；无后端时可用「演示模式」内置模拟数据

生产构建（输出到 frontend/dist/）：

cd frontend
npm run build

⚙️ 配置说明

大语言模型 (LLM) 🧠

通过 init_chat_model() API 支持多种 LLM 提供商，不同任务使用不同模型（详见 configuration.py）：

模型字段	默认值	用途
`summarization_model`	`openai:gpt-4.1-mini`	对搜索 API 结果进行摘要
`research_model`	`openai:gpt-4.1`	驱动搜索 Agent
`compression_model`	`openai:gpt-4.1`	压缩研究发现
`final_report_model`	`openai:gpt-4.1`	撰写最终报告

注意：所选模型需要支持结构化输出（structured outputs）和工具调用（tool calling）。OpenRouter 用户请参考此指南；通过 Ollama 使用本地模型的用户请参考设置说明。

搜索 API 🔍

默认使用 Tavily 搜索 API，完全兼容 MCP，并支持 Anthropic 和 OpenAI 的原生网页搜索。可通过环境变量切换：

SEARCH_API=tavily       # 默认，需要 TAVILY_API_KEY
SEARCH_API=openai       # OpenAI 原生搜索
SEARCH_API=anthropic    # Anthropic 原生搜索
SEARCH_API=none         # 不使用搜索（仅 MCP）

`.env` 环境变量一览

变量	必填	说明
`OPENAI_API_KEY`	✅（默认配置）	OpenAI 模型密钥
`TAVILY_API_KEY`	✅（默认搜索）	Tavily 搜索密钥
`DEEPSEEK_API_KEY` / `DASHSCOPE_API_KEY`	可选	DeepSeek / 阿里云 DashScope（通义）模型
`ANTHROPIC_API_KEY` / `GOOGLE_API_KEY`	可选	对应厂商模型密钥
`LANGSMITH_API_KEY` / `LANGSMITH_PROJECT` / `LANGSMITH_TRACING`	可选	LangSmith 链路追踪（调试 Agent 用）
`SUPABASE_KEY` / `SUPABASE_URL`	❌	MCP / Supabase 平台（本地跑完全不需要）

其他常用配置

配置项	默认值	说明
`max_researcher_iterations`	6	主管最大迭代次数
`max_react_tool_calls`	10	研究员最大工具调用次数
`max_concurrent_research_units`	5	最大并行研究员数
`max_content_length`	50000	网页内容最大字符数
`mcp_config`	None	MCP 服务器配置

所有配置均可通过环境变量、LangGraph Studio 界面或直接修改 configuration.py 完成。配置加载优先级：环境变量 > 运行时配置（Studio UI / 前端配置面板）> 默认值。

💡 最低可用配置：OPENAI_API_KEY + TAVILY_API_KEY 两行即可跑通完整研究流程。

📊 评估

本项目配套 Deep Research Bench 评估。该基准包含 100 个博士级别的研究任务（50 英文 + 50 中文），覆盖 22 个领域，以 RACE 分数（LLM-as-judge，Gemini）对报告质量打分。

⚠️ 警告：运行全部 100 个示例大约需要花费 $20-$100，具体取决于模型选择。

# 在 LangSmith 数据集上运行综合评估
python tests/run_evaluate.py

# 将结果提取为可提交到 Deep Research Bench 的 JSONL 文件
python tests/extract_langsmith_data.py --project-name "你的实验名称" --model-name "你的模型名称" --dataset-name "deep_research_bench"

生成的 JSONL 文件位于 tests/expt_results/，将其移至 Deep Research Bench 仓库的本地克隆，并按照其快速入门指南提交评估。

📁 项目结构

Gewu-Deep-Research/
│
├── 📄 README.md / ZHIDAO.md / CLAUDE.md     # 文档：项目门面 · 中文导读 · 工程约定
├── ⚙️ pyproject.toml · langgraph.json       # 依赖清单 · 主图入口声明
├── 🔑 .env.example                          # 环境变量模板
│
├── 🧠 src/open_deep_research/               # ⭐ 核心：多 Agent 研究引擎
│   ├── deep_researcher.py                   #   主图定义（入口文件，860 行）
│   ├── configuration.py                     #   配置中枢（模型 / 搜索 / 迭代上限）
│   ├── state.py                             #   三层状态定义（读代码的起点）
│   ├── prompts.py / prompts_zh.py           #   提示词模板（英 / 中）
│   └── utils.py                             #   工具箱（搜索 · MCP · Token 治理）
│
├── 🔐 src/security/auth.py                  # Supabase 认证与鉴权
├── 🖥️ frontend/                             # React 18 + Vite 中文控制台
│   └── src/views/                           #   控制台 · 架构 · 基准 · 配置 四视图
├── 🧪 tests/                                # Deep Research Bench 评估脚本
└── 📋 examples/                             # 示例研究报告（ArXiv / PubMed 等）

📖 逐文件深度导读见 ZHIDAO.md —— 完整目录、运行流程全景、配置系统详解、复刻建议与 FAQ 全在其中。

🚢 部署与使用

LangGraph Studio：按快速开始本地启动，即可在 Studio 中调试 Agent
托管部署：可轻松部署到 LangGraph Platform
开放 Agent 平台（OAP）：面向非技术用户的 Agent 界面，适合让用户自行搭配 MCP 工具与搜索 API——部署 OAP · 将 Deep Researcher 添加到 OAP

📖 深入阅读与学习路线

📖 ZHIDAO.md：项目中文导读——逐文件代码讲解（state.py → configuration.py → prompts.py → deep_researcher.py → utils.py）、运行流程全景图、配置系统详解、复刻建议、FAQ

❓ 常见问题

Q: .env 文件需要哪些环境变量？

至少需要：

OPENAI_API_KEY=sk-xxx          # OpenAI 模型密钥
TAVILY_API_KEY=tvly-xxx        # Tavily 搜索密钥

可选：ANTHROPIC_API_KEY、GOOGLE_API_KEY 等（视使用的模型提供商而定）。

Q: 如何使用 Tavily 之外的其他搜索？

修改 .env 中的 SEARCH_API 配置，或在 LangGraph Studio UI 中切换（支持 openai / anthropic / none 等）。

Q: 可以使用本地模型吗？

可以，通过 Ollama 支持，模型字符串格式为 ollama:model_name。但注意本地模型可能不支持结构化输出和工具调用。

Q: langgraph.json 是做什么的？

这是 LangGraph 工具链的项目配置文件（JSON），告诉 LangGraph CLI 主图的入口点：

{
  "graphs": {
    "agent": "./src/open_deep_research/deep_researcher.py:deep_researcher"
  }
}

🗺️ Roadmap

多 Agent 研究编排（澄清 → 简报 → 主管 → 并行研究员 → 压缩 → 报告）
中文提示词套件与报告语言自适应（prompts_zh.py）
自研 React 控制台：直连 / 演示双模式 + 运行配置面板
国内模型适配：DashScope / DeepSeek 等 Token 限流识别
稳定性修复：压缩模型 Token 校验、研究员状态不可变（见 git log）
报告导出（PDF / DOCX）
前端多会话研究与历史管理
更多搜索后端开箱支持

🤝 参与贡献

Fork → Branch → PR，欢迎提交新功能、新搜索后端与新前端视图！

📜 本项目基于 MIT License 开源 · 深度导读见 ZHIDAO.md

🙏 致谢上游 langchain-ai/open_deep_research 的开源工作

格物 · Gewu Deep Research · 如果对你有帮助，欢迎点一颗 ⭐ Star

阶段	目标	要点
阶段 1（1-2 天）	最小可行版本	单 Agent + 单搜索工具，去掉主管层，直接研究员搜索 + 生成报告
阶段 2（2-3 天）	加入多 Agent	主管子图 + 并行研究员 + think_tool
阶段 3（3-5 天）	完善功能	用户澄清流程、研究压缩、引用来源、token 超限处理
阶段 4（5-7 天）	高级功能	MCP 工具集成、多搜索 API、评估系统、部署上线

Navigation Menu

Repository files navigation

🔬 格物 · Gewu Deep Research

💭 格物致知，穷究一事

✨ 功能全景

🏗️ 架构总览

🔬 一次研究的生命周期

🧩 核心技术亮点

🚀 快速开始

环境要求

1️⃣ 克隆仓库并激活虚拟环境

2️⃣ 安装依赖

3️⃣ 设置 `.env` 文件来自定义环境变量（用于模型选择、搜索工具和其他配置）：

4️⃣ 使用 LangGraph 本地服务器启动 Agent

5️⃣ 启动前端控制台（推荐）

⚙️ 配置说明

大语言模型 (LLM) 🧠

搜索 API 🔍

`.env` 环境变量一览

其他常用配置

📊 评估

📁 项目结构

🚢 部署与使用

📖 深入阅读与学习路线

推荐阅读顺序

❓ 常见问题

🗺️ Roadmap

🤝 参与贡献

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
examples		examples
frontend		frontend
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
Description.md		Description.md
LICENSE		LICENSE
README.md		README.md
ZHIDAO.md		ZHIDAO.md
langgraph.json		langgraph.json
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Latest commit

History

Folders and files

Repository files navigation

🔬 格物 · Gewu Deep Research

💭 格物致知，穷究一事

✨ 功能全景

🏗️ 架构总览

🔬 一次研究的生命周期

🧩 核心技术亮点

🚀 快速开始

环境要求

1️⃣ 克隆仓库并激活虚拟环境

2️⃣ 安装依赖

3️⃣ 设置 .env 文件来自定义环境变量（用于模型选择、搜索工具和其他配置）：

4️⃣ 使用 LangGraph 本地服务器启动 Agent

5️⃣ 启动前端控制台（推荐）

⚙️ 配置说明

大语言模型 (LLM) 🧠

搜索 API 🔍

.env 环境变量一览

其他常用配置

📊 评估

📁 项目结构

🚢 部署与使用

📖 深入阅读与学习路线

推荐阅读顺序

❓ 常见问题

🗺️ Roadmap

🤝 参与贡献

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

3️⃣ 设置 `.env` 文件来自定义环境变量（用于模型选择、搜索工具和其他配置）：

`.env` 环境变量一览