Dify external knowledge base fails to retrieve data from RagFlow v0.26.4 due to parameter mismatch

快速结论：Dify 外部知识库向 RagFlow 发送检索请求时，请求体参数结构与 RagFlow 的 /api/v1/retrieval 端点要求不一致，导致 RagFlow 静默返回空结果。优先排查的解决方法是搭建一个适配中间层来转换请求格式。

问题场景

用户在 Dify 1.14.1（Docker 自托管）中创建外部知识库，API 端点指向 RagFlow v0.26.4 的 /api/v1/retrieval 接口。在 Dify 的“命中测试”中输入查询（例如 “客户”），预期返回文档片段，但实际收到空记录：{"query":{"content":"客户"},"records":[]}。

报错原文

// 实际响应
{"query":{"content":"客户"},"records":[]}

// Dify 发出的请求体
{
  "query": "客户",
  "external_retrieval_model": {
    "top_k": 4,
    "score_threshold": 0.5,
    "score_threshold_enabled": false
  }
}

// RagFlow 期望的请求体格式
{
  "dataset_ids": ["a46801c281b511f1a23313b0b027c16e"],
  "question": "客户",
  "retrieval_setting": {
    "top_k": 3,
    "score_threshold": 0.3
  }
}

原因分析

这是设计问题（Working as Designed）。Dify 外部知识库使用固定、标准化的 API 契约，没有为不同外部服务提供适配层。Dify 实际发送的请求体包含 query、retrieval_setting、knowledge_id 等字段。而 RagFlow 的 /api/v1/retrieval 端点要求 dataset_ids（数组）和 question（字符串）——两者参数名称和结构完全不同，导致 RagFlow 静默返回空结果。

环境排查

Dify 版本：1.14.1
RagFlow 版本：v0.26.4
部署方式：Docker 自托管
Dify 外部知识库 API 端点配置：http://IP:9380/api/v1/retrieval

解决步骤

搭建一个轻量级中间件/适配服务，部署在 Dify 与 RagFlow 之间。
适配服务提供一个 /retrieval 端点，用于接收 Dify 的请求。
在适配层中，将 Dify 的请求体转换为 RagFlow 的格式：
- query 映射为 question
- knowledge_id 包装成数组，映射为 dataset_ids
- retrieval_setting 中的字段对应适配到 retrieval_setting
适配服务将转换后的请求发送到 RagFlow 的 /api/v1/retrieval 端点。
将 RagFlow 的响应转换为 Dify 期望的格式：一个包含 records 列表的 JSON 对象，每个 record 包含 content、score、title、metadata 字段。
修改 Dify 外部知识库的 API 端点，指向适配服务的地址，而非直接指向 RagFlow。

验证方法

在 Dify 的外部知识库“命中测试”中输入查询词语，观察是否返回非空的 records 列表。也可以通过浏览器开发者工具（F12）检查网络请求，确认 Dify 发出的请求体以及收到的响应。如果响应中包含来自 RagFlow 的文档片段，则表示问题已解决。

参考来源

langgenius/dify #39367

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。

Dify external knowledge base fails to retrieve data from RagFlow v0.26.4 due to parameter mismatch