5.5 · 知识召回节点（Knowledge Retrieval Node）

应用编排与外部知识接入 · 本章是 Dify DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目Dify 章节5.5 状态全文译文模块系统架构、检索、召回与索引、界面与交互、配置治理

项目要点页2.5 参考项目项目章节目录Dify DeepWiki 原始章节Knowledge Retrieval Node 上一章5.4 下一章5.6

源码线索

api/controllers/console/datasets/hit_testing_base.py
api/controllers/service_api/dataset/hit_testing.py
api/core/callback_handler/index_tool_callback_handler.py
api/core/helper/moderation.py
api/core/helper/ssrf_proxy.py
api/core/rag/datasource/retrieval_service.py
api/core/rag/extractor/pdf_extractor.py
api/core/rag/extractor/word_extractor.py
api/core/rag/retrieval/dataset_retrieval.py
api/core/tools/utils/dataset_retriever/dataset_multi_retriever_tool.py

模块标签

系统架构
检索、召回与索引
界面与交互
配置治理
图谱与关系

中文译文

知识召回节点（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/langgenius/dify/5.5-knowledge-retrieval-node

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

翻译模型：deepseek-chat

原文字符数：14472

项目：Dify (dify)

---

知识检索节点

节点概览与架构

KnowledgeRetrievalNode 通过查询已配置的数据集并返回排序后的文档片段来执行 RAG 检索。它实现了 LLMUsageTrackingMixin，用于在单检索模式使用路由模型或启用自动元数据过滤时跟踪大语言模型（LLM）的用量。

节点特性

属性	值
节点类型	`BuiltinNodeTypes.KNOWLEDGE_RETRIEVAL`
节点类	`KnowledgeRetrievalNode`，位于 `api/core/workflow/nodes/knowledge_retrieval/knowledge_retrieval_node.py:64-64`
执行类型	顺序执行（非分支）
输入变量	查询文本（字符串），附件（文件数组）
输出类型	包含 `Source` 对象的 `ArrayObjectSegment`
混入类	`LLMUsageTrackingMixin`，用于跟踪路由/元数据模型的用量

核心组件与代码实体

graph TB
    KRNode["KnowledgeRetrievalNode<br/>(knowledge_retrieval_node.py)"]
    KRNode --> NodeData["KnowledgeRetrievalNodeData<br/>(entities.py)"]
    KRNode --> DRImpl["DatasetRetrieval<br/>(dataset_retrieval.py)"]

    DRImpl --> RSvc["RetrievalService<br/>(retrieval_service.py)"]
    DRImpl --> Router["多数据集路由器<br/>(multi_dataset_react_route.py)"]

    RSvc --> VectorFactory["向量<br/>(vector_factory.py)"]
    RSvc --> KeywordFactory["关键词<br/>(keyword_factory.py)"]
    RSvc --> PostProc["DataPostProcessor<br/>(data_post_processor.py)"]

    DRImpl --> ExtSvc["ExternalDatasetService<br/>(external_knowledge_service.py)"]

来源： api/core/workflow/nodes/knowledge_retrieval/knowledge_retrieval_node.py:64-88，api/core/rag/retrieval/dataset_retrieval.py:102-118，api/core/rag/datasource/retrieval_service.py:93-108

---

节点配置模型

KnowledgeRetrievalNodeData 实体定义了工作流引擎用于实例化节点的配置模式。

graph TB
    NodeData["KnowledgeRetrievalNodeData"]
    NodeData --> Inputs["输入选择器"]
    NodeData --> Retrieval["检索配置"]
    NodeData --> Metadata["元数据过滤"]

    Inputs --> QuerySel["query_variable_selector: list[str]"]
    Inputs --> AttachSel["query_attachment_selector: list[str]"]

    Retrieval --> DatasetIDs["dataset_ids: list[str]"]
    Retrieval --> Mode["retrieval_mode: RetrieveStrategy"]

    Metadata --> FilterMode["metadata_filtering_mode: str<br/>disabled/manual/automatic"]
    Metadata --> FilterCond["metadata_filtering_conditions<br/>(MetadataFilteringCondition)"]
    Metadata --> MetaModelCfg["metadata_model_config<br/>(ModelConfig)"]

来源： api/core/workflow/nodes/knowledge_retrieval/entities.py:34-38，api/core/workflow/nodes/knowledge_retrieval/knowledge_retrieval_node.py:34-38

---

检索策略

该节点通过 retrieval_mode 属性支持两种检索模式，该属性映射到 DatasetRetrieveConfigEntity.RetrieveStrategy。

单检索模式（基于路由）

在 SINGLE 模式下，大语言模型（LLM）路由器会在执行前选择最相关的数据集。根据所选模型的能力，会使用 FunctionCallMultiDatasetRouter 或 ReactMultiDatasetRouter。

执行流程：

KnowledgeRetrievalNode 调用 DatasetRetrieval.knowledge_retrieval()，策略为 SINGLE api/core/workflow/nodes/knowledge_retrieval/knowledge_retrieval_node.py:182-194。
路由器在 DatasetRetrieval._get_available_datasets 中基于数据集描述构建工具 api/core/rag/retrieval/dataset_retrieval.py:121-121。
大语言模型（LLM）通过 FunctionCallMultiDatasetRouter 或 ReactMultiDatasetRouter 选择一个 dataset_id api/core/rag/retrieval/dataset_retrieval.py:45-46。
针对该特定数据集调用 RetrievalService.retrieve() api/core/rag/datasource/retrieval_service.py:96-108。

多检索模式（并行）

在 MULTIPLE 模式下，节点使用线程池并行查询所有选定的数据集。

sequenceDiagram
    participant Node as KnowledgeRetrievalNode
    participant DR as DatasetRetrieval
    participant RS as RetrievalService
    participant TP as ThreadPoolExecutor

    Node->>DR: knowledge_retrieval(MULTIPLE)
    DR->>RS: retrieve()
    RS->>TP: submit(_retrieve 任务)
    loop 并行任务
        TP->>RS: _retrieve(dataset_n, query)
    end
    RS-->>DR: all_documents[]
    DR->>DR: 去重与后处理
    DR-->>Node: list[Source]

来源： api/core/rag/retrieval/dataset_retrieval.py:119-157，api/core/rag/datasource/retrieval_service.py:119-167

---

元数据过滤

元数据过滤允许工作流基于文档属性限制搜索范围。

过滤模式

禁用：不应用任何过滤。
手动：使用节点配置中提供的 metadata_filtering_conditions。变量插值由 VariablePool 处理 api/core/workflow/nodes/knowledge_retrieval/knowledge_retrieval_node.py:183-201。
自动：使用大语言模型（LLM）从自然语言查询中提取过滤条件。它利用 METADATA_FILTER_SYSTEM_PROMPT 等提示词来生成结构化的 JSON 过滤器 api/core/rag/retrieval/dataset_retrieval.py:47-55。

来源： api/core/rag/retrieval/dataset_retrieval.py:131-156，api/core/workflow/nodes/knowledge_retrieval/knowledge_retrieval_node.py:183-201

---

节点执行与数据流

_run() 方法协调检索过程，并将输出格式化为工作流变量池所需的形式。

变量提取与校验

节点从 query_variable_selector 中提取查询字符串，从 query_attachment_selector 中提取文件附件 api/core/workflow/nodes/knowledge_retrieval/knowledge_retrieval_node.py:106-129。

内部数据流（从自然语言到代码空间）

graph LR
    UserQuery["'查找 2023 年的销售报告'"] -- "query_variable_selector" --> KRNode["KnowledgeRetrievalNode"]
    KRNode -- "KnowledgeRetrievalRequest" --> DR["DatasetRetrieval.knowledge_retrieval()"]
    DR -- "RetrievalMethod" --> RS["RetrievalService.retrieve()"]
    RS -- "Vector.search_by_vector()" --> VDB["VectorFactory 实现"]
    VDB -- "Document[]" --> RS
    RS -- "DataPostProcessor" --> DR
    DR -- "list[Source]" --> KRNode
    KRNode -- "ArrayObjectSegment" --> Out["NodeRunResult.outputs['result']"]

来源： api/core/workflow/nodes/knowledge_retrieval/knowledge_retrieval_node.py:93-132，api/core/rag/retrieval/dataset_retrieval.py:119-157，api/core/rag/datasource/retrieval_service.py:96-108

---

与大语言模型（LLM）节点的集成

KnowledgeRetrievalNode 的输出通常被 LLMNode 作为"上下文"使用。

LLMNode 中的上下文处理

当 LLMNode 引用检索节点的输出时，工作流引擎会处理包含检索到的 Source 对象的 ArrayObjectSegment 的传递。下游节点可以遍历这些 Source 对象来提取 content 字段。

命中测试与回调

在检索过程中，文档片段的命中计数会通过 DatasetIndexToolCallbackHandler.on_tool_end 进行更新，该处理器会增加 DocumentSegment 模型上的 hit_count api/core/callback_handler/index_tool_callback_handler.py:52-89。

来源： api/core/callback_handler/index_tool_callback_handler.py:52-89，api/core/rag/datasource/retrieval_service.py:29-34

---

速率限制与用量

速率限制

节点使用 _check_knowledge_rate_limit 对每个租户的检索请求实施速率限制。它会检查 RateLimitLog 和 Dataset 设置，以确保租户未超过其配额 api/core/rag/retrieval/dataset_retrieval.py:120-120。

用量跟踪

来自路由模型或元数据提取模型的用量（Token、成本）会使用 LLMUsage 实体进行跟踪，并在 NodeRunResult 元数据中返回 api/core/workflow/nodes/knowledge_retrieval/knowledge_retrieval_node.py:138-143。

来源： api/core/workflow/nodes/knowledge_retrieval/knowledge_retrieval_node.py:133-144，api/core/rag/retrieval/dataset_retrieval.py:107-118