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负责检索、抓取、上下文管理与报告生成的主 AgentDetailedReportdetailed_report类型报告的高级编排器位于 backend/report_type/detailed_report/detailed_report.pywrite_md_to_pdf/write_md_to_word负责将 Markdown 报告转换为 PDF 与 DOCXReportSource/ReportType/Tone报告类型、数据源与语气风格的枚举定义位于 gpt_researcher/utils/enum.py。二、安装与环境配置1. 克隆仓库git clone https://github.com/assafelovic/gpt-researcher.git cd gpt-researcher2. 安装依赖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中还包含deepDeep 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.pyweb网络检索与抓取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组合进阶参数限定域名 混合数据源 只出 Markdownpython 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_urlstotal_cost_usd来自researcher.get_costs()方便对每次研究进行成本与来源追溯。3. PDF 与 DOCX 的生成默认情况下CLI 会基于同一文件名 stem 依次生成 PDF 与 DOCX见 cli.pyPDF经由 backend/utils.py 的write_md_to_pdf()使用md2pdf并结合 backend/styles/pdf_styles.css 样式渲染内部还会把/outputs/...图片链接转换为绝对路径以兼容 weasyprintDOCX经由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(parentsTrue, exist_okTrue)自动建立见 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），仅供参考