GPT Researcher CLI 使用指南：从安装、参数详解到报告输出全流程-开发者社区

GPT Researcher CLI 使用指南：从安装、参数详解到报告输出全流程

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

本篇指南以 docs/docs/gpt-researcher/getting-started/cli.md 为骨架，带你全面掌握 gpt-researcher 命令行工具：如何完成安装与环境配置、如何使用cli.py生成多种类型的报告、如何通过--tone控制文风，并结合仓库源码（cli.py、enum.py 等）深入讲解每个参数的底层含义与输出文件机制。读完本文，你将能够独立用一条命令完成从"问题"到"结构化研究报告（Markdown / PDF / DOCX）"的全流程。

一、CLI 是什么

cli.py是 gpt-researcher 提供的命令行入口，它基于argparse封装了核心的GPTResearcher类（位于 gpt_researcher/agent.py），让你无需编写 Python 代码即可对任意主题发起自主研究，并生成多种类型的报告。

从 cli.py 的导入语句可以看出它的核心依赖：

GPTResearcher：负责检索、抓取、上下文管理与报告生成的主 Agent；
DetailedReport：detailed_report类型报告的高级编排器（位于 backend/report_type/detailed_report/detailed_report.py）；
write_md_to_pdf/write_md_to_word：负责将 Markdown 报告转换为 PDF 与 DOCX；
ReportSource/ReportType/Tone：报告类型、数据源与语气风格的枚举定义（位于 gpt_researcher/utils/enum.py）。

二、安装与环境配置

1. 克隆仓库

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

2. 安装依赖

pip install -r requirements.txt

根目录下的 requirements.txt 会一并安装后端依赖与核心库；若需集成监控追踪等可选能力，可参考 .env.example 中的说明按需安装额外 extras。

3. 配置环境变量

在项目根目录创建.env文件并填入 API Key 等必要配置。仓库提供了 .env.example 作为模板，其中至少需要关注以下几类变量：

LLM 提供方：OPENAI_API_KEY（默认 LLM 为 OpenAI，见 gpt_researcher/config/variables/default.py 中的FAST_LLM/SMART_LLM/STRATEGIC_LLM）；
检索服务：TAVILY_API_KEY（默认 retriever 为 Tavily）、BRAVE_API_KEY、XQUIK_API_KEY、GETXAPI_API_KEY、GROUNDROUTE_API_KEY等，按需选择；
学术检索（可选）：OPENALEX_EMAIL、OPENALEX_API_KEY、NCBI_API_KEY；
本地文档路径：DOC_PATH=./my-docs，供local/hybrid等--report_source使用。

注意：cli.py在入口处通过load_dotenv()加载.env（见 cli.py），因此请务必在项目根目录配置好环境变量，否则研究过程会因缺少 API 凭证而失败。

三、基本用法与参数详解

基本语法

python cli.py "<query>" --report_type <report_type> [--tone <tone>]

位置参数：query（必填）

要研究的问题，作为位置参数传入，建议用双引号包裹。例如：

python cli.py "What are the main causes of climate change?" --report_type research_report

--report_type（必填）

报告类型。其取值由 gpt_researcher/utils/enum.py 中的ReportType枚举定义，当前支持以下值：

取值	说明	预期耗时
`research_report`	摘要式报告	短而快（约 2 分钟）
`detailed_report`	深度详细报告	更长（约 5 分钟）
`resource_report`	资源清单类报告	-
`outline_report`	提纲类报告	-
`custom_report`	自定义格式报告	-
`subtopic_report`	子主题聚焦报告	-
`deep`	深度研究模式	视广度/深度配置而定

注意与文档早期版本相比，cli.py的report_type_descriptions中还包含deep（Deep Research）这一选项（见 cli.py）。

--tone（可选，默认 objective）

控制报告的文风。源码中该参数通过一个固定的字符串列表做参数校验（见 cli.py），随后在main()中映射为Tone枚举值（见 cli.py）。支持取值及含义如下：

取值	风格
`objective`	客观、不偏不倚地陈述事实
`formal`	学术规范、措辞严谨
`analytical`	批判性评估与深入剖析
`persuasive`	说服性观点表达
`informative`	清晰全面的信息传递
`explanatory`	解释复杂概念
`descriptive`	详尽的细节描绘
`critical`	判断论证的有效性与相关性
`comparative`	对比不同理论、数据与方法
`speculative`	探索假设与潜在含义
`reflective`	结合研究过程的个人见解
`narrative`	故事化呈现
`humorous`	轻松有趣的风格
`optimistic`	突出积极面
`pessimistic`	聚焦局限与挑战

务必使用全小写传入--tone值，否则会触发argparse的choices校验报错。

四、进阶参数：编码、域限定与数据源

原文档未覆盖、但源码明确支持的参数同样值得掌握（见 cli.py）：

--encoding（可选，默认 utf-8）

控制输出文件编码。传参后会传入GPTResearcher并影响报告生成的编码处理。

--query_domains（可选）

以逗号分隔的域名白名单，用于将检索范围限定到指定站点。例如：

python cli.py "quantum computing trends" --report_type research_report --query_domains "arxiv.org,nature.com"

该参数在main()中被拆分为列表并传给GPTResearcher(query_domains=...)（见 cli.py）。

--report_source（可选，默认 web）

指定信息的来源，取值对应ReportSource枚举（见 gpt_researcher/utils/enum.py）：

web：网络检索与抓取；
local：使用本地文档；
hybrid：本地与网络混合；
azure：使用 Azure Blob Storage 文档；
langchain_documents：使用 LangChain Document 对象；
langchain_vectorstore：使用 LangChain 向量库检索；
static：使用预置静态内容。

例如使用本地文档库研究：

python cli.py "Summarize our internal onboarding docs" --report_type research_report --report_source local

--no-pdf / --no-docx（可选）

跳过 PDF 或 DOCX 生成。默认情况下每次运行会同时产出 Markdown、PDF、DOCX 三种格式；若希望只生成 Markdown，可叠加使用：

python cli.py "..." --report_type research_report --no-pdf --no-docx

五、完整示例

生成气候变化的快速研究报告：

python cli.py "What are the main causes of climate change?" --report_type research_report

以分析性语气生成关于 AI 就业影响的详细报告：

python cli.py "The impact of artificial intelligence on job markets" --report_type detailed_report --tone analytical

以说服性语气生成可再生能源提纲报告：

python cli.py "Renewable energy sources and their potential" --report_type outline_report --tone persuasive

组合进阶参数：限定域名 + 混合数据源 + 只出 Markdown：

python cli.py "LLM agent safety" --report_type research_report --query_domains "arxiv.org" --report_source hybrid --no-pdf --no-docx

六、输出机制与文件说明

1. 输出目录与文件命名

生成的报告默认保存在项目根目录的outputs/目录下。原文档描述文件名为"唯一 UUID"，但当前源码（cli.py）已升级为更友好的命名机制：

研究完成后，调用_generate_task_title()请求配置的 fast LLM 为报告生成一个不超过 20 字符的简短标题（与查询同语言，见 cli.py）；
_sanitize_filename()负责清理标题中不适用于文件系统的字符（过滤< > : " / \ | ? *与控制字符、合并空白、截断到 60 字符，见 cli.py）；
若文件名冲突，_resolve_unique_path()会自动追加_2、_3后缀（见 cli.py）；
如果 LLM 标题生成失败，会回退使用原始 query 作为文件名。

2. 报告的 YAML frontmatter

写入的 Markdown 文件头部会附带一段 YAML frontmatter，记录本次运行的元信息（见_build_frontmatter()，cli.py）：

--- task_id: <uuid4> title: <LLM 生成的标题> query: <原始查询> report_type: research_report report_source: web tone: objective query_domains: # 仅当指定 --query_domains 时出现 - arxiv.org created_at: <ISO 时间戳> sources_count: <访问过的来源数量> total_cost_usd: <累计 API 成本> ---

其中sources_count来自researcher.visited_urls，total_cost_usd来自researcher.get_costs()，方便对每次研究进行成本与来源追溯。

3. PDF 与 DOCX 的生成

默认情况下，CLI 会基于同一文件名 stem 依次生成 PDF 与 DOCX（见 cli.py）：

PDF：经由 backend/utils.py 的write_md_to_pdf()，使用md2pdf并结合 backend/styles/pdf_styles.css 样式渲染，内部还会把/outputs/...图片链接转换为绝对路径以兼容 weasyprint；
DOCX：经由write_md_to_word()（backend/utils.py），先将 Markdown 转为 HTML（使用mistune），再借助htmldocx写入 Word 文档。

相关测试用例可参见 tests/backend/test_write_md_to_pdf_filename.py，其中验证了空文件名不会写出outputs/.pdf之类的脏文件。

七、两种报告类型的内部差异

在main()中，detailed_report走的是独立分支（见 cli.py），其他类型统一走GPTResearcher主流程（cli.py）：

普通类型：创建GPTResearcher实例 →conduct_research()完成检索、抓取与上下文构建 →write_report()生成最终报告；
detailed_report：交给DetailedReport.run()编排（见 backend/report_type/detailed_report/detailed_report.py），内部会先做初始研究，再拆解出多个子主题（subtopic），为每个子主题启动独立的GPTResearcher实例生成子报告，最后拼接引言、目录、正文与结论，形成篇幅更长的深度报告——这正是它耗时约 5 分钟的原因。

八、注意事项与常见问题

执行时长不固定：取决于查询复杂度、报告类型、retriever 与 LLM 的响应速度；deep/detailed_report会明显更慢。
API 凭证必须齐全：确保.env中的 LLM Key 与 retriever Key 正确配置，否则研究无法完成。
tone 必须全小写：--tone的值来自固定 choices 列表，大小写敏感。
输出目录会自动创建：即使outputs/不存在，main()也会通过mkdir(parents=True, exist_ok=True)自动建立（见 cli.py）。
PDF 生成依赖本地渲染库：若机器缺少 weasyprint 所需原生库，PDF 生成会失败并打印警告，但 Markdown 与 DOCX 不受影响（异常已被捕获，见 cli.py）。

九、参考资源

CLI 入口实现：cli.py
报告类型 / 数据源 / 语气枚举：gpt_researcher/utils/enum.py
核心 Agent 类：gpt_researcher/agent.py
详细报告编排器：backend/report_type/detailed_report/detailed_report.py
文件导出工具：backend/utils.py
默认配置项：gpt_researcher/config/variables/default.py
环境变量模板：.env.example
相关测试：tests/backend/test_write_md_to_pdf_filename.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），仅供参考