企业官网建设流程全解析

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-researcher

GPT 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 中被明确列出，也是理解整个项目技术选型的起点：

其中"多来源共识降低错误率"这一理念在项目首页的免责声明中有更直白的表述：抓取的站点越多，全部同时出错的可能性就越低；工具的目的不是"消灭"偏差，而是"尽可能减少"偏差，并把多元观点均衡呈现给读者。

二、核心架构：Planner 与 Execution Agent 的分工协作

2.1 总体设计

GPT Researcher 的核心思路在 README.md 的 Architecture 一节有精炼描述：利用 planner（规划）与 execution（执行）两类 Agent。Planner 负责生成研究问题，Execution Agents 负责收集相关信息，最终由 publisher 汇总所有发现，聚合为一份完整报告。

仓库中的架构图直观展示了这一流程：

2.2 五步研究流水线

README 给出的研究步骤如下：

1. 根据研究 query 创建一个任务专属 Agent；
2. 生成一组问题，共同构成对该任务的客观观点；
3. 使用爬虫 Agent 为每个问题收集信息；
4. 对每份资源做摘要并追踪来源；
5. 过滤并聚合各摘要，形成最终研究报告。

2.3 源码中的落地形态

从源码结构看，上述每一步都能在 gpt_researcher/agent.py 的GPTResearcher类中找到对应实现：

• Agent 选择：conduct_research()在未显式传入agent/role时，会调用choose_agent()（来自 gpt_researcher/actions）为查询挑选最合适的专属 Agent 角色（如学术研究、金融分析等）；
• 问题生成与检索：ResearchConductor（gpt_researcher/skills/researcher.py）负责把主查询拆分为子查询并驱动检索；
• 抓取与摘要：BrowserManager（gpt_researcher/skills/browser.py）与SourceCurator（gpt_researcher/skills/curator.py）负责网页抓取、内容质量筛选与来源跟踪；
• 上下文管理：ContextManager（gpt_researcher/skills/context_manager.py）维护整个研究过程中的记忆与上下文，对应 README 的"研究全程保持记忆与上下文"特性；
• 报告生成：ReportGenerator（gpt_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 Gemini（Nano Banana 系列模型）自动生成插画并嵌入报告；
• 2000+ 词长报告：默认TOTAL_WORDS为 1200，SMART_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/nextjs）；
• JavaScript 渲染网页抓取：基于浏览器引擎的抓取能力（gpt_researcher/scraper/browser）；
• 记忆与上下文：Memory组件（gpt_researcher/memory）提供向量化记忆后端；
• 多格式导出：PDF、Word、Markdown（cli.py 中write_md_to_pdf/write_md_to_word落地）。

四、快速开始：四种启动方式

4.1 源码安装与启动服务（FastAPI）

README 推荐的本地起步流程如下（要求 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_V2=true # 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启动 uvicorn；FastAPI 应用本体位于 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(query=query) # 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 之外还支持：

报告类型与语气在 gpt_researcher/utils/enum.py 中以枚举形式完整定义：

• ReportType：research_report、resource_report、outline_report、custom_report、detailed_report、subtopic_report、deep；
• ReportSource：web、local、azure、langchain_documents、langchain_vectorstore、static、hybrid；
• Tone：objective、formal、analytical、persuasive、informative、explanatory、descriptive、critical、comparative、speculative、reflective、narrative、humorous、optimistic、pessimistic、simple、casual共 17 种。

更多示例与配置可参考仓库文档 PIP 包指南 与 示例 Notebook。

4.4 命令行接口（CLI）

仓库提供了功能完整的 CLI（cli.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；
• --tone：15 种语气之一，默认objective；
• --encoding：输出文件编码，默认utf-8；
• --query_domains：逗号分隔的限定域名列表；
• --report_source：web/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）：

从源码结构看，配置还支持通过config_path传入 JSON 配置文件（仓库示例见 gpt_researcher/config/variables/test_local.json），适合本地文档/私有部署场景。详细配置说明可参考仓库文档 config.md。

六、MCP Client：接入外部数据源

GPT Researcher 原生支持 MCP（Model Context Protocol）集成，可连接 GitHub 仓库、数据库、自定义 API 等专用数据源，实现"网页搜索 + MCP"混合研究。

启用混合模式（环境变量方式）：

export RETRIEVER=tavily,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( query="What 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 report

MCP 服务器配置字典支持的字段（见 gpt_researcher/agent.py）包括：name（服务器名）、command（启动命令）、args（命令参数）、tool_name（指定使用哪个工具）、env（环境变量）、connection_url/connection_type（stdio / websocket / http 远程连接）、connection_token（远程连接鉴权）。

MCP 执行策略有三种（MCP_STRATEGY）：fast（默认，仅用原始 query 跑一次 MCP，性能最优）、deep（为所有子查询跑 MCP，覆盖最全）、disabled（完全跳过 MCP）。MCP 检索器实现见 gpt_researcher/retrievers/mcp，相关配置与高级用法可参考仓库文档 MCP 配置指南。

七、行内 AI 图片生成（Nano Banana）

启用后，GPT Researcher 会在研究阶段自动识别可视化机会，预生成 2~3 张与内容相关的 AI 插画，并在报告写作时内联嵌入。在.env中配置：

IMAGE_GENERATION_ENABLED=true GOOGLE_API_KEY=your_google_api_key IMAGE_GENERATION_MODEL=models/gemini-2.5-flash-image

工作流程（与源码 gpt_researcher/agent.py 中conduct_research()的图片预生成逻辑一致）：

1. 研究完成、写报告之前，系统分析研究上下文，识别可视化机会（plan_and_generate_images()，实现见 gpt_researcher/skills/image_generator.py）；
2. 预生成 2~3 张相关图片（数量由IMAGE_GENERATION_MAX_IMAGES控制，默认 3）；
3. 在write_report()时将预生成图片内联嵌入正文。

生成的图片默认采用深色系风格（IMAGE_GENERATION_STYLE=dark），与 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_DEPTH=2、DEEP_RESEARCH_BREADTH=3）；
• ⚡并发处理：多分支并发执行（DEEP_RESEARCH_CONCURRENCY=4）；
• 🤝跨分支智能上下文管理：每个分支产生的学习成果可被兄弟分支复用，避免重复检索。

使用时将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）预置了多个服务：

1. 安装 Docker）；
2. 复制.env.example为.env并填入 API Keys；
3. 按需在 docker-compose 文件中注释掉不需要的服务；
4. 启动：

docker-compose up --build

若上述命令失败，可尝试无连字符版本：

docker compose up --build

默认（未注释任何服务时）会启动两个进程：

• Python 后端：运行于localhost:8000（gpt-researcher服务，映射my-docs、outputs、logs三个卷，透传OPENAI_API_KEY、TAVILY_API_KEY、GOOGLE_API_KEY等环境变量）；
• React 前端：运行于localhost:3000（gptr-nextjs服务，基于 frontend/nextjs 构建，映射源码目录实现热更新）。

在任意浏览器打开localhost:3000即可开始研究。此外 compose 还包含两个可选 profile：test（运行测试套件tests/report-types.py与tests/vector-store.py）与discord（Discord 机器人）。

十、基于本地文档研究

README 明确支持的本地文件格式包括：PDF、纯文本、CSV、Excel、Markdown、PowerPoint 与 Word。

Step 1：设置环境变量DOC_PATH指向文档所在目录：

export DOC_PATH="./my-docs"

Step 2（二选一）：

• 使用localhost:8000前端时，在 "Report Source" 下拉框中选择"My Documents"；
• 使用 PIP 包时，实例化GPTResearcher时传入report_source="local"：

researcher = GPTResearcher(query="...", report_source="local")

源码层面对本地文档的加载由 gpt_researcher/document/document.py 与 gpt_researcher/document/azure_document_loader.py 等实现；此外ReportSource还支持azure（Azure Blob Storage 文档）、langchain_documents（LangChain 文档对象）与langchain_vectorstore（LangChain 向量库检索）等来源，详见 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.json，Agent 角色包括 orchestrator、researcher、writer、editor、fact_checker、publisher 等（multi_agents/agents）；
• AG2 编排版：见 multi_agents/ag2，包含 orchestrator 与 editor 两个核心角色；
• 配套文档：LangGraph 多智能体 与 AG2 多智能体。

十二、可观测性：LangSmith 与 Monocle

12.1 LangSmith 链路追踪

开启方法（README 中的标准配置）：

export LANGCHAIN_TRACING_V2=true export LANGCHAIN_API_KEY=your_api_key export LANGCHAIN_PROJECT="gpt-researcher"

开启后，所有基于 LangGraph 的 Agent 交互都会被自动追踪并在 LangSmith 控制台可视化，便于调试与优化复杂的多智能体工作流。

12.2 Monocle（OpenTelemetry 追踪，可选）

Monocle 是基于 OpenTelemetry 的 Agent 应用追踪器，可端到端记录每次运行：LLM 调用、Agent 步骤、工具调用及其输入/输出、耗时与 token 数。它默认关闭，需要显式安装并配置：

pip install "gpt-researcher[monocle]"

在.env中配置：

MONOCLE_TRACING=true MONOCLE_EXPORTERS=file # file, console, okahu, s3, blob, gcs (default: file) OKAHU_API_KEY=okh_xxxxxxxx # required only for the `okahu` exporter

每次运行会在.monocle/目录写入一个 trace 文件，可通过 Monocle 的 VS Code 扩展打开；使用okahuexporter 可将多次运行的追踪汇总分析。

十三、前端应用

GPT Researcher 提供两套前端部署方案：

1. 轻量静态前端：由 FastAPI 直接托管（HTML/CSS/JS），适合快速体验，文件见 frontend（index.html、styles.css、scripts.js）；
2. 生产级 NextJS 应用：功能更丰富（frontend/nextjs），提供研究查询输入、实时进度跟踪、研究成果交互式展示与可定制的研究设置。

前端通过 WebSocket 与后端通信实现研究进度实时推送（WebSocket 管理器见 backend/server/websocket_manager.py），并支持研究报告历史持久化（backend/server/report_store.py）。详细接入说明见 前端介绍文档。

十四、关于"无偏研究"的立场

README 的免责声明明确将本仓库定位为实验性应用（Apache 2 协议，仅供学术目的），并坦诚阐述了三条立场：

1. GPT Researcher 的目标是减少错误与有偏事实：抓取的站点越多，信息全部出错的可能性越低；
2. 它不试图消灭偏差，而是尽可能降低偏差，项目本质是一个探索"最有效的人机交互方式"的社区实践；
3. 人工研究同样存在偏见（研究者往往对主题已有预设立场），而工具通过抓取多方观点、均衡呈现多元视角，让有偏见的人也能读到其原本不会接触到的声音。

这一设计哲学贯穿整个仓库：多检索器并行、多来源共识、来源追踪与引用（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