让代理自动做完一轮资料调研（GPT Researcher）

做一次像样的资料调研，时间大多花在打开几十个页面、摘录句子、核对出处上，真正需要判断的部分反而排在最后。GPT Researcher 把这段重复劳动交出去：一个代理负责拆问题，一批代理负责抓取和摘要，最后一个把结果拼成带引用的报告。

GPT Researcher 是用 Python 写的自主研究代理，输入一个研究问题，它会自行拆出子问题、汇总 20 个以上网页来源，输出带引用的长篇研究报告。

它的流程分三步：planner 根据研究问题生成子问题，execution agent 针对每个子问题抓取网页、做摘要并标注来源，publisher 把摘要过滤聚合，写成最终报告。这个设计参考了 Plan-and-Solve 与 RAG 两篇论文的思路。仓库地址是 https://github.com/assafelovic/gpt-researcher，采用 Apache-2.0 许可证，主要语言为 Python。

仓库当前有 29861 个 Star、4072 个 Fork、20 个开放 Issue，最近一次提交在 2026-09-27。这篇文章按「用起来会遇到什么」来组织，先列坑，再拆模块，最后说清楚哪些能调、哪些调不了。

装上之后最先遇到的事

下面几条来自 README 的安装前提和仓库里已关闭的 Issue，是装完之后最容易撞上的情况。

• 跑之前得先备好两把钥匙，OPENAI_API_KEY 与 TAVILY_API_KEY，README 的安装步骤把它们写成了必填的环境变量。
• 默认检索走 Tavily，仓库里有用户报告 api.tavily.com/search 在一小时内时好时坏。
• 用 Azure OpenAI 时，光把参数写进 .env 可能不生效，会报找不到 openai_api_key。
• 在 Mac M1 上用 docker buildx 构建 linux/amd64 镜像，会撞上 system lacks support for the sse3 instruction set。
• 研究标题太长时容器里会抛 OSError: [Errno 36] File name too long。

逐个拆开看

项目本身可以按功能切成几块：检索、模型接入、多智能体研究、报告输出、部署方式。每块都有对应的坑，下面按块拆。

tavily rate limit

检索是研究流程的入口。项目支持多种检索后端，通过 RETRIEVER 环境变量切换，README 里给的写法是 export RETRIEVER=tavily,mcp，把网页搜索和 MCP 数据源拼起来同时用。默认走 Tavily，用户报告过两种限流表现：Tavily 的搜索接口在一段时间内返回结果不稳定；DuckDuckGo 直接抛限流异常，终端里在 Running research for 之后就是报错堆栈。这两个 Issue 都已标记为已解决。这一块出问题的表现往往不是明显报错，而是最终报告内容稀薄，因为抓不到东西时后面的摘要和写作会跟着空转。

Azure OpenAI .env 参数不生效

模型接入层靠环境变量指定，常见字段有 FAST_LLM、SMART_LLM、STRATEGIC_LLM 和 EMBEDDING，后者可以写成 openai:text-embedding-3-small 这种形式，配合 SIMILARITY_THRESHOLD 使用。接 Azure OpenAI 时按 .env 里的写法配置，会出现 Did not find openai_api_key, please add an environment variable 的提示，该 Issue 已关闭。想接自建或第三方兼容端点，README 给出的口子是 OPENAI_BASE_URL。

multi-agent 报告各节内容重复

多智能体模式对应仓库里的 multi_agents 目录，做的是比默认流程更深一层的研究，会围绕一个题目反复展开探索。用户反馈不同章节之间会出现冗余内容，同一件事在两三个小节里各说一遍。这个 Issue 已解决。多智能体模式和默认的单代理流程是两条路径，前者研究深度更高，出问题的面也更大。

Docker 构建 sse3 报错

部署层提供了 Dockerfile、Dockerfile.fullstack 和 docker-compose.yml。在 Mac M1 上用 docker buildx 指定 --platform linux/amd64 构建时会报 sse3 指令集不支持。相应的 Issue 已经关闭。另有用户提过希望项目直接提供预构建镜像、不用每次本地 --build 编译，这个请求也已处理。

OSError: [Errno 36] File name too long

输出层负责把结果落盘并导出，报告可以导出成 PDF、Word 等格式，写文件用的文件名来自研究查询。在 macOS 的 Docker 容器里，查询词过长会触发文件名超长错误。已关闭的 Issue 里给出的临时做法是把查询词写短一点。

哪些是限制、哪些是配置问题

属于设计限制的部分改不了。整个流程依赖外部 LLM 提供方，默认要走 OpenAI 的接口，也可用 OPENAI_BASE_URL 换成兼容端点，但总得有一个能调用的模型服务，离线跑不起来。检索同样依赖外部搜索 API，Tavily 的免费额度和限流策略不在项目控制范围内，Issue 里那些时好时坏的记录属于这一类。运行环境要求 Python 3.12 或更高版本；网页抓取依赖带 JavaScript 执行能力的浏览器，Windows 上出现过 Chrome failed to start、DevToolsActivePort file doesn't exist 这类问题，成因在浏览器而不在项目逻辑。报告长度也受限，README 说能生成超过 2000 词的报告，实际能写多长仍取决于模型的上下文窗口。

属于配置问题的部分可以在 .env 里调整。要接 Azure OpenAI 或自建端点，看 OPENAI_BASE_URL 和模型相关的那几个变量。要改检索来源，看 RETRIEVER，写法是逗号分隔，例如 tavily,mcp。要做相似度过滤，看 EMBEDDING 与 SIMILARITY_THRESHOLD。要在报告里插入 AI 生成的配图，需要打开 IMAGE_GENERATION_ENABLED=true，并配好 GOOGLE_API_KEY 与 IMAGE_GENERATION_MODEL，README 给的值是 models/gemini-2.5-flash-image，开启后系统会在研究阶段预生成 2 到 3 张图并内嵌进报告。从 v3.7.0 起，上下文筛选默认改由 Jev 按有用程度打分，不再需要 embedding 和额外的 API key，这一项就不用配了。

同类项目放在一起看

取舍很清楚：本项目默认要接外部 LLM 与搜索 API，跑一次调研会消耗 token 和搜索额度，不想为批量调研承担这部分成本的人不适合用它。两个同类项目的仓库规模小得多，能覆盖的领域很窄，同样做研究任务，但各自锁定一个很窄的方向，和本项目的通用报告生成不是同一件事，只有在你的问题正好落在细胞骨架动力学或前端路径遍历这类细分方向、且不需要长报告与多模型接入时才值得考虑。

绕开的办法

1. 不想装前端和 Docker，可以把项目当库直接用：pip install gpt-researcher，然后从 gpt_researcher 导入 GPTResearcher，构造 GPTResearcher(query=...) 后调 conduct_research() 和 write_report()。
2. 想在终端里跑，用仓库根目录的 cli.py；也可以装成 Claude Skill，命令是 npx skills add assafelovic/gpt-researcher，装好后在对话里直接调用它的深度研究能力。
3. 检索结果不稳时换后端组合，README 给的写法是 export RETRIEVER=tavily,mcp。
4. 想接自建或第三方模型服务，设 OPENAI_BASE_URL；具体字段在仓库的 .env.example 里能找到模板。
5. M1 上构建镜像报 sse3 的具体绕法，仓库里没有写清楚，需要自行评估。
6. 查询词触发文件名超长的错误，Issue 里给的做法是把查询词写短。

适合用它的人：需要定期产出带引用长报告的研究、投研和内容岗位；已经有可用的模型服务，或愿意接入 OpenAI、Tavily 的团队；想把研究能力嵌进自己 Python 程序的开发者。不适合用它的人：不想接外部 LLM 与搜索 API 的人；只做单次简单查询、不需要长报告的人；跑不了 Python 3.12 以上环境，或没有浏览器抓取条件的机器。

这个项目会主动抓取网页内容。只可用在自有资产或已获授权的目标上；对第三方站点做批量抓取可能违反其服务条款，触发 IP 封禁乃至法律风险。项目本身不做目标授权校验，这个边界由使用者自己把握。

焚评：这个项目的量化评分

本项目的选题来自 焚.com（一个按公开公式给 GitHub 项目打分的站）。焚评当前总分 9.9 分（满分 10）。下表是各维度的得分：

评分口径、权重与计算方式见焚.com 的评分方法页；数据随 GitHub 指标刷新，具体数值以焚.com 当前页面为准。本文正文为诀.com 独立撰写，评分数据由焚.com 授权引用。