agentic_huge_data_base / wiki
页面 Dify · 4.3 召回策略与元数据筛选·DeepWiki 中文全文译文
DeepWiki 中文译文 / Dify / 4.3

4.3 · 召回策略与元数据筛选（Retrieval Strategies and Metadata Filtering）

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

项目Dify 章节4.3 状态全文译文 模块检索、召回与索引、系统架构、模型调用与提供方适配、图谱与关系
项目要点页2.5 参考项目 项目章节目录Dify DeepWiki 原始章节Retrieval Strategies and Metadata Filtering 上一章4.2 下一章4.4
源码线索
  • 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/data_post_processor/data_post_processor.py
  • api/core/rag/datasource/retrieval_service.py
  • api/core/rag/embedding/retrieval.py
  • api/core/rag/extractor/pdf_extractor.py
  • api/core/rag/extractor/word_extractor.py
模块标签
  • 检索、召回与索引
  • 系统架构
  • 模型调用与提供方适配
  • 图谱与关系
  • 文档对象与元数据

章节正文

召回策略与元数据筛选

原始 DeepWiki 页面https://deepwiki.com/langgenius/dify/4.3-retrieval-strategies-and-metadata-filtering

检索策略与元数据过滤

相关源文件

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

  • 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/data_post_processor/data_post_processor.py
  • api/core/rag/datasource/retrieval_service.py
  • api/core/rag/embedding/retrieval.py
  • api/core/rag/extractor/pdf_extractor.py
  • api/core/rag/extractor/word_extractor.py
  • api/core/rag/rerank/entity/weight.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/fields/dataset_fields.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/index.tsx
  • web/app/components/app/configuration/dataset-config/index.tsx
  • web/app/components/app/configuration/dataset-config/params-config/config-content.tsx
  • web/app/components/app/configuration/dataset-config/params-config/index.tsx
  • web/app/components/app/configuration/debug/debug-with-multiple-model/text-generation-item.tsx
  • web/app/components/app/configuration/debug/index.tsx
  • web/app/components/app/configuration/hooks/use-advanced-prompt-config.ts
  • web/app/components/app/configuration/images/prompt.svg
  • web/app/components/app/configuration/index.tsx
  • web/app/components/base/agent-log-modal/detail.tsx
  • web/app/components/base/agent-log-modal/index.tsx
  • web/app/components/base/message-log-modal/__tests__/index.spec.tsx
  • web/app/components/base/message-log-modal/index.tsx
  • web/app/components/base/prompt-log-modal/index.tsx
  • web/app/components/base/radio-card/simple/index.tsx
  • web/app/components/base/radio-card/simple/style.module.css
  • web/app/components/datasets/common/retrieval-param-config/index.tsx
  • web/app/components/workflow/nodes/knowledge-retrieval/components/retrieval-config.tsx
  • web/app/components/workflow/nodes/knowledge-retrieval/default.ts
  • web/app/components/workflow/nodes/knowledge-retrieval/panel.tsx
  • web/app/components/workflow/nodes/knowledge-retrieval/types.ts
  • web/app/components/workflow/nodes/knowledge-retrieval/use-config.ts
  • web/app/components/workflow/nodes/knowledge-retrieval/utils.ts
  • web/app/components/workflow/nodes/tool/panel.tsx
  • web/app/components/workflow/workflow-preview/components/nodes/base.tsx
  • web/context/debug-configuration.ts
  • web/models/debug.ts

目的与范围

本文档详细介绍了 Dify 的检索增强生成（RAG）系统中检索策略与元数据过滤的技术实现。内容涵盖单数据集与多数据集检索的逻辑、搜索方法的执行（语义搜索、全文搜索、混合搜索），以及手动和基于大语言模型（LLM）的元数据过滤机制。

核心检索逻辑封装在 DatasetRetrieval 类中 api/core/rag/retrieval/dataset_retrieval.py:102，而针对数据源执行具体搜索方法的逻辑则由 RetrievalService 处理 api/core/rag/datasource/retrieval_service.py:93。

检索策略架构

Dify 支持两种主要的查询知识库策略，定义在 DatasetRetrieveConfigEntity.RetrieveStrategy 中 api/core/app/app_config/entities.py:15-20。

1. 单数据集检索（N 对 1 路由）

在此模式下，大语言模型（LLM）充当路由器，在执行搜索之前从可用选项列表中选择最相关的数据集。

Dify · 1. 单数据集检索（N 对 1 路由） · 图 1
Dify · 1. 单数据集检索（N 对 1 路由） · 图 1

图：单数据集路由流程

  • 路由机制：系统将可用数据集转换为"工具"，并使用其描述信息 api/core/rag/retrieval/dataset_retrieval.py:607-616。
  • 模型选择：如果模型支持 ModelFeature.TOOL_CALL，则使用 FunctionCallMultiDatasetRouter api/core/rag/retrieval/dataset_retrieval.py:633。否则，会回退到使用 ReactMultiDatasetRouter 的 ReAct 提示策略 api/core/rag/retrieval/dataset_retrieval.py:648。
2. 多数据集检索（N 对 N 并行）

此策略会并行地在所有选中的数据集中执行搜索，并汇总结果。

  • 并行执行：使用 ThreadPoolExecutor，其工作线程数量由配置中的 RETRIEVAL_SERVICE_EXECUTORS 定义 api/core/rag/datasource/retrieval_service.py:119。
  • 聚合：所有线程的结果会被收集到一个共享列表中，然后在 DatasetRetrieval.multiple_retrieve 中进行去重和重排序 api/core/rag/retrieval/dataset_retrieval.py:826-856。

来源： api/core/rag/retrieval/dataset_retrieval.py:158-245, api/core/rag/datasource/retrieval_service.py:118-160, api/core/app/app_config/entities.py:15-21

搜索方法及执行

Dify 通过 RetrievalMethod 枚举实现检索 api/core/rag/retrieval/retrieval_methods.py:1。

方法代码实体实现细节
SEMANTIC_SEARCHVector.search_by_vector()使用嵌入向量进行向量相似度搜索 api/core/rag/datasource/vdb/vector_factory.py:17。
FULL_TEXT_SEARCHVector.search_by_full_text()使用数据库原生的全文索引进行关键词匹配。
HYBRID_SEARCHRetrievalService._retrieve()同时执行语义搜索和全文搜索，然后融合结果 api/core/rag/datasource/retrieval_service.py:246。
KEYWORD_SEARCHJiebaKeywordTableHandler基于 BM25 的关键词搜索（主要用于经济版索引）api/core/rag/datasource/keyword/jieba/jieba_keyword_table_handler.py:1。
混合搜索与重排序流程
Dify · 混合搜索与重排序流程 · 图 2
Dify · 混合搜索与重排序流程 · 图 2

图：混合搜索到代码实体的映射

  • 重排序：如果启用了重排序模型，Dify 会使用 DataPostProcessor 对文档重新打分 api/core/rag/data_post_processor/data_post_processor.py:35。
  • 去重：系统会确保如果同一片段通过多种方法找到，只保留得分最高的实例 api/core/rag/datasource/retrieval_service.py:163-170。

来源： api/core/rag/datasource/retrieval_service.py:93-172, api/core/rag/data_post_processor/data_post_processor.py:35-100, api/core/rag/retrieval/retrieval_methods.py:1

元数据过滤

元数据过滤通过将约束条件应用于文档属性（例如标签、类别、时间戳）来缩小搜索范围。

过滤模式

Dify 支持三种过滤模式 api/core/rag/retrieval/dataset_retrieval.py:131：

  1. 禁用：不应用任何过滤。
  2. 手动：用户提供显式的 MetadataFilteringCondition 对象 api/core/app/app_config/entities.py:18。
  3. 自动（基于大语言模型）：大语言模型（LLM）从用户的自然语言查询中提取过滤条件 api/core/rag/retrieval/dataset_retrieval.py:133。
基于大语言模型的条件提取

当选择"自动"模式时，系统会使用 METADATA_FILTER_SYSTEM_PROMPT api/core/rag/retrieval/dataset_retrieval.py:51 来指示大语言模型（LLM）输出一个与元数据模式匹配的 JSON 结构。

# dataset_retrieval.py 中的实现
metadata_filter_document_ids, metadata_condition = self.get_metadata_filter_condition(
    dataset_ids=available_datasets_ids,
    query=query,
    tenant_id=tenant_id,
    user_id=user_id,
    metadata_filtering_mode=metadata_filtering_mode,
    metadata_model_config=metadata_model_config,
    metadata_filtering_conditions=metadata_filtering_conditions,
    inputs=inputs,
)

api/core/rag/retrieval/dataset_retrieval.py:147-156

在工作流节点中的实现

KnowledgeRetrievalNode 在工作流执行期间负责解析这些条件 api/core/workflow/nodes/knowledge_retrieval/knowledge_retrieval_node.py:93。它会将变量引用解析为字面量值，然后再传递给 DatasetRetrieval 引擎 api/core/workflow/nodes/knowledge_retrieval/knowledge_retrieval_node.py:183-200。

来源： api/core/rag/retrieval/dataset_retrieval.py:129-156, api/core/workflow/nodes/knowledge_retrieval/knowledge_retrieval_node.py:183-210, api/core/app/app_config/entities.py:18

命中测试服务

HitTestingService 允许开发者通过 Dify 控制台验证检索配置，而无需运行完整的应用程序 api/services/hit_testing_service.py:46。

  • 检索验证：它直接调用 RetrievalService.retrieve() api/services/hit_testing_service.py:141。
  • 日志记录：它会记录检索性能，并将查询保存到 DatasetQuery 模型中用于分析 api/services/hit_testing_service.py:171-180。
  • 外部知识库：它支持通过 ExternalDatasetService.fetch_external_knowledge_retrieval() 测试外部知识库提供商 api/services/hit_testing_service.py:38。

来源： api/services/hit_testing_service.py:46-182, api/core/rag/datasource/retrieval_service.py:175-196

技术数据流：从查询到结果

Dify · 技术数据流：从查询到结果 · 图 3
Dify · 技术数据流：从查询到结果 · 图 3

图：检索执行序列

来源： api/core/rag/retrieval/dataset_retrieval.py:119-245, api/core/rag/datasource/retrieval_service.py:93-172, api/core/workflow/nodes/knowledge_retrieval/knowledge_retrieval_node.py:93-131