GPT Researcher Deep Research基于递归广度与深度的开源深度研究机制实战指南【免费下载链接】gpt-researcherAn autonomous agent that conducts deep research on any data using any LLM providers项目地址: https://gitcode.com/GitHub_Trending/gp/gpt-researcher导读Deep Research 是 GPT Researcher 提供的递归式深度研究模式report_typedeep通过广度铺开 深度下钻 并发执行 上下文智能聚合的树状探索路径把单一查询拆解为多级、多路的研究分支适用于需要极致深度与广度的调研场景如技术趋势、学术综述、竞品分析。读完本文你将掌握 Deep Research 的完整工作原理、核心配置参数、进度回调协议、错误恢复机制与资源调优策略并能在自己的代码中直接接入这一能力。一、Deep Research 是什么Deep Research 是 GPT Researcher 针对 AI 社区深度研究趋势推出的开源实现。与标准研究模式一次查询、一次报告不同Deep Research 采用递归树状探索每一层生成多个搜索查询铺开广度对每个分支递归下钻挖掘深度再通过异步并发让多条研究路径同时推进最后自动聚合、综合各分支的发现。在源码层面这一能力由 gpt_researcher/skills/deep_research.py 中的DeepResearchSkill类承载通过 gpt_researcher/agent.py 在report_type为deep时自动装配进GPTResearcher实例self.deep_researcher: Optional[DeepResearchSkill] None if report_type ReportType.DeepResearch.value: self.deep_researcher DeepResearchSkill(self)而deep正是 gpt_researcher/utils/enum.py 中ReportType.DeepResearch的枚举值。五个核心设计特征广度Breadth每一层根据当前查询生成多个搜索查询覆盖主题的不同侧面深度Depth每个分支递归下钻顺着线索持续深挖、串联关联信息并发处理Concurrency基于asyncio的Semaphore控制多条研究路径同时运行见DeepResearchSkill.deep_research中的asyncio.Semaphore(self.concurrency_limit)智能上下文管理自动汇总所有分支的 learnings 与来源并通过trim_context_to_word_limit将上下文裁剪到安全词数上限MAX_CONTEXT_WORDS 25000进度跟踪以ResearchProgress数据结构对广度与深度两个维度进行实时进度上报。可以把它理解为部署了一支AI 研究员团队每个研究员沿自己的路径探索同时协作构建对主题的整体认知。二、工作流程从查询到报告的递归管线Deep Research 的执行入口在DeepResearchSkill.run()其主流程分为三个阶段1. 研究计划生成generate_research_plan先对所有配置的 retriever 做一轮初步搜索get_search_results将初始结果连同当前时间注入提示词让strategic LLM 生成若干澄清性追问随后自动以 Automatically proceeding with research 作答拼成组合查询作为递归研究的根输入。2. 递归深度研究deep_research核心递归函数其内部逻辑gpt_researcher/skills/deep_research.py为调用generate_search_queries生成breadth个带researchGoal的搜索查询在Semaphore限流下每个查询交给一个嵌套的GPTResearcher实例report_typeresearch_report独立完成conduct_research()并透传tone、websocket、config_path、headers、visited_urls以及 MCP 配置mcp_configs、mcp_strategy保证子研究与顶层配置一致对每个分支的结果调用process_research_results提取 learnings含来源 citation与 follow-up questions若depth 1则递归下钻new_breadth max(2, breadth // 2)并以上一轮研究目标 follow-up 问题构造下一层查询逐层把 learnings、visited URLs、citations、context、sources 向上汇聚全部完成后用trim_context_to_word_limit裁剪上下文返回聚合结果。3. 上下文装配与汇报run()把 learnings 与其 citation 拼成{learning} [Source: {url}]格式连同研究上下文一起写入self.researcher.context并记录研究耗时与增量成本通过log_handler的deep_research_costs事件。报告生成不在此处进行——由主GPTResearcher的write_report()基于该上下文统一完成。容错与终止机制值得注意的实现细节每个分支查询都有try/except包裹失败返回None并被过滤单条失败不影响整体若某一层所有分支全部失败如 API Key 失效、检索器离线代码会记录 warning 并停止下钻避免基于空结果无限生成 follow-up对应 issue #1579该行为由 tests/skills/test_deep_research_empty_results.py 中的test_stops_when_all_query_processors_return_none验证LLM 输出解析采用json_repair容错优先按 JSON 解析失败时回退到正则提取Query:/Research Goal:/Learning:/Question:行式格式见parse_search_queries_response等解析函数tests/test_deep_research_parsing.py 对两类格式均有覆盖。三、快速开始三行代码接入Deep Research 与标准研究共用同一 API只需把report_type设为deepfrom gpt_researcher import GPTResearcher from gpt_researcher.utils.enum import ReportType, Tone import asyncio async def main(): # Initialize researcher with deep research type researcher GPTResearcher( queryWhat are the latest developments in quantum computing?, report_typedeep, # This triggers deep research mode ) # Run research research_data await researcher.conduct_research() # Generate report report await researcher.write_report() print(report) if __name__ __main__: asyncio.run(main())注意report_typedeep等价于ReportType.DeepResearch.value即字符串deep两种写法均可。conduct_research()内部会检测该类型并转入_handle_deep_research()见 gpt_researcher/agent.py同时以deep_research_initialize/deep_research_start/deep_research_complete/cost_update等事件写入日志便于追踪整个流程。四、核心配置参数Deep Research 的行为由以下参数控制源码默认值定义在 gpt_researcher/config/variables/default.py参数环境变量源码默认值作用deep_research_breadthDEEP_RESEARCH_BREADTH3每一层的并行研究路径数即每层生成的搜索查询数量deep_research_depthDEEP_RESEARCH_DEPTH2递归探索的层数决定下钻多深deep_research_concurrencyDEEP_RESEARCH_CONCURRENCY4最大并发研究操作数asyncio.Semaphore上限total_wordsTOTAL_WORDS1200生成报告的期望总字数官方文档建议 Deep Research 场景取 2000 左右关于默认值的说明官方文档给出的默认值为 breadth4、depth2、concurrency4而当前仓库源码中default.py的默认值为 breadth3、depth2、concurrency4。两者仅 breadth 不同3 vs 4。在实际使用中DeepResearchSkill.__init__通过getattr(researcher.cfg, deep_research_breadth, 4)读取配置因此凡是在你的环境变量或配置文件中显式设置了该参数就会覆盖默认值建议以你实际部署环境中的配置为准并显式设置以确保行为可预期。配置方式一环境变量export DEEP_RESEARCH_BREADTH4 export DEEP_RESEARCH_DEPTH2 export DEEP_RESEARCH_CONCURRENCY4 export TOTAL_WORDS2500环境变量会被 gpt_researcher/config/config.py 的Config.from_env加载并根据BaseConfig的类型注解自动转换类型convert_env_value优先级高于配置文件。配置方式二配置文件YAMLdeep_research_breadth: 4 deep_research_depth: 2 deep_research_concurrency: 4 total_words: 2500researcher GPTResearcher( queryyour query, report_typedeep, config_pathpath/to/config.yaml # Configure deep research parameters here )当同时提供配置文件与环境变量时环境变量优先。config_path还会透传给所有嵌套的子GPTResearcher实例保证递归分支使用同一套配置。五、进度跟踪on_progress 回调协议Deep Research 的进度通过on_progress回调实时上报回调参数为ResearchProgress对象其字段定义在 gpt_researcher/skills/deep_research.pyclass ResearchProgress: current_depth: int # Current depth level total_depth: int # Maximum depth to explore current_breadth: int # Current number of parallel paths total_breadth: int # Maximum breadth at each level current_query: str # Currently processing query completed_queries: int # Number of completed queries total_queries: int # Total queries to process源码中的进度语义如下current_depth从 1 开始递增至total_depthtotal_breadth为该层计划执行的查询数current_breadth随查询完成逐步累加并在每层全部完成后被重置为该层实际成功的查询数progress.current_breadth len(results)total_queries在查询生成后设置为len(serp_queries)completed_queries在每条分支成功处理后 1。典型用法——在conduct_research(on_progress...)中挂载回调def on_progress(progress): print( fDepth {progress.current_depth}/{progress.total_depth} | fBreadth {progress.current_breadth}/{progress.total_breadth} | fQueries {progress.completed_queries}/{progress.total_queries} | fCurrent: {progress.current_query} ) await researcher.conduct_research(on_progresson_progress)这套进度协议既可用于终端/Web 界面的实时展示本项目前端即通过 WebSocket 消费此类进度也可用于日志埋点与故障定位。六、错误处理与健壮性设计Deep Research 被设计为对失败具有弹性失败查询自动跳过单条分支查询抛异常时被捕获并记入日志logger.error 控制台输出 traceback返回Noneasyncio.gather的结果会过滤掉None分支失败不影响整体Semaphore保护下的每条路径相互隔离一条失败不会中断其他分支全层失败自动终止当某层results为空时记录no successful query results at depth...; stopping to avoid infinite work并立即返回避免死循环与无效 API 消耗对应 issue #1579测试见 tests/skills/test_deep_research_empty_results.py进度回调辅助诊断通过实时进度数据可快速定位是哪一层、哪个查询失败。七、最佳实践与参数调优先宽后深Start Broad从一个相对泛化的查询出发让系统在后续层自动聚焦到具体细节善用进度回调Monitor Progress观察 depth/breadth 的推进节奏理解研究流是否健康按需调参Adjust Parametersbreadth 越大 → 覆盖面越广但每层查询与 API 调用越多depth 越大 → 洞察越深但耗时与成本指数级增长递归下钻时每层宽度自动减半new_breadth max(2, breadth // 2)因此顶层 breadth 直接决定总工作量资源管理Resource Managementdeep_research_concurrency要结合系统内存、检索器与 LLM 的速率限制来设置MAX_CONTEXT_WORDS 25000会自动裁剪上下文防止长链路下超长上下文拖垮下游报告生成搭配推理模型Deep Research 依赖 strategic LLMSTRATEGIC_LLM默认openai:gpt-5.4做规划与结果提炼并受REASONING_EFFORTlow/medium/high见 gpt_researcher/llm_provider/generic/base.py调节推理强度文档所述 $0.4/5 分钟的成本量级即基于o3-minihigh推理档位实际成本随你的模型选择、breadth/depth 与REASONING_EFFORT而变。八、限制与注意事项对推理模型有依赖规划与学习提炼环节需要具备强推理能力的 LLM如o3-mini一类 reasoning 模型推理档位调低可换速度、调高可换深度耗时更长相比标准研究递归多轮 多路并发通常显著拉长整体时长官方文档以约 5 分钟为量级参考实际随参数而定成本更高多个并发查询叠加多轮下钻API 调用量与 token 消耗明显上升建议用deep_research_breadth/depth控制预算并借助get_costs()与日志中的deep_research_costs事件跟踪花费系统资源占用更高并发研究路径会同时占用检索、爬取与 LLM 资源部署时需结合自身算力与限流配额评估。延伸阅读完整实现gpt_researcher/skills/deep_research.py调度与装配gpt_researcher/agent.py装配与_handle_deep_research执行/日志报告类型枚举gpt_researcher/utils/enum.py默认配置gpt_researcher/config/variables/default.py配置加载与环境变量优先级gpt_researcher/config/config.py相关测试tests/skills/test_deep_research_empty_results.py、tests/test_deep_research_parsing.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），仅供参考