4.5 · Deep Research 模式（Deep Research Mode）

Deep Research 模式

深度研究模式

相关源文件

本章引用的主要源码文件：

• backend/onyx/chat/chat_state.py
• backend/onyx/chat/chat_utils.py
• backend/onyx/chat/llm_loop.py
• backend/onyx/chat/llm_step.py
• backend/onyx/chat/models.py
• backend/onyx/chat/process_message.py
• backend/onyx/chat/prompt_utils.py
• backend/onyx/coding_agent/__init__.py
• backend/onyx/coding_agent/mock_tools.py
• backend/onyx/coding_agent/models.py
• backend/onyx/context/search/models.py
• backend/onyx/context/search/pipeline.py
• backend/onyx/db/chat.py
• backend/onyx/deep_research/dr_loop.py
• backend/onyx/prompts/chat_prompts.py
• backend/onyx/prompts/coding_agent/__init__.py
• backend/onyx/prompts/coding_agent/coding_agent.py
• backend/onyx/prompts/deep_research/__init__.py
• backend/onyx/prompts/deep_research/dr_tool_prompts.py
• backend/onyx/prompts/deep_research/orchestration_layer.py
• backend/onyx/prompts/deep_research/research_agent.py
• backend/onyx/prompts/prompt_utils.py
• backend/onyx/prompts/tool_prompts.py
• backend/onyx/server/query_and_chat/chat_backend.py
• backend/onyx/server/query_and_chat/models.py
• backend/onyx/server/query_and_chat/streaming_models.py
• backend/onyx/tools/fake_tools/coding_agent.py
• backend/onyx/tools/fake_tools/research_agent.py
• backend/onyx/tools/models.py
• backend/onyx/tools/tool_implementations/search/search_tool.py
• backend/onyx/tools/tool_runner.py
• backend/scripts/coding_agent_test.py
• backend/tests/unit/onyx/chat/test_llm_loop.py
• backend/tests/unit/onyx/chat/test_llm_step.py
• web/src/app/app/message/messageComponents/timeline/renderers/code/CodingAgentRenderer.tsx

目的与范围

深度研究模式是 Onyx 中的一种高级智能体工作流，旨在对复杂查询进行全面的多阶段研究。与标准聊天交互（参见消息处理流程）不同，深度研究模式会编排多个专门的研究智能体，跨多种来源进行迭代信息收集，并将研究结果综合成一份包含全局一致引用的结构化报告。

本文档涵盖以下内容：

• 四阶段深度研究管线（澄清、规划、执行、报告）。
• 在 run_deep_research_llm_loop 中实现的编排器和研究智能体架构 backend/onyx/deep_research/dr_loop.py:202-702。
• 用于协调的模拟工具（research_agent、think_tool、generate_plan、generate_report）。
• 跨分布式智能体的并行执行与引用协调。

架构总览

高层流程

深度研究过程在 handle_stream_message_objects 中被触发，当请求的 deep_research 标志设置为 true 时 backend/onyx/chat/process_message.py:864-888。它会将执行委托给 run_deep_research_llm_loop backend/onyx/deep_research/dr_loop.py:202-702。

深度研究管线：run_deep_research_llm_loop

来源： backend/onyx/deep_research/dr_loop.py:202-702 backend/onyx/chat/process_message.py:864-888 backend/onyx/tools/fake_tools/research_agent.py:659-702

阶段 1：澄清（可选）

目的

在开始研究之前，系统可能会提出澄清性问题，以确保理解查询范围。如果用户查询已经足够详细，或者设置了 SKIP_DEEP_RESEARCH_CLARIFICATION 环境变量，则会跳过此步骤 backend/onyx/configs/chat_configs.py:21。

实现

澄清步骤使用 CLARIFICATION_PROMPT backend/onyx/prompts/deep_research/orchestration_layer.py:8-25，该提示指示大语言模型（LLM）要么提出问题，要么调用 generate_plan 工具。如果大语言模型（LLM）输出文本而未调用工具，则该文本会成为向用户显示的澄清问题。

关键代码实体：

• CLARIFICATION_PROMPT：backend/onyx/prompts/deep_research/orchestration_layer.py:8-25
• get_clarification_tool_definitions()：返回 generate_plan 的模拟工具定义 backend/onyx/deep_research/dr_mock_tools.py:25。
• state_container.set_is_clarification(True)：在 ChatStateContainer 中将该轮标记为澄清 backend/onyx/deep_research/dr_loop.py:288。

来源： backend/onyx/deep_research/dr_loop.py:236-299 backend/onyx/prompts/deep_research/orchestration_layer.py:8-30

阶段 2：研究计划

计划生成

规划阶段会生成一个结构化的研究计划。RESEARCH_PLAN_PROMPT backend/onyx/prompts/deep_research/orchestration_layer.py:48-49 指示大语言模型（LLM）分析查询并将其分解为主要概念。

在流式传输过程中，run_llm_step_pkt_generator 会发送数据包，这些数据包会被转换为前端可用的格式：

• AgentResponseStart → DeepResearchPlanStart backend/onyx/deep_research/dr_loop.py:346-350
• AgentResponseDelta → DeepResearchPlanDelta backend/onyx/deep_research/dr_loop.py:355-359

来源： backend/onyx/deep_research/dr_loop.py:301-385 backend/onyx/prompts/deep_research/orchestration_layer.py:48-59

阶段 3：研究执行

编排器循环

编排器管理研究周期，将任务委派给研究智能体，并决定何时生成最终报告。

周期限制：

超时与周期控制： 编排器会检查条件，如果经过的时间超过 DEEP_RESEARCH_FORCE_REPORT_SECONDS（30 分钟），则强制生成报告 backend/onyx/deep_research/dr_loop.py:82-83。

编排器可用的工具： 编排器使用在 get_orchestrator_tools 中定义的模拟工具 backend/onyx/deep_research/dr_mock_tools.py:26：

• research_agent：触发 run_research_agent_calls。
• think_tool：通过 create_think_tool_token_processor 处理的显式推理步骤 backend/onyx/deep_research/utils.py:31。
• generate_report：结束循环并综合研究结果的信号。

来源： backend/onyx/deep_research/dr_loop.py:386-702 backend/onyx/deep_research/dr_mock_tools.py:26-30 backend/onyx/deep_research/utils.py:30-70

研究智能体

单个研究任务执行

每个研究智能体通过迭代调用搜索/读取工具，并使用 run_research_agent_calls 生成中间报告，对特定主题进行有针对性的研究 backend/onyx/tools/fake_tools/research_agent.py:659-702。

智能体执行逻辑：

1. 初始化：设置一个 DynamicCitationProcessor，使用 CitationMode.KEEP_MARKERS 在中间生成过程中保留引用索引 backend/onyx/tools/fake_tools/research_agent.py:11。
2. 执行循环：最多迭代 MAX_RESEARCH_CYCLES（8 次）backend/onyx/prompts/deep_research/research_agent.py:42。
3. 工具集：智能体使用 SearchTool、WebSearchTool 和 OpenURLTool backend/onyx/tools/fake_tools/research_agent.py:65-68。
4. 中间报告：使用 RESEARCH_REPORT_PROMPT 生成摘要 backend/onyx/prompts/deep_research/research_agent.py:46。

并行化： 如果进行了多次 research_agent 调用，它们会使用 run_functions_tuples_in_parallel 并行执行 backend/onyx/tools/fake_tools/research_agent.py:686-691。随后通过 collapse_citations 协调引用 backend/onyx/chat/citation_utils.py:12。

来源： backend/onyx/tools/fake_tools/research_agent.py:205-657 backend/onyx/chat/citation_utils.py:12

阶段 4：最终报告生成

报告综合

研究周期完成后，generate_final_report backend/onyx/deep_research/dr_loop.py:100-113 将所有研究结果综合成一份结构化文档。

报告构建：

• 提示：使用 FINAL_REPORT_PROMPT backend/onyx/prompts/deep_research/orchestration_layer.py:37 和 USER_FINAL_REPORT_QUERY backend/onyx/prompts/deep_research/orchestration_layer.py:50。
• 上下文：历史记录包含研究智能体生成的所有中间报告。
• 约束：最大输出 Token 数设置为 MAX_FINAL_REPORT_TOKENS（20,000）backend/onyx/deep_research/dr_loop.py:77。

来源： backend/onyx/deep_research/dr_loop.py:100-184 backend/onyx/prompts/deep_research/orchestration_layer.py:37-50

并行执行与引用

引用协调

由于研究智能体并行运行，它们的引用索引（例如 [1]、[2]）通常会重叠。Onyx 使用多阶段协调过程：

实现细节：

• collapse_citations 会遍历所有结果，构建一个全局文档映射，并替换报告文本中的 [N] 标记，确保它们指向正确的全局索引 backend/onyx/chat/citation_utils.py:12。

来源：

• backend/onyx/chat/citation_utils.py:12
• backend/onyx/tools/fake_tools/research_agent.py:694-702