assafelovic/gpt-researcher · 上手攻略

仓库：assafelovic/gpt-researcher
链接：https://github.com/assafelovic/gpt-researcher
分类：agent / llm-infra
作者：Tom
更新：2026-07-10

这是什么

GPT Researcher 是一个开源的自主深度研究 Agent，设计用于对任意主题进行系统性网络调研或本地文档分析。它受 Plan-and-Solve 和 RAG 论文启发，通过「规划 Agent + 执行 Agent」的并行架构解决传统 LLM 调研的几大痛点：信息陈旧、幻觉、Token 限制、来源单一、结论偏颇。

核心思路是：Planner 生成一组研究问题，Execution Agent 并行爬取每个问题的相关资源，Publisher 将所有结果汇总为带引用的完整报告。

解决什么问题

调研周期长：人工调研往往需要数周，GPT Researcher 将其压缩到几分钟。
LLM 幻觉：基于实时网络爬取而非过时训练数据，保证信息新鲜度。
长报告生成难：通过分段并行收集 + 最终聚合，突破单次调用 Token 上限。
来源偏差：默认聚合 20+ 个网络来源，输出更客观的结论。
多数据源需求：支持本地文档 + 网络搜索的混合研究，并可通过 MCP 扩展到 GitHub、数据库等。

快速安装

方式一：pip 安装（最简）

pip install gpt-researcher

方式二：从源码运行

# 1. 确认 Python >= 3.11
python --version

# 2. 克隆仓库
git clone https://github.com/assafelovic/gpt-researcher.git
cd gpt-researcher

# 3. 配置 API 密钥（.env 文件）
cat > .env << 'EOF'
OPENAI_API_KEY=sk-xxxx       # 主 LLM，必填
TAVILY_API_KEY=tvly-xxxx     # 网络搜索，必填
OPENAI_BASE_URL=             # 可选：自定义 OpenAI 兼容端点（如 vLLM、Ollama）
LANGCHAIN_TRACING_V2=true    # 可选：LangSmith 追踪
LANGCHAIN_API_KEY=           # 可选
EOF

# 4. 安装依赖
pip install -r requirements.txt

# 5. 启动服务
python -m uvicorn main:app --reload
# 访问 http://localhost:8000

⚠️ 注意：Python 3.11+ 是硬性要求，低版本会报依赖错误。如果用 Poetry：poetry install && poetry shell 后再启动。

核心用法

基础 Python API

from gpt_researcher import GPTResearcher
import asyncio

async def research():
    researcher = GPTResearcher(query="为什么 Nvidia 股价持续上涨？")
    # 执行调研
    research_result = await researcher.conduct_research()
    # 生成报告
    report = await researcher.write_report()
    print(report)

asyncio.run(research())

切换 LLM 提供商

默认使用 OpenAI，可在 config/config.py 中修改 LLM_PROVIDER，也支持通过环境变量指定兼容端点：

export OPENAI_BASE_URL=https://api.deepseek.com/v1  # 使用 DeepSeek 等兼容 API

支持切换为 fast（轻量模型）和 balanced（均衡）模式控制成本。

启用 MCP 扩展（网络 + 专用数据源混合）

import os
from gpt_researcher import GPTResearcher

os.environ["RETRIEVER"] = "tavily,mcp"  # 混用 Tavily + MCP

researcher = GPTResearcher(
    query="最新开源 Web 研究 Agent 有哪些？",
    mcp_configs=[{
        "name": "github",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": {"GITHUB_TOKEN": os.getenv("GITHUB_TOKEN")}
    }]
)

report = await researcher.write_report()

AI 配图生成

GPT Researcher 可在报告中自动嵌入 AI 生成的插图（调用 Google Gemini）：

# .env 中启用
IMAGE_GENERATION_ENABLED=true
GOOGLE_API_KEY=your_google_api_key
IMAGE_GENERATION_MODEL=models/gemini-2.5-flash-image

报告导出支持 PDF、Word 等格式。

典型适用场景

场景	说明
市场调研报告	竞品分析、行业趋势，分钟级生成带来源的完整报告
学术文献综述	对特定主题聚合多篇网络来源，生成客观综述
技术选型调研	调研某技术的社区活跃度、版本现状、替代方案
新闻事件深挖	突发事件多角度事实核查，20+ 来源交叉验证
本地知识库问答	上传内部文档，用 LLM 基于本地知识进行深度研究

坑与注意

API 费用：并行爬取多个来源，每轮研究可能消耗大量 Token。建议先用 fast 模式测试，确认输出质量后再切 balanced。
Tavily 限流：免费版有 QPS 限制，高频使用需升级付费计划。
中文支持：核心引擎对中文友好，但部分网络爬取来源为英文网站，摘要引用部分为英文。
中文文档有限：官方文档以英文为主，中文社区资料较少，遇到问题多查 GitHub Issues。
自托管模型：通过 OPENAI_BASE_URL 可以接 Ollama/vLLM，但默认提示词针对 GPT 系列优化较好，其他模型效果可能打折扣。
首次启动慢：依赖安装较多，pip install -r requirements.txt 可能需要 2-5 分钟。

与同类对比

项目	定位	优势	劣势
GPT Researcher	自主深度研究	并行 Agent 架构、来源追踪、MCP 扩展、报告质量高	需配置 API、部署有一定门槛
Perplexity AI	实时问答	零配置、响应快	无完整报告生成、无本地文档支持
Consensus	学术论文搜索	专注学术、质量高	仅论文、无 Agent 能力
DeepResearch (OpenAI)	深度研究	官方集成、质量稳定	付费、不可自托管
FastGPT	知识库+RAG	开源、可私有部署	更偏 RAG 知识库，非纯研究场景

GPT Researcher 的差异化在于：完全开源、可自托管、并行 Agent 架构保证了调研广度，MCP 扩展让它不只是一个网络爬虫。

一句话结论

如果你需要一份带来源、可复现、分钟级完成的深度调研报告，且希望能够自托管或接入自有 LLM，GPT Researcher 是目前开源生态里最接近 production-ready 的选择。