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

解决步骤

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

验证方法

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

参考来源

langgenius/dify #39367

AI 工具推荐

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

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

了解 GamsGo AI

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