GPT Researcher

GPT Researcher 快速入门：把「查资料写报告」拆成一条可复用流水线

这是什么？适合谁？

GPT Researcher 是 assafelovic 维护的开源深度研究 Agent，官方定位是「面向任意任务的、同时覆盖网络与本地文档的深度研究 Agent」（README）。它不做对话，做的是把一个开放式问题跑成一份带引用的长报告。

它的架构是三段式（依据 README 的 Architecture 章节）：

• 规划（planner）：把主问题拆成若干研究问题，这些问题合起来才构成对主问题的完整回答；
• 执行（execution）：为每个子问题派检索/爬取 Agent 去抓资料，边抓边做摘要与来源记录；
• 发布（publisher）：过滤、聚合各子问题的摘要，写成一份结构化报告并保留引用。

README 强调它「超出 RAG」的部分：planner/execution 拆分、只保留对回答有用的上下文（Jev 智能上下文过滤，默认不需要 API Key 或向量库）、多 Agent 协作、以及广度与深度并行的递归深入研究。

适合谁：要定期产出行业调研、竞品分析、文献综述初稿的研究/分析岗；想把「研究报告自动化」嵌进自有系统的开发者（它既是可跑的服务，也是可 pip install 的库）；已经有模型与检索 API 预算、缺一条编排流水线的团队。

不适合谁：只需要单轮问答的用户（用带联网的对话产品更省事）；没有模型 API Key 或检索 Key 的人（缺任一都跑不起来，README 明确要求 OPENAI_API_KEY 与 TAVILY_API_KEY）；要求「零配置、开箱即用」的场景。

核验日期：2026-10-29。功能与命令依据官方仓库 README 与文档站，本文未在本站环境安装运行。

准备工作

• Python 3.12 或更高（README 的安装第 1 步）。
• 一个模型 API Key：默认走 OPENAI_API_KEY；若用 OpenAI 兼容的第三方或本地模型，额外设 OPENAI_BASE_URL。
• 一个检索 API Key：默认 TAVILY_API_KEY（READM 的示例同时给出 Tavily 与 MCP 混合检索选项）。
• 可选：LANGCHAIN_TRACING_V2 / LANGCHAIN_API_KEY，开启 LangSmith 链路追踪，便于看每一步 Agent 在干什么。
• 磁盘与网络：报告会抓取大量网页，跑长主题时建议单独目录 + 单独预算，不要和别的任务共用一份 .env。
• 计价口径：软件本身是 Apache-2.0 开源；模型与检索按各自厂商计费，README 未给统一定价，本文不推测金额。

安装与启用

路线一：装成 Python 包，在脚本里调用

pip install gpt-researcher

from gpt_researcher import GPTResearcher

query = "why is Nvidia stock going up?"
researcher = GPTResearcher(query=query)
research_result = await researcher.conduct_research()
report = await researcher.write_report()

这是把它嵌进自有系统最省事的方式：两步调用（先研究、再写报告），返回的是字符串报告。

路线二：克隆仓库跑起完整服务（带前端）

git clone https://github.com/assafelovic/gpt-researcher.git
cd gpt-researcher
export OPENAI_API_KEY={Your OpenAI API Key here}
export TAVILY_API_KEY={Your Tavily API Key here}
pip install -r requirements.txt
python -m uvicorn main:app --reload

访问 http://localhost:8000 即可用网页界面提交查询、看进度、读报告。README 说明前端有两套：FastAPI 直接托管的轻量静态版，以及功能更全的 NextJS 版。

路线三：装成 Claude Skill，在对话里用

npx skills add assafelovic/gpt-researcher

装好后 Claude 可以在对话中直接调用它的深度研究能力，适合「不想自己搭服务、只想在现有对话里多一个研究员」的用法。

三条路线跑完，建议先做一次连通性自检：用同一个 query 分别走 pip 与网页两条路，确认拿到报告且引用链接可点开——引用不落地的报告不能用于任何对外交付。

首个任务：跑一份能被复核的调研报告

挑一个你自己已有判断的题目先跑，这样你才能判断报告质量（README 的 Live Demo 也是这个思路）。

研究主题：2026 年开源深度研究 Agent 的主流实现路线差异
要求：
1. 拆成至少 6 个子问题，覆盖架构、检索策略、引用可信度、成本、部署形态；
2. 每条结论必须给出可点击的来源；
3. 结论分三档标注：官方文档明确写了 / 第三方报道 / 你的推断；
4. 最后单独列一节「本文没有验证的部分」。

成功判据（缺一条都不算跑通）：

• 报告长度与深度符合预期（README 说明它能生成超过 2,000 词的报告、聚合 20 个以上来源）；
• 抽样点开 5 条引用，全部能打开且内容与结论对得上；
• 「推断」与「事实」被分开标注，而不是混在一段话里；
• 你能用它省下的时间衡量价值：如果读它的报告比自己查还慢，说明子问题拆错了。

初级用法

• 把它当流水线而不是聊天：输入是「主题 + 约束 + 输出格式」，不是「帮我查一下」。约束写得越具体（时间范围、来源类型、必须覆盖的维度），报告越可用。
• 本地文档 + 网络混合检索：README 有 local research 一节，把本地 PDF/Markdown 放进指定目录后，同一份报告可以同时引用内部资料与公开网页——这是它相对纯搜索产品最实用的差异。
• MCP 接内部数据源：设 RETRIEVER=tavily,mcp 后在构造 GPTResearcher 时传 mcp_configs，就能把 GitHub 仓库、数据库、自建 API 当成检索源之一（README 给了 @modelcontextprotocol/server-github 的完整例子）。
• 报告导出：支持导出 PDF、Word 等格式，适合直接把初稿交给非技术同事。

高级玩法

1. 用多 Agent 分工替代一次性长提示

README 的 multi-agent 部分把流程拆成「规划 → 检索 → 写作 → 评审」多个专职 Agent。相比把所有要求塞进一个超长 prompt，分工的好处是每一段都有自己的验收标准；代价是 token 消耗上升，长主题要设预算上限。

2. 递归深入研究：广度与深度分开控制

递归模式会先横向铺开子主题，再对关键分支下钻。实操建议是两级预算分开设：一级控制「铺多宽」，二级控制「钻多深」。只调总预算会让它要么铺得太散（每个分支都很浅），要么一头扎进某个分支（覆盖不全）。

3. 让它顺手生成配图

README 提到可以用 Google Gemini（Nano Banana）生成插图并嵌入报告，开关是 .env 里的 IMAGE_GENERATION_ENABLED=true。做对外材料时记得在报告里保留「图片由 AI 生成」的说明，别让人误以为是实拍或官方图。

4. 把追踪接上，看它到底在干什么

设好 LangSmith 三个环境变量后，每次研究都会留下可回看的轨迹：哪一步拆了哪些子问题、抓了哪些页面、哪些被过滤掉。调质量时先看轨迹再改 prompt，比反复重跑省得多。

五个小技巧

1. 先跑「窄主题」再跑「宽主题」：窄主题能暴露配置问题，宽主题只会把问题放大成噪声。
2. 检索 Key 的额度往往先于模型额度耗尽，长跑前先看检索侧配额。
3. 子问题数量不是越多越好：6–10 个通常能覆盖一份结构化报告，过多会让每个子问题只抓到皮毛。
4. 报告里的引用要按「官方文档 > 一手数据 > 二手报道」分级读，不要因为带链接就当事实。
5. 把它当「初稿机」：人工负责判断与取舍，Agent 负责把资料找齐、把结构搭好。

常见踩坑

以下为基于官方 README、限制说明与常见集成方式整理的排障思路，不是本站亲历记录。

坑 1：只设了模型 Key，忘了检索 Key

症状：启动就报缺环境变量，或研究阶段直接空转。原因：README 的起步示例要求同时设置 OPENAI_API_KEY 与 TAVILY_API_KEY，检索是它的一半能力。解决：两个 Key 都配好，或用 RETRIEVER 换成你已有的检索通道。

坑 2：以为它给的引用天然可信

症状：报告结论漂亮，点开引用发现是二手博客或内容农场。原因：抓取层只保证「抓到了、记录了来源」，不保证来源质量；README 的免责声明也写明这是实验性应用、按 Apache 2.0「as-is」提供。解决：把「来源分级」写进你的提示词，并对关键结论做人工复核。

坑 3：长主题跑到一半成本失控

症状：一次研究消耗远超预期。原因：递归深入研究与多 Agent 会并发发起大量检索与模型调用，宽度和深度都放大开销。解决：先小预算试跑，确认质量与成本曲线后再放开；检索与模型分别设上限。

坑 4：本地文档混检没生效

症状：报告里完全没有内部资料的内容。原因：本地研究需要把文档放进指定目录并启用对应检索配置，不是「放进去就自动读」。解决：按文档站的 local research 章节配置，先用一份已知答案的文档做对照测试。

坑 5：MCP 接了但检索结果没变化

症状：设了 RETRIEVER=tavily,mcp，报告里看不到 MCP 数据源的痕迹。原因：mcp_configs 要在构造研究对象时传入（含命令、参数与环境变量），只改环境变量不够。解决：照 README 的 GitHub MCP 例子先跑一遍最小可用配置，确认轨迹里出现 MCP 调用再加源。

坑 6：前端 8000 端口打不开

症状：uvicorn main:app --reload 起来了，浏览器访问无响应。原因：端口被占用、或依赖没装全（README 要求先 pip install -r requirements.txt）。解决：换端口启动、检查依赖安装输出；容器化部署时确认端口映射。

常见问题 FAQ

Q1：它和 Perplexity 这类搜索产品有什么不同？

A：Perplexity 是「带引用的即时问答」，交付物是一段答案；GPT Researcher 交付的是一份多章节长报告，中间过程（拆题、并行检索、聚合）可被你改写和复用。本站另有 Perplexity 条目可对照。

Q2：和 Deer Flow 这类开源深度研究框架比呢？

A：两者都是开源、都把「研究」拆成多 Agent 流水线。Deer Flow 更偏「研究 + 播客/PPT 等衍生内容」的全栈工作台（本站条目见 Deer Flow），GPT Researcher 更聚焦「检索 → 报告」这一段，且提供 pip 包形态便于嵌入自有系统。选哪个取决于你要的是工作台还是零件。

Q3：一定要用 OpenAI 的模型吗？

A：不必须。README 说明可以设 OPENAI_BASE_URL 指向 OpenAI 兼容接口，因此本地模型或其它厂商的兼容端点也能用；具体支持范围以文档站为准。

Q4：要花钱吗？花多少？

A：代码 Apache-2.0，软件免费；费用来自模型调用与检索 API。README 没有公布统一价目，本站不推测金额——请按你选的模型与检索厂商的官方定价自行估算。

Q5：报告能直接对外发布吗？

A：不建议。它是研究初稿：来源质量参差、可能有推断被写成结论。对外发布前必须人工核对每条关键结论的出处，并说明是否使用了 AI 辅助。

Q6：能接内部知识库吗？

A：两条路：本地文档检索（local research），或通过 MCP 接自建数据源。前者适合静态资料，后者适合需要实时查询的内部系统。

成本、权限与安全边界

许可：Apache-2.0（LICENSE）。软件免费，模型与检索按各自厂商计费。

数据面要提前想清楚：它会把你的查询、抓到的网页内容、以及混检时的本地文档片段送进模型请求。接内部资料前，先确认这些内容允许出境/出内网，以及检索厂商的数据保留策略。

权限面：跑服务形态时，它需要能出网抓页面；本地文档模式会给它读你指定目录的权限。建议单独目录、单独凭据、单独预算，不要和别的自动化共用一份 .env。

质量面：README 自己的免责声明写着这是实验性应用、按「as-is」提供，并且明确不构成学术建议。把它的输出定位成「需要复核的初稿」，而不是「可以直接签字的研究结论」。

进阶学习建议

• 架构线：读 How it Works 与 README 的 Architecture 段，重点看 planner 如何生成子问题、publisher 如何聚合——这决定了你该怎么写主题描述。
• 集成线：把 MCP 最小例子跑通（RETRIEVER=tavily,mcp + GitHub MCP server），再把检索源换成你自己的数据库或工单系统，这一步是把通用工具变成本团队工具的关键。
• 可控线：接上 LangSmith 追踪，做一次「同主题、两种子问题拆法」的对照实验，用轨迹而不是感觉判断哪种拆法更好。
• 工程线：读 CONTRIBUTING 与路线图，如果你想长期用，最好知道上游接下来会改什么。

免责声明

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。 文中安装命令、示例脚本与配置片段均为文档说明，未在本站环境执行；不同模型与检索通道下的实际效果需要自行验证。

参考链接

• 官方仓库与 README
• 官方文档站
• MCP 集成指南
• 前端部署说明
• Apache-2.0 许可文本
• Deer Flow（同类框架对照）
• Perplexity（搜索产品对照）