agentic_huge_data_base / wiki
页面 Dify · 5.5 知识召回节点·DeepWiki 中文全文译文
DeepWiki 中文译文 / Dify / 5.5

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

应用编排与外部知识接入 · 聚焦本章的模块关系、源码依据与实现要点。

项目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

知识检索节点

相关源文件

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

  • 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
  • api/core/tools/utils/dataset_retriever/dataset_retriever_tool.py
  • api/core/workflow/nodes/knowledge_retrieval/knowledge_retrieval_node.py
  • api/services/hit_testing_service.py
  • api/tests/unit_tests/controllers/console/datasets/test_hit_testing_base.py
  • api/tests/unit_tests/controllers/service_api/dataset/test_hit_testing.py
  • api/tests/unit_tests/core/helper/test_ssrf_proxy.py
  • api/tests/unit_tests/core/rag/datasource/test_datasource_retrieval.py
  • api/tests/unit_tests/core/rag/extractor/test_word_extractor.py
  • api/tests/unit_tests/core/rag/retrieval/test_dataset_retrieval.py
  • api/tests/unit_tests/core/tools/test_signature.py
  • api/tests/unit_tests/services/test_hit_testing_service_dump_records.py
  • web/app/components/app/configuration/config-vision/param-config-content.tsx
  • web/app/components/app/configuration/dataset-config/context-var/index.tsx
  • web/app/components/billing/priority-label/index.tsx
  • web/app/components/workflow/nodes/_base/components/option-card.tsx
  • web/app/components/workflow/nodes/_base/components/variable/utils.ts
  • web/app/components/workflow/nodes/assigner/panel.tsx
  • web/app/components/workflow/nodes/http/components/key-value/key-value-edit/index.tsx
  • web/app/components/workflow/nodes/http/components/timeout/index.tsx
  • web/app/components/workflow/nodes/http/default.ts
  • web/app/components/workflow/nodes/http/panel.tsx
  • web/app/components/workflow/nodes/http/types.ts
  • web/app/components/workflow/nodes/http/use-config.ts
  • web/app/components/workflow/nodes/iteration/panel.tsx
  • web/app/components/workflow/nodes/knowledge-retrieval/use-single-run-form-params.ts
  • web/app/components/workflow/nodes/list-operator/components/filter-condition.tsx
  • web/app/components/workflow/nodes/list-operator/panel.tsx
  • web/app/components/workflow/nodes/llm/components/resolution-picker.tsx
  • web/app/components/workflow/nodes/llm/panel.tsx
  • web/app/components/workflow/nodes/llm/use-config.ts
  • web/app/components/workflow/nodes/parameter-extractor/panel.tsx
  • web/app/components/workflow/nodes/start/panel.tsx
  • web/app/components/workflow/nodes/trigger-webhook/components/generic-table.tsx
  • web/app/components/workflow/nodes/utils.ts
  • web/app/components/workflow/types.ts
  • web/utils/completion-params.ts

知识检索节点（KnowledgeRetrievalNode）通过查询知识库（数据集）并检索相关文档片段，实现了检索增强生成（RAG）工作流。检索到的内容会作为上下文传递给下游的大语言模型（LLM）节点，使模型能够基于自定义知识回答问题。

本页涵盖以下内容：

  • 节点配置与数据模型
  • 检索策略（单数据集路由 vs. 多数据集并行检索）
  • 元数据过滤机制
  • 与大语言模型（LLM）节点的集成（上下文传递）
  • 速率限制与用量跟踪

节点概览与架构

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

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

来源： 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 实体定义了工作流引擎用于实例化节点的配置模式。

Dify · 节点配置模型 · 图 2
Dify · 节点配置模型 · 图 2

来源： 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。

执行流程：

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

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

Dify · 多检索模式（并行） · 图 3
Dify · 多检索模式（并行） · 图 3

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

元数据过滤

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

过滤模式
  1. 禁用：不应用任何过滤。
  2. 手动：使用节点配置中提供的 metadata_filtering_conditions。变量插值由 VariablePool 处理 api/core/workflow/nodes/knowledge_retrieval/knowledge_retrieval_node.py:183-201。
  3. 自动：使用大语言模型（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。

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

来源： 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