GPT Researcher 深度研究模式全解析递归树状探索引擎与 DeepResearchSkill 源码级剖析【免费下载链接】gpt-researcherAn autonomous agent that conducts deep research on any data using any LLM providers项目地址: https://gitcode.com/GitHub_Trending/gp/gpt-researcherGPT Researcher 的 Deep Research深度研究模式通过可配置深度与宽度的递归树状搜索把一个顶层研究问题自动拆解为多层子课题并发执行检索、提炼与追问最终汇聚为带引用的研究上下文。本文以仓库中的深度研究参考文档为骨架结合gpt_researcher/skills/deep_research.py的完整实现讲清该模式的配置参数、调用链路、递归机制与容错设计帮助你在生产环境中正确启用并调优这一能力。什么是 Deep Research 模式Deep Research 是 GPT Researcher 内置的一种高级报告类型report_typedeep其核心设计是递归的树状探索宽度Breadth每一层生成多个搜索查询从不同侧面覆盖主题深度Depth对每个分支递归下钻跟随研究线索逐层深入并发处理基于asyncio的 async/await 模式在信号量约束下并行执行多条研究路径上下文智能管理跨分支聚合、去重与裁剪防止上下文超出模型窗口进度追踪通过on_progress回调实时暴露宽度与深度两个维度的研究进度。可以把它理解为部署了一支AI 研究员小队每位研究员沿自己的研究路径深挖同时协作汇总出对主题的整体理解。调用链路从 report_typedeep 到 DeepResearchSkill入口在 GPTResearcher 初始化 处当report_type为deep即ReportType.DeepResearch.value时实例化DeepResearchSkill并挂载到self.deep_researcher# gpt_researcher/agent.py self.deep_researcher: Optional[DeepResearchSkill] None if report_type ReportType.DeepResearch.value: self.deep_researcher DeepResearchSkill(self)随后conduct_research()中会走独立分支agent.py# gpt_researcher/agent.py # Handle deep research separately if self.report_type ReportType.DeepResearch.value and self.deep_researcher: self._current_step deep_research return await self._handle_deep_research(on_progress)_handle_deep_research()会依次记录deep_research_initialize、deep_research_start、deep_research_complete三类日志事件含 breadth/depth/concurrency 参数与总成本最终调用self.deep_researcher.run(on_progress)返回聚合后的研究上下文之后由主流程的write_report()负责生成报告——DeepResearchSkill.run()本身只返回上下文、不生成报告这一点在源码注释中有明确说明。配置参数宽度、深度与并发深度研究的三大核心参数均为环境变量/配置项在 配置基类 中声明在 默认配置 中给出默认值# 环境变量方式.env 或 shell export 均可 export DEEP_RESEARCH_BREADTH4 # 每一层生成的子查询数量 export DEEP_RESEARCH_DEPTH2 # 递归下钻的层数 export DEEP_RESEARCH_CONCURRENCY4 # 同一时刻并发的查询处理任务数参数作用仓库默认值调优建议DEEP_RESEARCH_BREADTH每一层并行探索的研究路径数3DEFAULT_CONFIG调大覆盖面更广但焦点更散官方文档推荐如5时注意核心主题聚焦度DEEP_RESEARCH_DEPTH每条路径的递归搜索轮次2调大3~4可沿引用链深挖专业信息但显著增加耗时DEEP_RESEARCH_CONCURRENCY并发操作上限信号量4DEFAULT_CONFIG提升吞吐但可能触发检索 API 限流资源有限时应调小需要注意一个容易混淆的细节DeepResearchSkill.__init__通过getattr从researcher.cfg读取这三个值并带有代码级回退默认值deep_research.py# gpt_researcher/skills/deep_research.py self.breadth getattr(researcher.cfg, deep_research_breadth, 4) self.depth getattr(researcher.cfg, deep_research_depth, 2) self.concurrency_limit getattr(researcher.cfg, deep_research_concurrency, 2)由于researcher.cfg实际承载了DEFAULT_CONFIG中的DEEP_RESEARCH_*值因此实际生效的默认值是3 / 2 / 4而4 / 2 / 2只是配置缺失时的兜底回退——参考文档中出现的BREADTH4 / DEPTH2 / CONCURRENCY2正是这组回退值。此外还支持配置文件方式与 官方 deep_research 文档 一致researcher GPTResearcher( queryyour query, report_typedeep, config_pathpath/to/config.yaml # 在 YAML 中配置 deep_research_breadth 等参数 )报告长度由TOTAL_WORDS控制默认1200官方文档建议深度研究报告设为 2000~2500。DeepResearchSkill 的四大核心方法DeepResearchSkill定义于 gpt_researcher/skills/deep_research.py其状态与职责可归纳为四组方法全部使用strategic_llm_provider/strategic_llm_model策略型 LLM用于规划与推理1. generate_search_queries生成分支查询对当前主题生成num_queries个默认等于 breadth唯一搜索查询每个查询附带一个researchGoal研究目标。提示词强制模型只返回 JSON 数组schema 为[{query: ..., researchGoal: ...}]temperature 为0.4。解析入口为parse_search_queries_response()先尝试json_repair修复并反序列化失败则回退到逐行正则解析QUERY_LINE_PATTERN/GOAL_LINE_PATTERN并截断到num_queries条。2. generate_research_plan生成研究计划这是run()的第一步。它先遍历self.researcher.retrievers通过get_search_results()对原始查询做一次真实检索单个 retriever 失败仅记录 warning不中断再用当前时间作为上下文让策略 LLM 生成若干探索不同侧面与时间段的追问reasoning_effort固定为High。这些追问与占位答案组合成combined_queryInitial Query Follow-up Questions and Answers作为整棵递归树的根输入——这使研究计划由真实搜索结果驱动而非纯靠模型臆想。3. process_research_results提炼 learnings 与追问对单个查询的检索上下文做二次推理输出结构化结果{learnings: [{insight: ..., sourceUrl: https://...}], followUpQuestions: [...]}解析器parse_research_results_response()返回learnings去重后的洞察、followUpQuestions用于下一层递归的追问以及citations洞察 → 来源 URL 的映射。正则回退路径甚至能从纯文本行中提取行内 URL 作为引用LEARNING_LINE_PATTERNURL_PATTERN保证引用信息尽量不丢失。4. deep_research递归树引擎核心递归逻辑deep_research.py可拆解为六个关键机制并发信号量asyncio.Semaphore(self.concurrency_limit)限制同时执行的查询数asyncio.gather收集结果——这就是DEEP_RESEARCH_CONCURRENCY的落点子研究员复用主流程每条查询内部重新GPTResearcher(...)并调用conduct_research()完整继承tone、websocket、config_path、headers、visited_urls以及 MCP 配置mcp_configs/mcp_strategy均向嵌套 researcher 传播保证嵌套研究与顶层一致地走检索、抓取、摘要流水线宽度减半的递归收缩递归下钻时并非保持同宽度而是new_breadth max(2, breadth // 2)、new_depth depth - 1——每下钻一层分支数减半最少 2形成收敛的树而非爆炸的扇出下一层查询由目标 追问构成next_query拼接了本层的researchGoal与followUpQuestions把上一轮的研究结论作为下一轮的输入实现循线深挖上下文裁剪trim_context_to_word_limit()以MAX_CONTEXT_WORDS 25000词为上限从最近的内容开始保留、按原顺序重排防止递归累积撑爆模型上下文窗口失败隔离与空结果终止单个查询异常被try/except捕获并记录完整 traceback返回None后被过滤若某一层所有分支全部失败如 API key 失效、检索器离线源码会记录 warning 并直接返回已累积结果、停止下钻避免用空目标无限生成追问——该行为由测试 tests/skills/test_deep_research_empty_results.py 显式验证对应 issue #1579 的防护逻辑断言仅创建了 2 个顶层嵌套 researcher、没有向更深层递归。最终deep_research()返回一个字典learningslist(set(...))去重、visited_urls、citations、裁剪后的context与sources。运行入口 run()从进度到成本run(on_progressNone)是DeepResearchSkill对外的执行入口流程为记录初始成本initial_costs self.researcher.get_costs()调用generate_research_plan()生成计划并拼装combined_query以breadthself.breadth, depthself.depth启动deep_research()递归将 learnings 与 citations 组合成带[Source: url]标注的上下文条目再追加原始 context最后二次裁剪到词数上限把结果回写到self.researcher.context、visited_urls、research_sources并记录执行耗时与研究成本含deep_research_costs日志事件返回研究上下文。# DeepResearchSkill.run() 的返回值语义 # Return the context - dont generate report here as it will be done by the main agent return self.researcher.context研究树结构宽度 × 深度的直观图景参考文档给出的树状结构示例BREADTH4, DEPTH2完整保留了该模式的工作形态Query: Quantum Computing ├── Subtopic 1: Hardware (depth 1) │ ├── Subtopic 1.1: Superconducting qubits (depth 2) │ └── Subtopic 1.2: Ion traps (depth 2) ├── Subtopic 2: Algorithms (depth 1) │ ├── Subtopic 2.1: Shors algorithm (depth 2) │ └── Subtopic 2.2: Grovers algorithm (depth 2) ├── Subtopic 3: Applications (depth 1) │ └── ... └── Subtopic 4: Challenges (depth 1) └── ...在DEEP_RESEARCH_BREADTH4与DEEP_RESEARCH_DEPTH2下第一层探索 4 个子主题第二层每个分支再按减半宽度max(2, 4//2)2下钻形成约 4 8 12 条并发受控的研究路径——这正是宽度决定覆盖、深度决定纵深的量化含义。进度追踪ResearchProgress 与 on_progress 回调conduct_research(on_progress...)透传的回调会在每个节点被触发暴露 ResearchProgress 对象class ResearchProgress: current_depth: int # 当前深度层从 1 开始 total_depth: int # 最大探索深度 current_breadth: int # 当前已完成的路径数 total_breadth: int # 本层路径总数 current_query: str # 正在处理的查询 completed_queries: int # 已完成查询数 total_queries: int # 待处理查询总数在deep_research()内部每次开始/完成一个查询都会更新current_query、current_breadth、completed_queries并触发回调进入下一层时current_depth递增。前端WebSocket 场景可据此渲染双维度进度。实战使用完整可运行示例结合参考文档的 Usage 与 官方 Quick Start标准用法如下from gpt_researcher import GPTResearcher import asyncio async def main(): # report_typedeep 触发深度研究 researcher GPTResearcher( queryComprehensive analysis of quantum computing, report_typedeep, ) # on_progress 可选接收 ResearchProgress 进度对象 def on_progress(progress): print(f[depth {progress.current_depth}/{progress.total_depth}] f{progress.completed_queries}/{progress.total_queries} - {progress.current_query}) await researcher.conduct_research(on_progresson_progress) report await researcher.write_report() print(report) if __name__ __main__: asyncio.run(main())容错设计、限制与调优建议容错设计源自源码与测试的验证失败的查询自动跳过其余分支继续执行asyncio.gather结果过滤NoneLLM 输出解析采用json_repair → 正则逐行双通道兜底解析测试见 tests/test_deep_research_parsing.py空结果层直接终止下钻#1579避免无效递归消耗 token。限制深度研究依赖推理型 LLMSTRATEGIC_LLM承担规划、提炼与追问单次研究耗时与 API 成本显著高于标准报告每条查询都会触发一次完整的主研究流水线 一次结果提炼推理并发数过高可能触发检索服务限流。调优建议查询从宽泛开始让系统自行探索具体侧面用on_progress回调观测实际分支行为再决定参数更宽覆盖调BREADTH更专业纵深调DEPTH吞吐瓶颈调CONCURRENCY报告篇幅通过TOTAL_WORDS建议 2000~2500与DEEP_RESEARCH_*组合调节。从源码结构看Deep Research 模式的价值在于把检索—提炼—追问—再检索闭环工程化为一个可控、可观测、可容错的递归树引擎breadth/depth/concurrency三个参数分别对应树的扇出、层数与执行并行度理解其调用链agent.py → deep_research.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），仅供参考