GPT Researcher 深度研究 Agent 完整指南架构原理、安装配置与实战用法【免费下载链接】gpt-researcherAn autonomous agent that conducts deep research on any data using any LLM providers项目地址: https://gitcode.com/GitHub_Trending/gp/gpt-researcherGPT Researcher是当前仓库 gpt-researcher 提供的开源自主研究 Agent它接收任意研究任务query自动完成规划子问题—多路并行检索—内容抓取与去重—带引用聚合生成的完整闭环同时支持网页与本地文档两种数据来源并可与任意 LLM Provider 对接。读完本文你将掌握GPT Researcher 的 Planner/Execution/Publisher 核心架构及其在仓库源码中的落地形态、源码级配置体系gpt_researcher/config/variables/default.py、从命令行/API 服务/PIP 包/Docker 四种方式启动它的完整流程以及 MCP 数据源接入、行内图片生成、Deep Research 递归研究、多智能体编排、本地文档研究等高级用法。一、为什么需要 GPT Researcher解决研究任务的五大痛点GPT Researcher 的设计动机直指传统研究流程与现成 LLM 方案的核心短板这些动机在 README.md 中被明确列出也是理解整个项目技术选型的起点痛点GPT Researcher 的应对方式人工客观研究可能耗时数周需要海量资源与时间将研究拆解为可并行执行的 Agent 任务通过并行化显著提速基于过时数据训练的 LLM 会产生幻觉无法胜任时效性研究实时检索网页与本地文档让结论建立在最新、可验证的资料来源之上当前 LLM 存在 token 限制无法生成超长研究报告采用分块上下文管理与分段写作支持生成 2000 词的长报告现有服务可用网络来源有限导致信息失真、结论肤浅单次研究聚合 20 来源用高频共识降低单点错误概率选择性取材会向研究引入偏见多来源交叉验证 均匀呈现多元观点尽量压低系统性偏差其中多来源共识降低错误率这一理念在项目首页的免责声明中有更直白的表述抓取的站点越多全部同时出错的可能性就越低工具的目的不是消灭偏差而是尽可能减少偏差并把多元观点均衡呈现给读者。二、核心架构Planner 与 Execution Agent 的分工协作2.1 总体设计GPT Researcher 的核心思路在 README.md 的 Architecture 一节有精炼描述利用 planner规划与 execution执行两类 Agent。Planner 负责生成研究问题Execution Agents 负责收集相关信息最终由 publisher 汇总所有发现聚合为一份完整报告。仓库中的架构图直观展示了这一流程2.2 五步研究流水线README 给出的研究步骤如下根据研究 query 创建一个任务专属 Agent生成一组问题共同构成对该任务的客观观点使用爬虫 Agent 为每个问题收集信息对每份资源做摘要并追踪来源过滤并聚合各摘要形成最终研究报告。2.3 源码中的落地形态从源码结构看上述每一步都能在 gpt_researcher/agent.py 的GPTResearcher类中找到对应实现Agent 选择conduct_research()在未显式传入agent/role时会调用choose_agent()来自 gpt_researcher/actions为查询挑选最合适的专属 Agent 角色如学术研究、金融分析等问题生成与检索ResearchConductorgpt_researcher/skills/researcher.py负责把主查询拆分为子查询并驱动检索抓取与摘要BrowserManagergpt_researcher/skills/browser.py与SourceCuratorgpt_researcher/skills/curator.py负责网页抓取、内容质量筛选与来源跟踪上下文管理ContextManagergpt_researcher/skills/context_manager.py维护整个研究过程中的记忆与上下文对应 README 的研究全程保持记忆与上下文特性报告生成ReportGeneratorgpt_researcher/skills/writer.py扮演 publisher 角色将所有上下文聚合为最终报告并通过add_references()追加引用列表。两个核心异步方法是conduct_research()执行检索并累积self.context与write_report()基于 context 生成报告这正是下文 PIP 包用法中调用的两个 API。三、特性总览README 将功能亮点概括如下逐一对应仓库中的实现双源研究支持网页与本地文档PDF、纯文本、CSV、Excel、Markdown、PowerPoint、Word对应report_source枚举见 gpt_researcher/utils/enum.py 中的ReportSource智能图片抓取与筛选研究阶段自动收集并过滤配图get_research_images()/add_research_images()AI 行内插图使用 Google GeminiNano Banana 系列模型自动生成插画并嵌入报告2000 词长报告默认TOTAL_WORDS为 1200SMART_TOKEN_LIMIT为 12000支持超长输出20 来源聚合RETRIEVER可配置为 tavily、google、searx、bing、brave、duckduckgo、exa、arxiv、semantic_scholar 等十余种检索器见 gpt_researcher/retrievers 目录配合多来源并行合并实现客观结论双前端轻量级 HTML/CSS/JS 静态前端由 FastAPI 直接托管与生产级 NextJS Tailwind 前端frontend/nextjsJavaScript 渲染网页抓取基于浏览器引擎的抓取能力gpt_researcher/scraper/browser记忆与上下文Memory组件gpt_researcher/memory提供向量化记忆后端多格式导出PDF、Word、Markdowncli.py 中write_md_to_pdf/write_md_to_word落地。四、快速开始四种启动方式4.1 源码安装与启动服务FastAPIREADME 推荐的本地起步流程如下要求 Python 3.11 及以上git clone https://gitcode.com/GitHub_Trending/gp/gpt-researcher cd gpt-researcher配置 API Key——通过环境变量导出或写入项目根目录的.env文件仓库已通过 docker-compose.yml 与 main.py 中的load_dotenv()支持.env加载export OPENAI_API_KEY{Your OpenAI API Key here} export TAVILY_API_KEY{Your Tavily API Key here}可选开启 LangChain 链路追踪# export LANGCHAIN_TRACING_V2true # export LANGCHAIN_API_KEY{Your LangChain API Key here}对接自定义 OpenAI 兼容 API本地模型或其他厂商export OPENAI_BASE_URL{Your custom API base URL here}安装依赖并启动pip install -r requirements.txt python -m uvicorn main:app --reload浏览器访问 http://localhost:8000 即可开始使用。仓库入口 main.py 会先创建logs/目录、配置双通道日志文件 控制台再加载.env最后以0.0.0.0:8000启动 uvicornFastAPI 应用本体位于 backend/server/app.py。4.2 安装为 Claude Skill若希望将深度研究能力直接注入 Claude 对话中README 提供了一行命令安装方式npx skills add assafelovic/gpt-researcher安装后Claude 便可在对话中直接调用 GPT Researcher 的深度研究能力。仓库中对应 Skill 定义见 skills/gpt-researcher/SKILL.md。4.3 作为 PIP 包使用pip install gpt-researcher最小示例核心就是两个异步调用from gpt_researcher import GPTResearcher query why is Nvidia stock going up? researcher GPTResearcher(queryquery) # Conduct research on the given query research_result await researcher.conduct_research() # Write the report report await researcher.write_report()GPTResearcher构造器gpt_researcher/agent.py提供了非常丰富的参数README 之外还支持参数说明默认值report_type报告类型见下方枚举research_reportreport_format报告输出格式markdownreport_source数据来源web / local / hybrid / azure 等webtone写作语气Tone枚举objectivesource_urls/document_urls指定来源 URL 列表Nonequery_domains限定搜索域名列表Nonevector_store/vector_store_filter向量库及其过滤条件Nonemcp_configsMCP 服务器配置列表Nonemcp_strategyMCP 执行策略fast/deep/disabledfast报告类型与语气在 gpt_researcher/utils/enum.py 中以枚举形式完整定义ReportTyperesearch_report、resource_report、outline_report、custom_report、detailed_report、subtopic_report、deepReportSourceweb、local、azure、langchain_documents、langchain_vectorstore、static、hybridToneobjective、formal、analytical、persuasive、informative、explanatory、descriptive、critical、comparative、speculative、reflective、narrative、humorous、optimistic、pessimistic、simple、casual共 17 种。更多示例与配置可参考仓库文档 PIP 包指南 与 示例 Notebook。4.4 命令行接口CLI仓库提供了功能完整的 CLIcli.py适合脚本化、批量化生成报告。基本用法python cli.py query --report_type report_type --tone tone --query_domains foo.com,bar.com可用参数一览query位置参数研究查询--report_type必填可选research_report摘要型约 2 分钟、detailed_report深度型约 5 分钟、resource_report、outline_report、custom_report、subtopic_report、deep--tone15 种语气之一默认objective--encoding输出文件编码默认utf-8--query_domains逗号分隔的限定域名列表--report_sourceweb/local/hybrid/azure/langchain_documents/langchain_vectorstore/static默认web--no-pdf跳过 PDF 生成仅输出 Markdown 与 DOCX--no-docx跳过 DOCX 生成仅输出 Markdown 与 PDF。CLI 输出非常工程化会用 fast LLM 生成 ≤20 字符的简洁标题作为文件名主干失败则回退到 query自动清理 Windows/Linux 非法文件名字符为 Markdown 添加包含task_id、query、report_type、created_at、sources_count、total_cost_usd的 YAML frontmatter并在outputs/目录下同时产出 Markdown/PDF/DOCX 三份文件文件名冲突时自动追加_2、_3后缀。五、配置体系默认配置与覆盖规则所有配置集中在 gpt_researcher/config/variables/default.py由 gpt_researcher/config/config.py 的Config类加载。其覆盖优先级为环境变量 配置文件 默认值见_set_attributes()中os.getenv(key)优先逻辑。核心配置项速查表默认值取自 default.py配置项默认值说明RETRIEVERtavily搜索引擎/检索器可逗号分隔多个EMBEDDINGopenai:text-embedding-3-small向量化模型FAST_LLM/SMART_LLM/STRATEGIC_LLMopenai:gpt-5.4-mini/openai:gpt-5.4/openai:gpt-5.4快速/智能/策略三层 LLMSTRATEGIC 用于规划可配REASONING_EFFORT权衡速度与深度FAST_TOKEN_LIMIT/SMART_TOKEN_LIMIT/STRATEGIC_TOKEN_LIMIT6000 / 12000 / 8000各层输出 token 上限TOTAL_WORDS1200目标报告词数REPORT_FORMATAPA报告引用格式MAX_ITERATIONS3研究最大迭代轮数MAX_SUBTOPICS3子主题数量上限SCRAPERbs抓取器类型另有浏览器、firecrawl、pymupdf 等MAX_SCRAPER_WORKERS15抓取并发 worker 数SIMILARITY_THRESHOLD0.42上下文去重相似度阈值REPORT_SOURCEweb默认数据来源DOC_PATH./my-docs本地文档目录DEEP_RESEARCH_BREADTH/DEPTH/CONCURRENCY3 / 2 / 4Deep Research 宽度/深度/并发MCP_STRATEGYfastMCP 执行策略IMAGE_GENERATION_ENABLED/MODEL/MAX_IMAGES/STYLEFalse/models/gemini-2.5-flash-image/ 3 / dark行内图片生成开关与参数LANGUAGEenglish报告语言TEMPERATURE0.4LLM 采样温度从源码结构看配置还支持通过config_path传入 JSON 配置文件仓库示例见 gpt_researcher/config/variables/test_local.json适合本地文档/私有部署场景。详细配置说明可参考仓库文档 config.md。六、MCP Client接入外部数据源GPT Researcher 原生支持 MCPModel Context Protocol集成可连接 GitHub 仓库、数据库、自定义 API 等专用数据源实现网页搜索 MCP混合研究。启用混合模式环境变量方式export RETRIEVERtavily,mcp # Enable hybrid web MCP research代码方式更推荐可避免污染全局环境变量——源码中_process_mcp_configs()特意通过修改cfg.retrievers而非os.environ来规避进程级环境变量污染问题from gpt_researcher import GPTResearcher import asyncio import os async def mcp_research_example(): # Enable MCP with web search os.environ[RETRIEVER] tavily,mcp researcher GPTResearcher( queryWhat are the top open source web research agents?, mcp_configs[ { name: github, command: npx, args: [-y, modelcontextprotocol/server-github], env: {GITHUB_TOKEN: os.getenv(GITHUB_TOKEN)} } ] ) research_result await researcher.conduct_research() report await researcher.write_report() return reportMCP 服务器配置字典支持的字段见 gpt_researcher/agent.py包括name服务器名、command启动命令、args命令参数、tool_name指定使用哪个工具、env环境变量、connection_url/connection_typestdio / websocket / http 远程连接、connection_token远程连接鉴权。MCP 执行策略有三种MCP_STRATEGYfast默认仅用原始 query 跑一次 MCP性能最优、deep为所有子查询跑 MCP覆盖最全、disabled完全跳过 MCP。MCP 检索器实现见 gpt_researcher/retrievers/mcp相关配置与高级用法可参考仓库文档 MCP 配置指南。七、行内 AI 图片生成Nano Banana启用后GPT Researcher 会在研究阶段自动识别可视化机会预生成 2~3 张与内容相关的 AI 插画并在报告写作时内联嵌入。在.env中配置IMAGE_GENERATION_ENABLEDtrue GOOGLE_API_KEYyour_google_api_key IMAGE_GENERATION_MODELmodels/gemini-2.5-flash-image工作流程与源码 gpt_researcher/agent.py 中conduct_research()的图片预生成逻辑一致研究完成、写报告之前系统分析研究上下文识别可视化机会plan_and_generate_images()实现见 gpt_researcher/skills/image_generator.py预生成 2~3 张相关图片数量由IMAGE_GENERATION_MAX_IMAGES控制默认 3在write_report()时将预生成图片内联嵌入正文。生成的图片默认采用深色系风格IMAGE_GENERATION_STYLEdark与 GPT Researcher 的 UI 主题一致呈现青绿色点缀的专业信息图风格。可选模型参考 default.py 中的注释免费档为gemini-2.5-flash-image、gemini-2.0-flash-exp-image-generation付费档为imagen-4.0-generate-001、imagen-4.0-fast-generate-001同时支持modelslab作为备选图片生成提供商。更完整的说明见仓库文档 图片生成指南。八、Deep Research树状递归研究GPT Researcher 内置的 Deep Research 是一套高级递归研究工作流采用树状探索模式向下深挖子主题depth同时横向铺开覆盖面breadth并在各研究分支之间智能共享上下文。核心特性与默认参数见 default.py树状探索深度与广度均可配置DEEP_RESEARCH_DEPTH2、DEEP_RESEARCH_BREADTH3⚡并发处理多分支并发执行DEEP_RESEARCH_CONCURRENCY4跨分支智能上下文管理每个分支产生的学习成果可被兄弟分支复用避免重复检索。使用时将report_type设为deep或在 CLI 中--report_type deep。成本与耗时参考README 给出的数据基于o3-mini的 high 推理档位估算约5 分钟/次、约$0.4/次——实际耗时与成本随推理档位、宽度/深度参数而变化可通过REASONING_EFFORT调节速度与深度。Deep Research 技能核心实现在 gpt_researcher/skills/deep_research.py其中将研究上下文控制在 25k 词安全上限内并通过json_repair容错解析 LLM 输出的 JSON 结构详细文档见 Deep Research 指南。九、Docker 部署docker-compose 编排文件docker-compose.yml预置了多个服务安装 Docker复制.env.example为.env并填入 API Keys按需在 docker-compose 文件中注释掉不需要的服务启动docker-compose up --build若上述命令失败可尝试无连字符版本docker compose up --build默认未注释任何服务时会启动两个进程Python 后端运行于localhost:8000gpt-researcher服务映射my-docs、outputs、logs三个卷透传OPENAI_API_KEY、TAVILY_API_KEY、GOOGLE_API_KEY等环境变量React 前端运行于localhost:3000gptr-nextjs服务基于 frontend/nextjs 构建映射源码目录实现热更新。在任意浏览器打开localhost:3000即可开始研究。此外 compose 还包含两个可选 profiletest运行测试套件tests/report-types.py与tests/vector-store.py与discordDiscord 机器人。十、基于本地文档研究README 明确支持的本地文件格式包括PDF、纯文本、CSV、Excel、Markdown、PowerPoint 与 Word。Step 1设置环境变量DOC_PATH指向文档所在目录export DOC_PATH./my-docsStep 2二选一使用localhost:8000前端时在 Report Source 下拉框中选择My Documents使用 PIP 包时实例化GPTResearcher时传入report_sourcelocalresearcher GPTResearcher(query..., report_sourcelocal)源码层面对本地文档的加载由 gpt_researcher/document/document.py 与 gpt_researcher/document/azure_document_loader.py 等实现此外ReportSource还支持azureAzure Blob Storage 文档、langchain_documentsLangChain 文档对象与langchain_vectorstoreLangChain 向量库检索等来源详见 tailored-research 文档。十一、多智能体研究助手LangGraph / AG2随着 AI 从提示工程、RAG 走向多智能体系统GPT Researcher 基于LangGraph与AG2框架引入了多智能体助手灵感来自 STORM 论文由一组各具专长的 Agent 协同完成从规划到发布的完整研究流程显著提升研究的深度与质量。平均一次运行可产出5~6 页的研究报告支持 PDF、Docx、Markdown 多种格式。仓库实现位于 multi_agents 目录其中LangGraph 编排版见 multi_agents/main.py 与 multi_agents/langgraph.jsonAgent 角色包括 orchestrator、researcher、writer、editor、fact_checker、publisher 等multi_agents/agentsAG2 编排版见 multi_agents/ag2包含 orchestrator 与 editor 两个核心角色配套文档LangGraph 多智能体 与 AG2 多智能体。十二、可观测性LangSmith 与 Monocle12.1 LangSmith 链路追踪开启方法README 中的标准配置export LANGCHAIN_TRACING_V2true export LANGCHAIN_API_KEYyour_api_key export LANGCHAIN_PROJECTgpt-researcher开启后所有基于 LangGraph 的 Agent 交互都会被自动追踪并在 LangSmith 控制台可视化便于调试与优化复杂的多智能体工作流。12.2 MonocleOpenTelemetry 追踪可选Monocle 是基于 OpenTelemetry 的 Agent 应用追踪器可端到端记录每次运行LLM 调用、Agent 步骤、工具调用及其输入/输出、耗时与 token 数。它默认关闭需要显式安装并配置pip install gpt-researcher[monocle]在.env中配置MONOCLE_TRACINGtrue MONOCLE_EXPORTERSfile # file, console, okahu, s3, blob, gcs (default: file) OKAHU_API_KEYokh_xxxxxxxx # required only for the okahu exporter每次运行会在.monocle/目录写入一个 trace 文件可通过 Monocle 的 VS Code 扩展打开使用okahuexporter 可将多次运行的追踪汇总分析。十三、前端应用GPT Researcher 提供两套前端部署方案轻量静态前端由 FastAPI 直接托管HTML/CSS/JS适合快速体验文件见 frontendindex.html、styles.css、scripts.js生产级 NextJS 应用功能更丰富frontend/nextjs提供研究查询输入、实时进度跟踪、研究成果交互式展示与可定制的研究设置。前端通过 WebSocket 与后端通信实现研究进度实时推送WebSocket 管理器见 backend/server/websocket_manager.py并支持研究报告历史持久化backend/server/report_store.py。详细接入说明见 前端介绍文档。十四、关于无偏研究的立场README 的免责声明明确将本仓库定位为实验性应用Apache 2 协议仅供学术目的并坦诚阐述了三条立场GPT Researcher 的目标是减少错误与有偏事实抓取的站点越多信息全部出错的可能性越低它不试图消灭偏差而是尽可能降低偏差项目本质是一个探索最有效的人机交互方式的社区实践人工研究同样存在偏见研究者往往对主题已有预设立场而工具通过抓取多方观点、均衡呈现多元视角让有偏见的人也能读到其原本不会接触到的声音。这一设计哲学贯穿整个仓库多检索器并行、多来源共识、来源追踪与引用add_references、上下文去重SIMILARITY_THRESHOLD都是降低错误与偏差这一目标的工程化体现。结语从本文的梳理可以看到GPT Researcher 并非一个简单的搜索引擎 LLM 包装器而是一套层次分明的自主研究体系Planner/Execution/Publisher 架构负责任务分解与聚合多检索器与多抓取器负责信息广度Context Manager 与 Memory 维护研究深度与连续性Deep Research 与多智能体编排则在纵深与质量上更进一步。无论你是想用pip install gpt-researcher快速接入研究能力、用 CLI 批量产出带引用的报告、用 Docker 一键部署前后端还是用 MCP 打通私有数据源都可以在本仓库找到开箱即用的路径并通过 config.py 的配置体系按需定制。【免费下载链接】gpt-researcherAn autonomous agent that conducts deep research on any data using any LLM providers项目地址: https://gitcode.com/GitHub_Trending/gp/gpt-researcher创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考