# https://github.com/assafelovic/gpt-researcher 项目说明书 生成时间：2026-06-20 17:05:08 UTC ## 目录 - [GPT Researcher Overview and System Architecture](#page-1) - [Core Research Pipeline: Retrievers, Scrapers, Documents, and Context](#page-2) - [Multi-Agent Workflows, Deep Research, and MCP Integration](#page-3) - [Deployment, Frontend, Security, and Operations](#page-4) ## GPT Researcher Overview and System Architecture ### 相关页面 相关主题：[Core Research Pipeline: Retrievers, Scrapers, Documents, and Context](#page-2), [Multi-Agent Workflows, Deep Research, and MCP Integration](#page-3), [Deployment, Frontend, Security, and Operations](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/assafelovic/gpt-researcher/blob/main/README.md) - [frontend/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/frontend/README.md) - [mcp-server/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/mcp-server/README.md) - [frontend/nextjs/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/frontend/nextjs/README.md) - [multi_agents/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/multi_agents/README.md) - [backend/report_type/detailed_report/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/backend/report_type/detailed_report/README.md) - [gpt_researcher/mcp/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/gpt_researcher/mcp/README.md) - [multi_agents_ag2/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/multi_agents_ag2/README.md) - [backend/report_type/deep_research/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/backend/report_type/deep_research/README.md) - [backend/report_type/deep_research/example.py](https://github.com/assafelovic/gpt-researcher/blob/main/backend/report_type/deep_research/example.py)
# GPT Researcher 概述与系统架构 ## 项目简介 GPT Researcher 是首个面向网络与本地研究场景的开源深度研究代理（Deep Research Agent），能够在任意任务下生成带有引用、详细且客观的研究报告。资料来源：[README.md:1-30]()。 项目灵感来自 [Plan-and-Solve](https://arxiv.org/abs/2305.04091) 与 [RAG](https://arxiv.org/abs/2005.11401) 论文，旨在解决大语言模型在长篇研究任务中常见的事实偏差、Token 限制、信息源不足以及速度不稳定等问题，通过并行化代理工作提升整体性能。资料来源：[README.md:11-20]()。 ## 核心特性 GPT Researcher 提供了丰富的研究与产出能力，主要包括： - 📝 基于网络和本地文档生成详细研究报告 - 🖼️ 智能图片抓取与过滤，并支持使用 Google Gemini（Nano Banana）生成 AI 内联插图 - 📜 可生成超过 2,000 字的长篇报告 - 🌐 聚合 20+ 信息源以获得客观结论 - 🖥️ 提供轻量版（FastAPI + HTML/CSS/JS）与生产版（NextJS）双前端 - 🔍 支持 LangSmith 进行可观测性与追踪 - 🤖 提供基于 LangGraph 与 AG2 的多智能体工作流 资料来源：[README.md:35-60](), [README.md:120-145]()。 ## 系统架构 整个系统围绕一个 Python 核心库 `gpt_researcher` 构建，外部由前端应用、MCP 服务器以及多智能体协调层共同组成。 ```mermaid graph TD A[用户查询] --> B[Frontend
FastAPI / NextJS] B --> C[GPT Researcher Core
gpt_researcher/agent.py] C --> D[Research Conductor] D --> E[Web Retriever] D --> F[Local Document Scraper] D --> G[MCP Tools
gpt_researcher/mcp/] C --> H[Report Generator] H --> I[Multi-Agent Layer
LangGraph / AG2] I --> J[Publisher
PDF / Docx / Markdown] I --> K[Deep Research
Recursive Tree] ``` 架构说明：用户通过前端提交查询，核心代理 `agent.py` 调度 `Research Conductor` 抓取上下文（网络或本地），再交给 `Report Generator` 生成报告。复杂场景下，多智能体层会进一步拆解子主题并迭代修订；MCP 集成允许使用外部工具扩展能力。资料来源：[README.md:148-170](), [gpt_researcher/mcp/README.md:30-65]()。 ## 模块组成 | 模块路径 | 角色 | 关键能力 | | --- | --- | --- | | `backend/report_type/detailed_report/` | 详细报告生成器 | 受 [STORM](https://arxiv.org/abs/2402.14207) 启发，生成子主题并拼接长报告 | | `backend/report_type/deep_research/` | 深度递归研究 | 树状广度/深度探索，异步并发执行 | | `multi_agents/` | LangGraph 多智能体编排 | 包含 Chief Editor、Researcher、Editor、Reviewer、Revisor、Writer、Publisher | | `multi_agents_ag2/` | AG2 框架多智能体编排 | 与 LangGraph 版本功能类似，由 AG2 驱动 | | `gpt_researcher/mcp/` | Model Context Protocol 集成 | 客户端管理、智能工具选择、流式输出 | | `frontend/` | 静态前端 | 基于 FastAPI 提供轻量 UI | | `frontend/nextjs/` | NextJS 前端 | React 组件库 `gpt-researcher-ui` | | `mcp-server/` | 独立 MCP 服务（已迁移） | 提供 `deep_research`、`quick_search`、`write_report` 等工具 | 资料来源：[backend/report_type/detailed_report/README.md:1-10](), [backend/report_type/deep_research/README.md:1-25](), [multi_agents/README.md:25-55](), [gpt_researcher/mcp/README.md:35-60](), [frontend/nextjs/README.md:15-30]()。 ## 报告生成工作流 以深度研究模式为例，工作流遵循以下步骤：先根据查询生成多条 SERP 查询，再对每条结果执行子研究，递归扩展深度与广度；最后由 `parse_research_results_response` 解析出 `learnings` 与 `followUpQuestions`。该过程通过 `ReasoningEfforts.High` 调用 O3_MINI_MODEL 提升推理质量。资料来源：[backend/report_type/deep_research/example.py:1-60]()。 ## 已知问题与社区关注点 根据社区反馈，使用者需留意以下几类问题： 1. **来源幻觉**：当 `self.context = []` 时，`write_report` 仍会生成看似真实的引用，这是 [Issue #1572](https://github.com/assafelovic/gpt-researcher/issues/1572) 中用户多次确认的现象，部署到生产前应进行来源校验。 2. **未鉴权 SSRF 与本地文件读取**：WebSocket `/ws` 端点接受 `source_urls` 但缺少校验，结合 `PyMuPDFScraper` 的本地文件分支可能导致任意文件读取（[Issue #1794](https://github.com/assafelovic/gpt-researcher/issues/1794)、[#1805](https://github.com/assafelovic/gpt-researcher/issues/1805)），公网部署务必启用鉴权与白名单。 3. **LangChain 1.x 兼容**：Docker 镜像在 LangChain 1.x 发布后出现 `langchain module not found` 错误（[Issue #1536](https://github.com/assafelovic/gpt-researcher/issues/1536)），需在 `requirements.txt` 中固定旧版本。 4. **跨平台构建**：在 Apple Silicon 上 `docker buildx --platform linux/amd64` 会因缺少 `sse3` 指令集而失败（[Issue #658](https://github.com/assafelovic/gpt-researcher/issues/658)），建议使用本机架构构建。 5. **多智能体 NameError**：v3.4.2 修复了多智能体 `run_research_task` 抛出的 `NameError`（[v3.4.2 Release](https://github.com/assafelovic/gpt-researcher/releases/tag/v3.4.2)），升级至最新版本可避免该回归。 ## 快速上手 最简用法只需实例化 `GPTResearcher` 并调用 `conduct_research` 与 `write_report`： ```python from gpt_researcher import GPTResearcher from gpt_researcher.utils.enum import ReportType, Tone import asyncio async def main(): researcher = GPTResearcher( query="What are the latest developments in quantum computing?", report_type=ReportType.Deep.value, ) research_data = await researcher.conduct_research() report = await researcher.write_report() print(report) asyncio.run(main()) ``` 如需可视化 UI，可启动 FastAPI 静态前端（`python -m uvicorn main:app`）或使用 NextJS 版本（`npm run dev`）。资料来源：[backend/report_type/deep_research/README.md:30-50](), [frontend/README.md:10-25]()。 ## 参见 - [Deep Research Module](deep_research.md) - [Multi-Agent (LangGraph) Orchestration](multi_agents_langgraph.md) - [MCP Integration](mcp_integration.md) - [Frontend Deployment](frontend.md) - [Security Best Practices](security.md) --- ## Core Research Pipeline: Retrievers, Scrapers, Documents, and Context ### 相关页面 相关主题：[GPT Researcher Overview and System Architecture](#page-1), [Multi-Agent Workflows, Deep Research, and MCP Integration](#page-3), [Deployment, Frontend, Security, and Operations](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/assafelovic/gpt-researcher/blob/main/README.md) - [backend/utils.py](https://github.com/assafelovic/gpt-researcher/blob/main/backend/utils.py) - [backend/memory/research.py](https://github.com/assafelovic/gpt-researcher/blob/main/backend/memory/research.py) - [backend/report_type/detailed_report/detailed_report.py](https://github.com/assafelovic/gpt-researcher/blob/main/backend/report_type/detailed_report/detailed_report.py) - [backend/report_type/deep_research/example.py](https://github.com/assafelovic/gpt-researcher/blob/main/backend/report_type/deep_research/example.py) - [multi_agents/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/multi_agents/README.md) - [multi_agents/agents/editor.py](https://github.com/assafelovic/gpt-researcher/blob/main/multi_agents/agents/editor.py) - [multi_agents/agents/writer.py](https://github.com/assafelovic/gpt-researcher/blob/main/multi_agents/agents/writer.py) - [multi_agents/agents/utils/file_formats.py](https://github.com/assafelovic/gpt-researcher/blob/main/multi_agents/agents/utils/file_formats.py) - [multi_agents_ag2/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/multi_agents_ag2/README.md) - [frontend/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/frontend/README.md) - [mcp-server/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/mcp-server/README.md) 社区上下文引用的相关问题： - #1572 — 当 context 为空时 write_report 容易产生幻觉来源 - #1623 — PyMuPDFScraper 仅读取首页的修复 - #1607 — Web 抓取中的数据解析问题 - #1673 / v3.4.4 — 上下文规范化（dict/string） - #1794 / #1805 — source_urls 的未授权 SSRF 与本地 PDF 任意读取
# Core Research Pipeline: Retrievers, Scrapers, Documents, and Context ## 一、概述与定位 核心研究流水线（Core Research Pipeline）是 GPT Researcher 的主干流程，负责把一个**用户查询**转成一份**多源、长文、可导出**的研究报告。其内部由四类组件协作完成： 1. **Retriever（检索器）**：负责根据子查询拉取网络/本地候选 URL 与摘要。 2. **Scraper（抓取器）**：负责把候选 URL 或本地文件解析成结构化文档内容。 3. **Document（文档层）**：负责把抓取结果切分、清洗并聚合为上下文片段。 4. **Context（上下文管理）**：负责跨步骤维护上下文、来源集合与报告状态，供后续撰写与多智能体协作使用。 README 指出，系统会基于研究查询生成面向任务的代理，再以爬虫代理收集每个问题的信息，最后汇总并跟踪来源 [README.md](https://github.com/assafelovic/gpt-researcher/blob/main/README.md)。 ## 二、整体流水线 ```mermaid flowchart LR A[用户查询] --> B[Query Processing
生成子问题] B --> C[Retriever
搜索引擎/本地检索] C --> D[Scraper
网页/PDF/本地文档] D --> E[Document 处理
清洗与切分] E --> F[Context 聚合
global_context/visited_urls] F --> G[Writer / Report
撰写报告] G --> H[导出 PDF/DOCX/MD] ``` - **Query Processing**：把单一查询扩展为多个研究子问题（在 `deep_research` 中表现为 `generate_serp_queries`）[backend/report_type/deep_research/example.py](https://github.com/assafelovic/gpt-researcher/blob/main/backend/report_type/deep_research/example.py)。 - **Retriever**：在 `DetailedReport` 中通过 `self.gpt_researcher.conduct_research()` 触发 [backend/report_type/detailed_report/detailed_report.py](https://github.com/assafelovic/gpt-researcher/blob/main/backend/report_type/detailed_report/detailed_report.py)。 - **Scraper → Document**：从 URL 提取正文（支持 JS 渲染与 PDF），随后写入 `self.context`。 - **Context 聚合**：`global_context`、`global_urls` 跨子主题复用，避免重复抓取 [backend/report_type/detailed_report/detailed_report.py](https://github.com/assafelovic/gpt-researcher/blob/main/backend/report_type/detailed_report/detailed_report.py)。 - **Writer**：在多智能体版本中由 Writer Agent 统一汇总并写出 `introduction`、`table_of_contents`、`conclusion`、`sources` [multi_agents/agents/writer.py](https://github.com/assafelovic/gpt-researcher/blob/main/multi_agents/agents/writer.py)。 - **导出**：通过 `mistune` 与 `htmldocx` 把 Markdown 渲染为 DOCX [backend/utils.py](https://github.com/assafelovic/gpt-researcher/blob/main/backend/utils.py)。 ## 三、检索器（Retrievers） 检索器是流水线的入口，决定了**质量与时效性**。在 `deep_research` 示例中，检索结果被传入 `process_serp_result`，由 LLM 抽取 `learnings` 与 `followUpQuestions`，并要求每个学习点附带 `sourceUrl` 引用 [backend/report_type/deep_research/example.py](https://github.com/assafelovic/gpt-researcher/blob/main/backend/report_type/deep_research/example.py)。 社区反馈显示检索器的稳定性直接影响最终报告： - #1797 指出 SERP 提供方的不稳定会显著降低报告质量，建议增加可选检索后端。 - v3.5.0 在 PR #1647 中新增 ModelsLab 图像生成；v3.4.4 在 PR #1673 中修复 `STRATEGIC_LLM` 缺失冒号导致的引用错误，影响检索后策略性 LLM 调用。 ## 四、抓取器（Scrapers）与文档 抓取器把检索得到的 URL（含 `.pdf` 结尾或本地路径）转为可消费文本。社区问题揭示了几个与本主题密切相关的脆弱点： | 组件 | 行为 | 已知问题 | 修复/缓解 | |---|---|---|---| | PyMuPDFScraper | 处理 `.pdf` 来源 | 仅读取首页（#1623） | v3.4.3 PR #1623 修复为读取全部页 | | 网页抓取解析 | 解析 HTML | 数据解析异常（#1607） | v3.4.4 PR #1607 增加健壮性处理 | | source_urls 入口 | 接收外部 URL | 未授权 SSRF（#1794）、本地任意 PDF 读取（#1805） | 应在入口做白名单/校验 | | 上下文规范化 | 统一 context 格式 | dict / string 混用导致 KeyError | v3.4.4 PR 修复 | 需要特别注意的是，当 `self.context = []`（即未抓到任何相关上下文）时，`write_report` 仍会调用 LLM 撰写报告，进而可能**编造看似真实的来源**（#1572）。建议在调用 `write_report` 前显式校验 `context` 长度并对空集合做兜底文案处理 [backend/report_type/detailed_report/detailed_report.py](https://github.com/assafelovic/gpt-researcher/blob/main/backend/report_type/detailed_report/detailed_report.py)。 ## 五、上下文管理与多智能体协同 `DetailedReport` 通过 `global_context`、`global_written_sections`、`global_urls` 三个集合跨子主题共享上下文；`visited_urls` 在 `_initial_research` 后被 `_generate_subtopic_reports` 复用，并在 `_construct_detailed_report` 中合并用户提供的 `source_urls` [backend/report_type/detailed_report/detailed_report.py](https://github.com/assafelovic/gpt-researcher/blob/main/backend/report_type/detailed_report/detailed_report.py)。 在多智能体变体中，`ResearchState` 是一份贯穿 Browser → Editor → Researcher → Reviewer → Reviser → Writer → Publisher 的共享草稿状态 [backend/memory/research.py](https://github.com/assafelovic/gpt-researcher/blob/main/backend/memory/research.py)。Editor 负责根据 `initial_research` 切分章节标题，并仅输出 JSON 形式的标题数组 [multi_agents/agents/editor.py](https://github.com/assafelovic/gpt-researcher/blob/main/multi_agents/agents/editor.py)；Writer 汇总最终 `introduction/conclusion/sources` [multi_agents/agents/writer.py](https://github.com/assafelovic/gpt-researcher/blob/main/multi_agents/agents/writer.py)；AG2 版本则提供 `source: web | local` 切换，配合 `DOC_PATH` 进行本地文档研究 [multi_agents_ag2/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/multi_agents_ag2/README.md)。 ## 六、常见失败模式与建议 - **空上下文幻觉**：在调用写入前校验 `self.context`（#1572）。 - **PDF 抓取不完整**：升级到 v3.4.3+ 以保证多页读取（#1623）。 - **SSRF / 本地文件泄露**：不要把 `/ws` 暴露在公网；必要时在反向代理层做白名单与 `.pdf` 路径拦截（#1794、#1805）。 - **上下文格式不一致**：升级到 v3.4.4 引入的规范化补丁（#1673）。 - **导出失败**：DOCX 导出依赖 `htmldocx` + `mistune`，建议在 Dockerfile 中固定版本，避免 `weasyprint` GTK+3 在 Windows 上的安装问题（#166）。 ## 七、See Also - Multi-Agent Workflow（LangGraph / AG2） - Deep Research 模块与递归探索 - Frontend 部署（FastAPI 静态版 / NextJS 版） - MCP Server 集成 - LangSmith 可观测性配置 --- 引用汇总（资料来源格式 `path:line`）： - [README.md](https://github.com/assafelovic/gpt-researcher/blob/main/README.md) - [backend/utils.py](https://github.com/assafelovic/gpt-researcher/blob/main/backend/utils.py) - [backend/memory/research.py](https://github.com/assafelovic/gpt-researcher/blob/main/backend/memory/research.py) - [backend/report_type/detailed_report/detailed_report.py](https://github.com/assafelovic/gpt-researcher/blob/main/backend/report_type/detailed_report/detailed_report.py) - [backend/report_type/deep_research/example.py](https://github.com/assafelovic/gpt-researcher/blob/main/backend/report_type/deep_research/example.py) - [multi_agents/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/multi_agents/README.md) - [multi_agents/agents/editor.py](https://github.com/assafelovic/gpt-researcher/blob/main/multi_agents/agents/editor.py) - [multi_agents/agents/writer.py](https://github.com/assafelovic/gpt-researcher/blob/main/multi_agents/agents/writer.py) - [multi_agents/agents/utils/file_formats.py](https://github.com/assafelovic/gpt-researcher/blob/main/multi_agents/agents/utils/file_formats.py) - [multi_agents_ag2/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/multi_agents_ag2/README.md) - [frontend/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/frontend/README.md) - [mcp-server/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/mcp-server/README.md) --- ## Multi-Agent Workflows, Deep Research, and MCP Integration ### 相关页面 相关主题：[GPT Researcher Overview and System Architecture](#page-1), [Core Research Pipeline: Retrievers, Scrapers, Documents, and Context](#page-2), [Deployment, Frontend, Security, and Operations](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/assafelovic/gpt-researcher/blob/main/README.md) - [multi_agents/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/multi_agents/README.md) - [multi_agents/agents/editor.py](https://github.com/assafelovic/gpt-researcher/blob/main/multi_agents/agents/editor.py) - [multi_agents/agents/reviewer.py](https://github.com/assafelovic/gpt-researcher/blob/main/multi_agents/agents/reviewer.py) - [backend/report_type/deep_research/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/backend/report_type/deep_research/README.md) - [backend/report_type/deep_research/example.py](https://github.com/assafelovic/gpt-researcher/blob/main/backend/report_type/deep_research/example.py) - [backend/report_type/detailed_report/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/backend/report_type/detailed_report/README.md) - [gpt_researcher/mcp/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/gpt_researcher/mcp/README.md) - [mcp-server/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/mcp-server/README.md) - [multi_agents_ag2/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/multi_agents_ag2/README.md)
# Multi-Agent Workflows, Deep Research, and MCP Integration 本页系统性地介绍 GPT Researcher 在多智能体（Multi-Agent）协作、深度研究（Deep Research）以及模型上下文协议（Model Context Protocol, MCP）集成三大高级能力上的架构设计与使用方法。 ## 1. 多智能体工作流（Multi-Agent Workflows） GPT Researcher 提供了两套独立的多智能体实现：基于 [LangGraph](https://python.langchain.com/v0.1/docs/langgraph/) 的版本（位于 `multi_agents/`）与基于 [AG2](https://github.com/ag2ai/ag2) 的版本（位于 `multi_agents_ag2/`）。其设计灵感来自 [STORM](https://arxiv.org/abs/2402.14207) 论文，目标是把研究任务拆解为多个具有专门职责的智能体进行协同。 ### 1.1 智能体角色与职责 工作流中包含以下核心角色，资料来源：[multi_agents/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/multi_agents/README.md)： | 角色 | 职责 | | --- | --- | | **Chief Editor** | 协调全局，作为"主控"智能体，通过 LangGraph 管理其它智能体 | | **Editor** | 根据初始研究规划报告大纲与结构 | | **Browser (gpt-researcher)** | 浏览互联网以完成初步研究 | | **Researcher** | 对每个子主题开展深度研究并撰写草稿 | | **Reviewer** | 依据准则验证草稿正确性并提供反馈 | | **Revisor** | 根据 Reviewer 反馈不断迭代修订 | | **Writer** | 汇总各草稿，撰写引言、结论与参考文献 | | **Publisher** | 将最终报告发布为 PDF、DOCX、Markdown 等多格式 | ### 1.2 工作流执行步骤 工作流遵循"规划 → 数据收集与分析 → 审查与修订 → 撰写与提交 → 发布"五个阶段，资料来源：[multi_agents/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/multi_agents/README.md)。`Editor` 在规划阶段读取 `task.json` 中的 `query`、`model`、`max_sections`、`max_plan_revisions` 等参数，并生成结构化 JSON 计划（标题、日期、章节列表），资料来源：[multi_agents/agents/editor.py](https://github.com/assafelovic/gpt-researcher/blob/main/multi_agents/agents/editor.py:1-50)。`Reviewer` 在审核阶段会按 `task.guidelines` 准则执行，并在所有准则通过时返回 `None` 标记完成，资料来源：[multi_agents/agents/reviewer.py](https://github.com/assafelovic/gpt-researcher/blob/main/multi_agents/agents/reviewer.py:1-60)。 ### 1.3 AG2 实现的差异 `multi_agents_ag2/` 目录提供基于 AG2 框架的等价实现，新增 `include_human_feedback`、`follow_guidelines`、`source`（`web` 或 `local`）等任务字段，资料来源：[multi_agents_ag2/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/multi_agents_ag2/README.md)。当 `source=local` 时需配置 `DOC_PATH` 环境变量。 ## 2. 深度研究（Deep Research） ### 2.1 设计理念 Deep Research 是 GPT Researcher 应对当前"深度研究"趋势推出的递归式研究系统，采用树状探索模式（tree-like exploration），同时控制"广度（breadth）"和"深度（depth）"两个维度，资料来源：[backend/report_type/deep_research/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/backend/report_type/deep_research/README.md)。README 指出典型一次运行约需 5 分钟，使用 `o3-mini`（High 推理强度）时成本约 $0.4。 ### 2.2 核心实现 `backend/report_type/deep_research/example.py` 中的 `deep_research()` 方法通过 `breadth` 与 `depth` 控制递归层级，使用 `ResearchProgress` 跟踪整体进度；每层生成多个 SERP 查询，并使用推理模型（`O3_MINI_MODEL` + `ReasoningEfforts.High`）从检索结果中提炼结构化的 `learnings` 与 `followUpQuestions`，资料来源：[backend/report_type/deep_research/example.py](https://github.com/assafelovic/gpt-researcher/blob/main/backend/report_type/deep_research/example.py:1-80)。 ### 2.3 快速开始 ```python from gpt_researcher import GPTResearcher from gpt_researcher.utils.enum import ReportType, Tone import asyncio async def main(): researcher = GPTResearcher( query="What are the latest developments in quantum computing?", report_type="deep", # 触发 deep research 模式 ) research_data = await researcher.conduct_research() # ... 后续写报告等步骤 ``` 资料来源：[backend/report_type/deep_research/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/backend/report_type/deep_research/README.md)。如需生成更长的详细报告，`backend/report_type/detailed_report/` 提供了基于 STORM 论文的多子主题聚合架构，资料来源：[backend/report_type/detailed_report/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/backend/report_type/detailed_report/README.md)。 ## 3. MCP 集成（Model Context Protocol） GPT Researcher 通过 MCP 标准协议与外部工具、数据源对接，整体由仓库内 `gpt_researcher/mcp/` 模块与独立仓库 [gptr-mcp](https://github.com/assafelovic/gptr-mcp) 共同支撑，资料来源：[gpt_researcher/mcp/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/gpt_researcher/mcp/README.md)。 ### 3.1 内部 MCP 模块结构 `gpt_researcher/mcp/` 目录下的子模块及职责： | 子模块 | 职责 | | --- | --- | | `client.py` (`MCPClientManager`) | 维护 `MultiServerMCPClient` 实例，支持 stdio / websocket / HTTP 连接类型，并负责资源回收 | | `tool_selector.py` (`MCPToolSelector`) | 通过 LLM 智能分析当前可用的 MCP 工具，并结合研究查询进行选择 | | `research.py` | 基于所选工具执行实际研究流程 | | `streaming.py` | 提供 WebSocket 流式日志与状态推送工具 | 资料来源：[gpt_researcher/mcp/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/gpt_researcher/mcp/README.md)。 ### 3.2 独立 MCP 服务器（gptr-mcp） 主仓库的 `mcp-server/README.md` 已说明 MCP 服务器迁移至独立仓库 [assafelovic/gptr-mcp](https://github.com/assafelovic/gptr-mcp)，资料来源：[mcp-server/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/mcp-server/README.md)。该服务器暴露以下资源与工具： - **资源**：`research_resource`（按任务返回相关网络资源） - **工具**：`deep_research`（深度研究）、`quick_search`（快速搜索）、`write_report`（撰写报告）、`get_research_sources`（获取来源）、`get_research_context`（获取完整上下文） `quick_search` 注重速度，`deep_research` 注重质量，后者单次运行约需 30 秒，资料来源：[mcp-server/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/mcp-server/README.md)。 ## 4. 已知风险与社区反馈 社区在使用这些高级特性时报告了若干重要问题，应在生产部署前予以关注： - **报告幻觉（Hallucination）**：当检索后 `self.context = []` 为空时，`write_report` 仍会生成看似真实但虚构的来源与内容，资料来源：[Issue #1572](https://github.com/assafelovic/gpt-researcher/issues/1572)。 - **未鉴权 SSRF**：后端 `/ws` 端点接受无鉴权的 `source_urls` 列表，可被用于服务端请求伪造，资料来源：[Issue #1794](https://github.com/assafelovic/gpt-researcher/issues/1794)。 - **本地 PDF 任意读取**：以 `.pdf` 结尾的 `source_urls` 会被路由到 `PyMuPDFScraper` 的本地文件分支，导致未鉴权任意 PDF 文件读取，资料来源：[Issue #1805](https://github.com/assafelovic/gpt-researcher/issues/1805)。 - **修复进展**：v3.4.3 修复了 `PyMuPDFScraper` 仅读取首页的 bug，v3.4.4 修复了 `STRATEGIC_LLM` 解析与 Web 抓取数据解析问题，v3.5.0 新增 ModelsLab 图像生成与多项性能改进，资料来源：[v3.5.0 Release Notes](https://github.com/assafelovic/gpt-researcher/releases/tag/v3.5.0)、[v3.4.4 Release Notes](https://github.com/assafelovic/gpt-researcher/releases/tag/v3.4.4)。 ## See Also - [Installation & Getting Started](https://docs.gptr.dev/docs/gpt-researcher/getting-started) - [Multi-Agent LangGraph Documentation](https://docs.gptr.dev/docs/gpt-researcher/multi_agents/langgraph) - [Deep Research Documentation](https://docs.gptr.dev/docs/gpt-researcher/gptr/deep_research) - [gptr-mcp Repository](https://github.com/assafelovic/gptr-mcp) - [LangGraph Documentation](https://python.langchain.com/v0.1/docs/langgraph/) --- ## Deployment, Frontend, Security, and Operations ### 相关页面 相关主题：[GPT Researcher Overview and System Architecture](#page-1), [Core Research Pipeline: Retrievers, Scrapers, Documents, and Context](#page-2), [Multi-Agent Workflows, Deep Research, and MCP Integration](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/assafelovic/gpt-researcher/blob/main/README.md) - [frontend/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/frontend/README.md) - [backend/requirements.txt](https://github.com/assafelovic/gpt-researcher/blob/main/backend/requirements.txt) - [multi_agents/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/multi_agents/README.md) - [multi_agents_ag2/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/multi_agents_ag2/README.md) - [mcp-server/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/mcp-server/README.md) - [gpt_researcher/mcp/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/gpt_researcher/mcp/README.md)
# 部署、前端、安全与运维 GPT Researcher 提供多层次的部署形态——从单机 Python 包到 FastAPI 后端 + 前端的全栈应用，再到基于 LangGraph / AG2 的多代理流水线，以及通过 MCP（Model Context Protocol）协议对外暴露的工具化集成。理解这些形态之间的差异、约束与攻击面，对于生产化落地至关重要。 ## 部署形态与依赖栈 仓库根目录的 [README.md](https://github.com/assafelovic/gpt-researcher/blob/main/README.md) 描述了两条主要部署路径： 1. **Python 包模式**：通过 `pip install gpt-researcher` 安装，直接在脚本中实例化 `GPTResearcher` 类。 2. **后端服务模式**：在 `backend/server/` 目录下运行 FastAPI + WebSocket 服务（`/ws` 端点），可由前端调用。 后端生产依赖由 [backend/requirements.txt](https://github.com/assafelovic/gpt-researcher/blob/main/backend/requirements.txt) 显式声明：核心框架为 `fastapi>=0.104.1`、`uvicorn>=0.24.0`、`pydantic>=2.5.1`，LLM 链路使用 `langchain>=1.0.0` 与 `langchain-openai>=1.0.0`，搜索侧依赖 `tavily-python>=0.7.12`，输出格式支持 `md2pdf`、`python-docx` 与 `htmldocx`。多代理流水线另需 `langgraph`（见 [multi_agents/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/multi_agents/README.md)）。 社区中关于部署的典型痛点集中在 Docker 构建上：Windows / M1 架构下的交叉编译失败（参见 issue #658）、LangChain 1.x 版本兼容性问题（issue #1536）、以及对预构建容器镜像的长期呼声（issue #1226）。这些问题反映出该项目的部署生态尚依赖用户自构建，官方未发布稳定的预构建镜像。 ## 前端应用 [frontend/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/frontend/README.md) 明确给出两种前端实现： | 选项 | 技术栈 | 启动命令 | 端口 | |------|--------|---------|------| | 静态前端 | FastAPI 静态文件 | `python -m uvicorn main:app` | 8000 | | NextJS 前端 | Next.js + Tailwind | `npm run dev`（需 Node 18.17.0） | 3000 | NextJS 前端通过 `npm install --legacy-peer-deps` 安装依赖，运行时要求后端服务运行在 `localhost:8000` 上。两种前端都消费后端的 WebSocket 端点 `/ws`，用于实时推进研究任务流。需要注意的是，根 [README.md](https://github.com/assafelovic/gpt-researcher/blob/main/README.md) 提到的"实时进度跟踪"功能依赖 WebSocket 长连接，因此反代 / 负载均衡层必须正确转发 `Upgrade` 头。 ## 安全注意事项 社区近期披露了多个面向公开部署的高危问题，需在生产化前重点评估： - **未认证 SSRF（#1794）**：WebSocket `/ws` 端点接受调用方传入的 `source_urls` 参数且无身份验证、无 URL 校验，攻击者可借此让后端代理访问内部网络资源。 - **任意本地 PDF 读取（#1805）**：当传入的 `source_urls` 条目以 `.pdf` 结尾时，`PyMuPDFScraper` 的非 URL 分支会将其作为本地文件路径交给 `PyMuPDFLoader`，造成任意文件读取。 - **来源捏造（#1572）**：在 `write_report` 中若 `self.context = []`（未检索到相关上下文），最终报告会"幻觉"出看似真实但并不存在的来源。 建议的缓解措施包括：在反代层引入身份验证与速率限制；对 `source_urls` 做严格的协议 / 主机白名单；为 `PyMuPDFScraper` 增加本地路径校验；并在缺少上下文时显式返回空报告或错误，而不是继续生成。 ```mermaid flowchart LR Client[客户端] -->|ws + source_urls| WsServer[/ws 端点/] WsServer -->|未校验| Scraper{来源路由} Scraper -->|http URL| WebFetch[远程抓取] Scraper -->|.pdf 路径| PyMuPDFLoader[本地文件读取] WebFetch --> Context[上下文聚合] PyMuPDFLoader --> Context Context -->|context=[]| ReportGen[报告生成] ReportGen -->|潜在幻觉| Output[最终报告] ``` ## 运维与可观测性 根 [README.md](https://github.com/assafelovic/gpt-researcher/blob/main/README.md) 的"Observability"章节指出，项目支持通过 `LANGCHAIN_TRACING_V2=true`、`LANGCHAIN_API_KEY`、`LANGCHAIN_PROJECT` 三个环境变量接入 LangSmith，从而对基于 LangGraph 的多代理工作流进行链路追踪。生产部署应同时启用该能力以便调试 `researcher → reviewer → reviser` 节点之间的状态传递——[multi_agents/agents/editor.py](https://github.com/assafelovic/gpt-researcher/blob/main/multi_agents/agents/editor.py) 中的 `_create_workflow` 正是该管线的入口。 此外，[gpt_researcher/mcp/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/gpt_researcher/mcp/README.md) 描述的 MCP 集成（`client.py` / `tool_selector.py` / `research.py`）以及 [mcp-server/README.md](https://github.com/assafelovic/gpt-researcher/blob/main/mcp-server/README.md) 指向的独立仓库 [assafelovic/gptr-mcp](https://github.com/assafelovic/gptr-mcp) 提供了一种新的部署形态——将研究能力以 MCP 工具形式暴露给 Claude 等宿主。该模式下需注意 stdio / websocket / HTTP 三类连接的资源清理逻辑，避免子进程泄漏。 ## See Also - [MCP Integration & Deep Research Pipeline](mcp-integration.md) - [Multi-Agent Orchestration (LangGraph & AG2)](multi-agent-orchestration.md) - [Scrapers & Retrievers](scrapers-retrievers.md) --- --- ## Doramagic 踩坑日志 项目：assafelovic/gpt-researcher 摘要：发现 13 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：[Security] Unauthenticated Server-Side Request Forgery (SSRF)。 ## 1. 安全/权限坑 · 来源证据：[Security] Unauthenticated Server-Side Request Forgery (SSRF) - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Security] Unauthenticated Server-Side Request Forgery (SSRF) - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/assafelovic/gpt-researcher/issues/1794 | 来源类型 github_issue 暴露的待验证使用条件。 ## 2. 配置坑 · 可能修改宿主 AI 配置 - 严重度：medium - 证据强度：source_linked - 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。 - 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 - 证据：capability.host_targets | https://github.com/assafelovic/gpt-researcher | host_targets=mcp_host, claude ## 3. 配置坑 · 来源证据：Enhancement: Consider serpbase.dev as an alternative web search provider for stable SERP retrieval - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Enhancement: Consider serpbase.dev as an alternative web search provider for stable SERP retrieval - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/assafelovic/gpt-researcher/issues/1797 | 来源类型 github_issue 暴露的待验证使用条件。 ## 4. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/assafelovic/gpt-researcher | README/documentation is current enough for a first validation pass. ## 5. 维护坑 · 来源证据：Website is broken - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Website is broken - 对用户的影响：可能阻塞安装或首次运行。 - 证据：community_evidence:github | https://github.com/assafelovic/gpt-researcher/issues/1807 | 来源类型 github_issue 暴露的待验证使用条件。 ## 6. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/assafelovic/gpt-researcher | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/assafelovic/gpt-researcher | no_demo; severity=medium ## 8. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/assafelovic/gpt-researcher | no_demo; severity=medium ## 9. 安全/权限坑 · 来源证据：Add Obscura as a scraper backend - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add Obscura as a scraper backend - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/assafelovic/gpt-researcher/issues/1800 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 10. 安全/权限坑 · 来源证据：Unauthenticated arbitrary local PDF file read via source_urls and the PyMuPDFScraper local-file branch - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Unauthenticated arbitrary local PDF file read via source_urls and the PyMuPDFScraper local-file branch - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/assafelovic/gpt-researcher/issues/1805 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 11. 安全/权限坑 · 来源证据：🌐 Runtime Open Federation — federate GPT-Researcher as a research node, earn USDC (no key, MCP compatible) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：🌐 Runtime Open Federation — federate GPT-Researcher as a research node, earn USDC (no key, MCP compatible) - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/assafelovic/gpt-researcher/issues/1801 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 12. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/assafelovic/gpt-researcher | issue_or_pr_quality=unknown ## 13. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/assafelovic/gpt-researcher | release_recency=unknown