企业官网建设流程全解析

GPT Researcher 入门指南：从架构原理到本地部署的完整实战

【免费下载链接】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 是一个基于任意 LLM 提供商的自主智能体，用于对各类任务进行全面的在线研究，最终产出详细、客观、有事实依据的研究报告。本指南聚焦 GPT Researcher 的入门链路：先理解其 "planner + execution agents" 的并行研究架构，再完成环境准备、API Key 配置、依赖安装与 FastAPI 服务启动，并深入源码验证每一步的底层实现，帮助你快速跑通一次完整的研究任务。

GPT Researcher 是什么

GPT Researcher 是一个自主研究智能体，设计目标是针对"综合性在线研究"类任务，产出详细、客观、无偏见的研究报告，并支持定制化配置：聚焦相关资源、自定义大纲、以及定制写作风格等。

它借鉴了学术界近期提出的 Plan-and-Solve（先规划再求解）与 RAG（检索增强生成）两篇论文的思路，专门解决在线研究场景中普遍存在的速度、确定性与可靠性问题。通过并行化的智能体协作（而非同步串行操作），它在保证稳定性的同时显著提升了研究速度。

从当前仓库源码看，这一设计被落实为gpt_researcher/agent.py中的 GPTResearcher 类，它是整个研究流程的总协调者；具体的研究规划、网页检索、上下文管理、报告写作分别由 ResearchConductor、ContextManager、ReportGenerator 等组件承担，形成了一条清晰的"编排层 - 执行层"分层结构。

为什么要用 GPT Researcher

原文档从五个角度说明了构建这类智能体的动机，这些痛点至今仍是通用 LLM 应用于研究场景的核心障碍：

• 人工研究耗时过长：要为一项研究任务形成客观结论，人工往往需要数周时间去寻找正确的资料与信息。
• LLM 知识陈旧且易幻觉：当前 LLM 的训练数据存在时效滞后，且存在严重的幻觉风险，几乎无法直接用于严肃的研究任务。
• 输出长度受限：当前 LLM 的 token 输出上限不足以支撑 2k 字以上的长篇研究报告。
• 检索范围过窄：类似 "ChatGPT + Web Plugin" 的联网方案只考虑有限的资源和内容，容易导致结论流于表面或带有偏见。
• 资源选择偏差：仅使用少数几个来源本身就会在研究结论中引入系统性偏差。

GPT Researcher 通过"多源聚合 + 并行执行 + 引用跟踪"来系统性地缓解上述问题，具体体现在后面的架构设计中。

整体架构：Planner 与 Execution Agents

原文档给出了本项目的核心架构思想：

运行 "planner"（规划者）与 "execution"（执行）两类智能体：planner 生成需要研究的问题，execution agents 依据每个研究问题寻找最相关的信息；最后 planner 过滤并聚合所有相关信息，生成最终研究报告。

文档还注明，智能体使用 gpt-4o-mini 与 gpt-4o（128K 上下文）配合完成研究任务，并且只在必要时才使用更大模型以优化成本。这一"快模型打底、智能模型兜底"的策略在当前仓库配置中得到保留和演进：gpt_researcher/config/variables/default.py中默认 FAST_LLM 为openai:gpt-5.4-mini、SMART_LLM 与 STRATEGIC_LLM 均为openai:gpt-5.4，其中 SMART_LLM 被特别注明"支持 2k+ 词的长响应"，STRATEGIC_LLM 作为规划阶段使用的推理模型。

详细执行流程

原文档将研究流程拆解为如下四个具体步骤：

1. 创建领域专属智能体：根据研究查询或任务，自动选择并创建领域专属的 agent。
2. 生成一组研究问题：生成一组研究问题，它们共同构成对任意给定任务的客观意见。
3. 触发爬虫智能体：针对每个研究问题，触发一个 crawler agent 抓取与任务相关的在线资源。
4. 总结与聚合：对每个抓取到的资源，基于相关信息进行总结并跟踪其来源；最后过滤、聚合所有总结的来源，生成最终研究报告。

从源码看，这套流程在 GPTResearcher.conduct_research 中得到了完整实现，关键环节包括：

• 智能体选择：当未显式传入agent与role时，调用 choose_agent 让 smart LLM 根据查询返回{"server": ..., "agent_role_prompt": ...}结构，优先用json_repair修复模型输出的残缺 JSON；解析失败时还有正则提取、默认 agent 兜底等多级降级策略。
• 研究执行：交由 ResearchConductor.conduct_research 完成。它先通过 plan_research 进行一次初始检索并规划出子查询大纲，再针对每个子查询并行执行"搜索 -> 抓取 -> 相似内容筛选"的完整链路。
• 报告写作：研究上下文收集完毕后，ReportGenerator.write_report 基于context、agent_role_prompt、report_type、tone等参数生成最终报告。

并行化是关键：_get_context_by_web_search中所有子查询通过asyncio.gather并发执行（见 researcher.py），这正是原文档所说"通过并行化智能体工作提升速度、替代同步操作"的代码级印证。

核心能力清单

原文档列出 GPT Researcher 的主要特性，这也是评估其适用场景时最直接的参考：

• 多类型报告生成：可生成研究报告、大纲、资源列表与研究要点等不同形式的报告。
• 长篇报告能力：能够生成超过 2K 词的详细研究报告。
• 多源聚合：每次研究平均聚合 20+ 个网络来源，以形成客观、有事实依据的结论。
• 开箱即用的 Web 界面：附带易于使用的 HTML/CSS/JS 网页界面。
• JS 支持的网页抓取：可抓取支持 JavaScript 渲染的网页内容。
• 来源跟踪：持续跟踪并记录已访问、已使用的网络来源上下文。
• 多格式导出：可将研究报告导出为 PDF、Word 等格式。

关于"多类型报告"，仓库中定义了完整的枚举集合。在 gpt_researcher/utils/enum.py 中ReportType包含research_report（标准综合报告）、resource_report（资源清单）、outline_report（大纲）、custom_report（自定义）、detailed_report（深度详细报告）、subtopic_report（子主题报告）与deep（深度研究模式）共七种类型。Tone枚举则定义了从 Objective、Formal、Analytical 到 Narrative、Humorous 等 15 种写作风格（见 enum.py），对应"定制化选项"中的写作风格维度。

环境准备与获取项目

前置要求

原文档要求Python 3.11 或更高版本。此外，运行 GPT Researcher 还需要：

• 一个 LLM 提供商的 API Key（文档推荐 OpenAI GPT，也支持 Ollama 等本地模型或其他兼容 OpenAI 的提供商，详细支持列表可参考 supported-llms.md）；
• 一个搜索引擎 API Key（文档推荐 Tavily Search API，也可换成 duckduckgo、google、bing、searchapi、serper、searx 等，参见 search-engines.md）。

克隆项目

$ git clone https://github.com/assafelovic/gpt-researcher.git $ cd gpt-researcher

（如需使用本仓库，可直接git clone https://gitcode.com/GitHub_Trending/gp/gpt-researcher.git获取副本。）

配置 API Keys

原文档提供了两种设置 API Key 的方式：直接导出环境变量，或将变量写入.env文件。

方式一：export 导出环境变量（临时）

Linux / Windows 临时会话可直接使用 export：

export OPENAI_API_KEY={Your OpenAI API Key here} export TAVILY_API_KEY={Your Tavily API Key here}

如果使用自定义的 OpenAI 兼容 API（例如本地模型或其他提供商），还可以额外设置基础 URL：

export OPENAI_BASE_URL={Your custom API base URL here}

方式二：写入 .env 文件（持久化）

在gpt-researcher目录下创建.env文件，直接填入变量名与值（不带export前缀）：

OPENAI_API_KEY=你的OpenAI密钥 TAVILY_API_KEY=你的Tavily密钥

项目在启动阶段会自动加载该文件：main.py顶部调用load_dotenv()（见 main.py），cli.py入口处同样调用load_dotenv()（见 cli.py），保证两种运行方式都能读取.env配置。

更换 LLM 与搜索引擎

• LLM 提供商：文档推荐 OpenAI GPT，但任何其他 LLM 模型（包括开源模型）均可使用。更换方式与支持的模型清单详见 llms.md。
• 搜索引擎：文档推荐 Tavily Search API，也可通过修改配置中的RETRIEVER切换为duckduckgo、google、bing、searchapi、serper、searx等，并补充对应的环境变量 API Key。仓库默认配置即"RETRIEVER": "tavily"（见 default.py），且 get_retrievers 会在初始化时依据该配置装配具体的检索器实例。

快速开始（Quickstart）

安装依赖

$ pip install -r requirements.txt

以 FastAPI 启动服务

$ uvicorn main:app --reload

启动后，在任意浏览器访问http://localhost:8000即可开始研究。

从源码看，FastAPI 应用定义在 backend/server/app.py，main.py在__main__分支中会以host="0.0.0.0", port=8000启动 uvicorn（见 main.py）；因此直接运行python main.py也能达到同样效果。前端页面由frontend/目录下的 HTML/CSS/JS 实现，服务端则通过 WebSocket 向前端实时推送研究进度（相关实现见 backend/server/websocket_manager.py）。

使用虚拟环境或 Poetry

方式一：Python venv

1. 创建虚拟环境（环境名可自定，例如env）：

python -m venv env

2. 激活虚拟环境：

# Windows PowerShell/CMD .\env\Scripts\activate

3. 安装依赖：

python -m pip install -r requirements.txt

4. 停用虚拟环境：

deactivate

方式二：Poetry

Poetry 会读取项目的pyproject.toml来确定依赖及其版本，创建隔离的虚拟环境，避免与系统全局包冲突。

1. 安装依赖并创建虚拟环境（对应 Poetry 版本约~1.7.1）：

poetry install

2. 进入 Poetry 管理的虚拟环境 shell：

poetry shell

在虚拟环境中运行应用

python -m uvicorn main:app --reload

然后访问 http://localhost:8000 开始研究。

用 CLI 直接生成研究报告

除 Web 界面外，仓库还提供命令行入口 cli.py，适合脚本化或批量研究场景。基本用法：

python cli.py "<query>" --report_type <report_type> --tone <tone> --query_domains <foo.com,bar.com>

常用参数一览（取自 cli.py 的 argparse 定义）：

CLI 的输出逻辑同样值得注意：报告生成后，会用 fast LLM 根据查询与报告预览生成一个简短标题（最多 20 字符），经文件名安全清洗后作为文件名，并在 Markdown 文件头部附加 YAML frontmatter，其中包含task_id、title、query、report_type、report_source、tone、query_domains、created_at、sources_count、total_cost_usd等元数据字段（见 cli.py），便于后续检索与溯源。默认输出到outputs/目录，同一文件名的 Markdown、PDF、DOCX 会按相同 stem 分组存放。

深入理解：研究主流程源码解析

为帮助你在部署后进一步排查问题或定制行为，这里给出研究主流程的关键代码路径（相对仓库根目录）：

• 入口与总编排：GPTResearcher 类 ——conduct_research()负责研究阶段，write_report()、write_introduction()、write_report_conclusion()负责写作阶段，quick_search()提供跳过完整流程的快速检索。
• 研究执行核心：ResearchConductor.conduct_research —— 根据report_source分支处理 web / local / hybrid / azure / langchain 等不同来源；_get_context_by_web_search实现"规划子查询 -> 并发抓取 -> 上下文组合"。
• 智能体自动选择：choose_agent —— 调用 smart LLM 返回 agent 名称与角色提示词，具备 json_repair / 正则提取 / 默认兜底三级容错。
• 报告写作：ReportGenerator.write_report —— 传入上下文、风格、提示词家族等参数生成报告；当没有任何检索内容时会主动放弃写作而不是编造（见 writer.py 的空上下文保护逻辑）。
• 报告类型与风格枚举：enum.py ——ReportType、ReportSource、Tone等全部取值定义。
• 默认配置：default.py —— 所有可调参数及其默认值（检索器、LLM 选择、token 限制、MCP 策略、深度研究参数、图片生成等）。

延伸阅读

• getting-started.md —— 官方快速上手文档，包含本文对应的完整安装步骤。
• llms.md —— 更换与配置各类 LLM 提供商的详细说明。
• search-engines.md —— 不同搜索引擎（retriever）的接入方式。
• config.md —— 全局配置项详解。
• deep_research.md —— 深度研究模式（Deep Research）的进阶用法。
• how-to-choose.md —— 如何在 Web 界面与 pip 包等不同使用方式之间选择。

【免费下载链接】gpt-researcherAn autonomous agent that conducts deep research on any data using any LLM providers项目地址: https://gitcode.com/GitHub_Trending/gp/gpt-researcher