4.4 · 召回与 Citations（Retrieval and Citations）

企业连接器与统一搜索 · 本章是 Onyx DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目Onyx 章节4.4 状态全文译文模块界面与交互、测试、发布与运维、检索、召回与索引、智能体运行时

项目要点页2.5 参考项目项目章节目录Onyx DeepWiki 原始章节Retrieval and Citations 上一章4.3 下一章4.5

源码线索

.devcontainer/github_known_hosts
.secretsignore
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/context/search/models.py

模块标签

界面与交互
测试、发布与运维
检索、召回与索引
智能体运行时
入库与解析

中文译文

召回与 Citations（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/onyx-dot-app/onyx/4.4-retrieval-and-citations

翻译时间：2026-05-27T08:44:55.593Z

翻译模型：deepseek-chat

原文字符数：15622

项目：Onyx (onyx)

---

检索与引用

目的与范围

本文档描述了 Onyx 如何从各种来源检索文档并生成引用以支持 AI 响应。内容涵盖查找相关文档的搜索管线、将文档引用映射到引用编号的引用追踪系统，以及引用从检索经过大语言模型（LLM）生成到前端展示的完整流程。

有关配置数据源和连接器的信息，请参阅连接器框架概述。有关工具构建和执行的详细信息，请参阅工具集成。有关聊天消息处理的整体流程，请参阅消息处理流程。

---

检索与引用流程概览

检索与引用系统在多个阶段运行：查询生成、文档检索、引用映射、带引用标记的大语言模型（LLM）生成以及引用数据包发送。系统在整个过程中维护一个引用映射（CitationMapping = dict[int, str]），该映射将引用编号与文档 ID 关联起来。

graph TB
    UserQuery["用户查询"]
    QueryExpansion["查询生成<br/>semantic_query_rephrase<br/>keyword_query_expansion"]
    SearchPipeline["search_pipeline<br/>Vespa/OpenSearch"]
    RRF["weighted_reciprocal_rank_fusion<br/>合并与融合片段"]
    Selection["select_sections_for_expansion<br/>LLM 选择有前景的文档"]
    Expansion["expand_section_with_context<br/>并行扩展"]
    CitationMapping["CitationMapping<br/>dict[int, SearchDoc]"]
    LLMGeneration["run_llm_step<br/>DynamicCitationProcessor"]
    CitationPackets["CitationInfo 数据包<br/>发送到前端"]

    UserQuery --> QueryExpansion
    QueryExpansion --> SearchPipeline
    SearchPipeline --> RRF
    RRF --> Selection
    Selection --> Expansion
    Expansion --> CitationMapping
    CitationMapping --> LLMGeneration
    LLMGeneration --> CitationPackets

    style UserQuery fill:none
    style SearchPipeline fill:none
    style CitationMapping fill:none
    style CitationPackets fill:none

图：端到端检索与引用流程

来源：backend/onyx/tools/tool_implementations/search/search_tool.py:4-35，backend/onyx/chat/llm_loop.py:9-72，backend/onyx/chat/llm_step.py:13-55

---

搜索与检索管线

SearchTool 架构

backend/onyx/tools/tool_implementations/search/search_tool.py:219-812 中的 SearchTool 类实现了内部文档搜索，采用多阶段管线：

查询：大语言模型（LLM）根据聊天历史生成多个查询以扩大覆盖面 backend/onyx/tools/tool_implementations/search/search_tool.py:4-8。
重组：使用加权倒数排名融合（RRF）合并结果，并合并相邻片段 backend/onyx/tools/tool_implementations/search/search_tool.py:13-17。
选择：大语言模型（LLM）选择最有前景的文档片段进行读取，以减少噪声 backend/onyx/tools/tool_implementations/search/search_tool.py:19-22。
扩展：选定的片段会扩展包含周围的上下文片段 backend/onyx/tools/tool_implementations/search/search_tool.py:24-29。
提示构建：结果以 JSON 字符串形式返回给大语言模型（LLM），同时以富对象形式提供给用户界面 backend/onyx/tools/tool_implementations/search/search_tool.py:31-34。

graph LR
    SearchToolRun["SearchTool.run()"]
    OriginalQuery["原始查询<br/>权重: 2.0"]
    SemanticQuery["semantic_query_rephrase<br/>权重: 1.75"]
    LLMQueries["LLM 查询<br/>权重: 1.5 每个"]
    KeywordQueries["keyword_query_expansion<br/>权重: 1.25 每个"]

    SearchToolRun --> OriginalQuery
    SearchToolRun --> SemanticQuery
    SearchToolRun --> LLMQueries
    SearchToolRun --> KeywordQueries

    AllQueries["所有查询"]
    OriginalQuery --> AllQueries
    SemanticQuery --> AllQueries
    LLMQueries --> AllQueries
    KeywordQueries --> AllQueries

    ParallelSearch["并行 search_pipeline 调用"]
    AllQueries --> ParallelSearch

    WRF["weighted_reciprocal_rank_fusion"]
    ParallelSearch --> WRF

    Merged["merge_overlapping_sections"]
    WRF --> Merged

    Trim["_trim_sections_by_tokens"]
    Merged --> Trim

    SelectSections["select_sections_for_expansion"]
    Trim --> SelectSections

    ParallelExpansion["并行 expand_section_with_context"]
    SelectSections --> ParallelExpansion

    FinalSections["最终 InferenceSection[]"]
    ParallelExpansion --> FinalSections

图：SearchTool 多查询管线

来源：backend/onyx/tools/tool_implementations/search/search_tool.py:432-812

查询生成与扩展

系统会生成多个查询变体以最大化召回率：

查询类型	函数	权重	用途
原始查询	用户的精确查询	2.0	直接匹配基线
语义查询	`semantic_query_rephrase`	1.75	针对混合搜索优化
大语言模型查询	LLM 生成的查询	1.5	将复杂查询分解为子查询
关键词查询	`keyword_query_expansion`	1.25	覆盖关键词密集型术语

权重在 backend/onyx/tools/tool_implementations/search/constants.py:107-110 中定义为常量：

ORIGINAL_QUERY_WEIGHT = 2.0
LLM_SEMANTIC_QUERY_WEIGHT = 1.75
LLM_NON_CUSTOM_QUERY_WEIGHT = 1.5
LLM_KEYWORD_QUERY_WEIGHT = 1.25

查询去重通过 deduplicate_queries backend/onyx/tools/tool_implementations/search/search_tool.py:135-155 执行，用于合并重复查询（不区分大小写）并累加其权重。

来源：backend/onyx/tools/tool_implementations/search/search_tool.py:432-530，backend/onyx/tools/tool_implementations/search/constants.py:107-110

文档重组与选择

并行搜索后，结果通过 weighted_reciprocal_rank_fusion backend/onyx/tools/tool_implementations/search/search_utils.py:117-119 进行合并。然后使用 merge_individual_chunks backend/onyx/context/search/pipeline.py:151-210 将相邻片段合并为 InferenceSection 对象。

系统随后使用大语言模型（LLM）通过 select_chunks_for_relevance backend/onyx/tools/tool_implementations/search/search_tool.py:83 识别最有前景的片段。对于选定的片段，expand_section_with_context backend/onyx/tools/tool_implementations/search/search_utils.py:102-104 会并行运行，从原始文档中拉取周围的片段。

来源：backend/onyx/tools/tool_implementations/search/search_tool.py:530-720，backend/onyx/context/search/pipeline.py:151-210

---

引用生成与追踪

引用处理器与映射

DynamicCitationProcessor 处理大语言模型（LLM）输出中的引用标记。它支持多种模式，包括 HYPERLINK（将 [1] 转换为链接格式）、REMOVE（去除标记）和 KEEP_MARKERS backend/onyx/chat/citation_processor.py:12-14。

核心数据结构是 CitationMapping，它将引用编号映射到文档标识符。当工具返回结果时，此映射通过 update_citation_processor_from_tool_response backend/onyx/chat/citation_utils.py:13-14 进行更新。

来源：backend/onyx/chat/citation_processor.py:12-14，backend/onyx/chat/citation_utils.py:13-14

上下文文件提取与引用

上下文文件（来自项目或角色）在集成到大语言模型（LLM）提示之前会经过提取过程。提取过程基于大语言模型（LLM）的 Token 预算执行全有或全无的适配检查。

graph TB
    UserFiles["resolve_context_user_files<br/>项目或角色文件"]
    CheckTokens["聚合 Token 计数"]
    Compare{"适配<br/>上下文预算？"}

    LoadFiles["load_in_memory_chat_files<br/>提取文本/图片"]
    BuildMetadata["构建 ContextFileMetadata"]
    InjectPrompt["注入到提示中<br/>use_as_search_filter=false"]

    SetFilter["设置 use_as_search_filter=true<br/>文件作为搜索范围"]
    SearchTool["SearchTool 使用<br/>search_persona_id 或 search_project_id"]

    UserFiles --> CheckTokens
    CheckTokens --> Compare

    Compare -->|是| LoadFiles
    LoadFiles --> BuildMetadata
    BuildMetadata --> InjectPrompt

    Compare -->|否| SetFilter
    SetFilter --> SearchTool

图：上下文文件提取决策流程

当文件注入到上下文中时，会通过 _build_context_file_citation_mapping backend/onyx/chat/llm_loop.py:185-219 分配引用编号。如果文件超出预算，SearchTool 会配置 project_id_filter 或 persona_id_filter，从向量数据库中检索这些文件 backend/onyx/tools/tool_constructor.py:55-66。

来源：backend/onyx/chat/llm_loop.py:185-219，backend/onyx/tools/tool_constructor.py:55-66

---

深度研究引用

研究代理引用处理

研究代理流程通过使用 CitationMode.KEEP_MARKERS backend/onyx/tools/fake_tools/research_agent.py:10-11 在中间报告中保留引用标记。这使得中间报告能够维护内部引用，并在最终阶段进行整合。

在生成最终报告时，使用 collapse_citations 对所有研究代理的引用进行重新编号和去重 backend/onyx/tools/fake_tools/research_agent.py:12。

graph TB
    ResearchLoop["研究代理循环"]
    ToolCalls["工具调用<br/>SearchTool, WebSearchTool"]
    ToolDocs["文档添加<br/>到 citation_mapping"]

    IntermediateReport["generate_intermediate_report"]
    KeepMarkers["CitationMode.KEEP_MARKERS"]
    ReportText["包含 [1] [2] 标记的报告"]
    CitedDocs["get_seen_citations()"]
    EmitPacket["IntermediateReportCitedDocs 数据包"]

    ResearchLoop --> ToolCalls
    ToolCalls --> ToolDocs
    ToolDocs --> IntermediateReport
    IntermediateReport --> KeepMarkers
    KeepMarkers --> ReportText
    IntermediateReport --> CitedDocs
    CitedDocs --> EmitPacket

    FinalReport["generate_final_report"]
    CollapseCitations["collapse_citations"]
    RenumberedText["最终报告<br/>包含重新编号的引用"]

    ReportText --> FinalReport
    FinalReport --> CollapseCitations
    CollapseCitations --> RenumberedText

图：深度研究引用保留与重新编号

来源：backend/onyx/tools/fake_tools/research_agent.py:87-143，backend/onyx/deep_research/dr_loop.py:100-151

---

关键函数与类参考

组件	位置	用途
`SearchTool`	`backend/onyx/tools/tool_implementations/search/search_tool.py:219`	多阶段检索管线的主入口。
`DynamicCitationProcessor`	`backend/onyx/chat/citation_processor.py:12`	处理大语言模型（LLM）流中引用标记的逻辑。
`weighted_reciprocal_rank_fusion`	`backend/onyx/tools/tool_implementations/search/search_utils.py:108-110`	合并来自不同查询策略的结果。
`merge_individual_chunks`	`backend/onyx/context/search/pipeline.py:151-210`	将相邻文档片段合并为连贯的片段。
`run_llm_loop`	`backend/onyx/chat/llm_loop.py:39`	编排多轮大语言模型（LLM）推理和工具使用。
`ChatStateContainer`	`backend/onyx/chat/chat_state.py:24`	线程安全的容器，用于存储每轮对话的文档和状态。

来源：backend/onyx/tools/tool_implementations/search/search_tool.py:1-1005，backend/onyx/chat/llm_loop.py:1-1204，backend/onyx/context/search/pipeline.py:151-210