大模型RAG应用开发：Dify与RAGFlow集成的“鸡同鸭讲“问题及完美解决方案

本文详细记录了Dify与RAGFlow集成时遇到的API数据结构不匹配问题。Dify期望的"records"格式与RAGFlow返回的"data.chunks"格式完全不同，导致集成失败。作者通过分析对比两种API响应格式差异，最终采用Dify的自定义工具功能，通过OpenAPI规范定义RAGFlow API，并在工作流中添加代码节点实现数据格式转换，成功构建了稳健的RAG管道。文章强调了不要盲信

IT猫仔

1117人浏览 · 2025-10-14 14:00:55

IT猫仔 · 2025-10-14 14:00:55 发布

前排提示，文末有大模型AGI-CSDN独家资料包哦！

拖更快一个月，到这篇文章发出来时，这套方案也已经被优化过很多次了，但是整体的框架还是围绕本文的方案进行。我要说的就是当前 LLM（大语言模型）应用开发领域的两大明星开源项目：
Dify 和 RAGFlow。

Dify，是一个强大而优雅的 LLM 应用开发平台，它让我们可以像搭积木一样，快速构建出各种智能应用。

RAGFlow，则是一个专业的 RAG（检索增强生成）引擎，它能将我们海量的私有文档，转化为可供大模型检索的“外部大脑”。

将这两者结合，理论上，我们就能轻松构建出一个能基于公司内部知识库进行问答的智能助手。这听起来简直是天作之合！

然而，当我兴致勃勃地按照 Dify 官方文档和一些所谓的博主、网红的分享，使用其“外部知识库”功能去对接 RAGFlow 时却让我异常失望：无论我在 Dify 的测试界面输入什么问题，它永远返回“无检索结果”。

踩坑实录： 最让人抓狂的是，我用 Postman 等工具直接调用 RAGFlow 的 API，却能正常返回数据！网络是通的，API 密钥是正确的，RAGFlow 本身也在健康运行。但 Dify 就是“看不见”这些数据。

我就像一个对着能正常工作的电视机，却怎么也按不出画面的遥控器一样，陷入了深深的自我怀疑。

经过一番抽丝剥茧的排查，我终于揭开了这场“沉默的失败”背后的真相。今天，我就把这次完整的排查和解决方案，分享给大家。

第一幕：解构“沉默的失败” —— 两种语言的“鸡同鸭讲”

问题的根源，并非简单的配置错误，而是两个系统在核心设计上的一次“鸡同鸭讲”。

在系统集成的世界里，最可怕的不是“连接失败”的明确错误，而是这种“连接成功但无法理解对方”的“沉默失败”。它会极大地浪费你的排查时间。

核心症结：API 契约的根本性失配

问题的本质，在于 Dify 的“外部知识库”功能所期望的 API 响应数据结构，与 RAGFlow 检索 API 实际返回的数据结构，完全不匹配。

Dify 的期望（它想听的话）：
Dify 的文档明确规定，它期望第三方知识库返回一个包含名为 records 的顶级 JSON 数组。数组里的每个对象，都必须有 content, title, score 等字段。
```
{"records":[{"content":"...","title":"...","score":0.9}]}
```
RAGFlow 的现实（它实际说的话）：
而 RAGFlow 的检索 API (/api/v1/retrieval)，返回的数据，知识片段被嵌套在 data 对象下的 chunks 数组里，并且字段名也不同（如 document_keyword, similarity）。
```
{"code":0,"data":{"chunks":[{"content":"...","document_keyword":"...","similarity":0.9}]}}
```

一图胜千言，让我们看看这个“鸿沟”有多大：

特性 Dify 期望的“语言” RAGFlow 实际说的“语言” 状态

数据根节点 records (顶级数组) data (顶级对象) 不兼容

数据列表路径 records data.chunks 不兼容

标题字段 title document_keyword 不兼容

得分字段 score similarity 不兼容

特性	Dify 期望的“语言”	RAGFlow 实际说的“语言”	状态
数据根节点	`records` (顶级数组)	`data` (顶级对象)	不兼容
数据列表路径	`records`	`data.chunks`	不兼容
标题字段	`title`	`document_keyword`	不兼容
得分字段	`score`	`similarity`	不兼容

现在，真相大白了。Dify 就像一个只会说“英语”（期望 records）的接收者，而 RAGFlow 一直在用“中文”（返回 data.chunks）向它热情地发送数据。Dify 虽然收到了信号（HTTP 200），但完全听不懂内容，于是只能无奈地告诉你：“我什么也没听到。”

要点澄清： Dify 为用户提供的最直观、最便捷的集成路径（即“外部知识库”功能），恰恰是通往失败的陷阱。

第二幕：抉择的岔路口 —— 如何为它们搭建一座“翻译桥”？

既然直接对话行不通，我们就必须寻找替代方案。幸运的是，Dify 的真正强大之处，在于其灵活的工作流引擎。我们有几种不同的“建桥”思路：

方法 A：部署一个外部“翻译官”（适配器层）

思路： 在 Dify 和 RAGFlow 之间，部署一个轻量级的中间服务（比如用 Flask 或 FastAPI 写个简单的 Web 应用）。这个服务接收 Dify 的请求，调用 RAGFlow，然后将 RAGFlow 的返回结果“翻译”成 Dify 期望的 records 格式。
优点： 对 Dify 工作流侵入最小。
缺点： 增加了系统复杂度和运维成本，还引入了额外的网络延迟。对于我们 SRE 来说，这通常是“下下策”。

方法 B：利用 Dify 内置的“万能工具箱”（自定义工具）

思路： 完全绕开“外部知识库”功能，使用 Dify 的**自定义工具（Custom Tool）**能力。我们只需要为 RAGFlow 的 API 编写一个 OpenAPI 规范（一个 YAML 文件），Dify 就能自动将其识别为一个可以在工作流中使用的“工具节点”。
优点： 无需外部中间件，所有逻辑都在 Dify 内部完成，透明可控。
缺点： 检索逻辑成为工作流的一部分，可能会让画布看起来复杂一些。

方法 C/D：更简单的“插件”或更底层的“HTTP 请求节点”

插件： Dify 市场里有社区贡献的 RAGFlow 插件，开箱即用，但逻辑是“黑盒”，且依赖第三方维护。
HTTP 请求节点： 这是最原始的方式，需要手动配置所有请求细节，过于繁琐。

我的思考：

方法 A（适配器）引入了新的故障点和运维负担，不符合我们 SRE 追求简洁可靠的原则。

方法 C（插件）虽然简单，但作为一名资深工程师，我无法接受将核心流程交给一个不受我控制的“黑盒”。

方法 D（HTTP 节点）过于“手动挡”，效率低下。

因此，方法 B（自定义工具）成为了我的最终选择。 它在灵活性、可控性和开发体验之间取得了最佳平衡。它充分利用了 Dify 最强大的工作流引擎，来弥补其特定功能的不足。

第三幕：实战蓝图 —— 用“自定义工具”构建稳健的 RAG 管道

下面，就是我为大家整理的、可直接抄作业的详细实施步骤。

第一章：编写 OpenAPI“说明书”

首先，我们需要为 RAGFlow 的检索 API 编写一份“说明书”（OpenAPI 3.0 规范），告诉 Dify 这个工具该怎么用。

创建一个名为 ragflow-tool.yaml 的文件，内容如下：


openapi: 3.0.0

info:

title: RAGFlow Retrieval API Tool

version: 1.0.0

# ... (此处省略了详细的YAML内容，实际使用时请参考原文) ...

# 关键是定义了 /api/v1/retrieval 的POST请求、参数和响应结构

# ...

components:

securitySchemes:

bearerAuth:

type: http

scheme: bearer

注意： 记得将 YAML 文件中的 servers.url 修改为你自己 RAGFlow 实例的地址。

第二章：在 Dify 中“注册”新工具

登录 Dify，进入“工具” -> “自定义工具”，点击“创建”。
选择“从 OpenAPI 规范导入”，将上面的 YAML 内容粘贴进去。
在“认证”部分，设置好 API Key 认证，头部名称为 Authorization。
保存后，为这个新工具配置凭据，填入 Bearer {你的RAGFlow_API密钥}。

第三章：在工作流中“编排”你的 RAG 管道

这是最激动人心的部分，我们将在 Dify 的工作流画布上，像搭积木一样构建我们的应用。

开始节点： 定义一个 user_query 变量，接收用户输入。
RAGFlow 工具节点： 拖入我们刚创建的自定义工具。将 user_query 连接到工具的 question 输入。

代码节点（关键的“翻译官”）：

# 代码节点中的Python代码 (简化版)defmain(ragflow_output:dict)->dict:    context =""if ragflow_output['code']==0and'chunks'in ragflow_output.get('data',{}):for chunk in ragflow_output['data']['chunks']:            context +=f"--- 来源: {chunk['document_keyword']} ---\n{chunk['content']}\n\n"else:        context ="知识库中未找到相关信息。"return{'context': context}

在 RAGFlow 工具节点之后，添加一个“代码”节点。
将 RAGFlow 节点的输出，连接到代码节点的输入（例如，命名为 ragflow_output）。
在代码节点中，用 Python 编写一个简单的解析函数，将 ragflow_output['data']['chunks'] 里的内容，格式化成一段清晰、可读的上下文文本。

LLM 节点：

请根据以下背景信息回答问题。背景信息:{{#context#}}问题:{{#user_query#}}

在代码节点之后，添加一个“LLM”节点。
在 Prompt 模板中，引用代码节点输出的 context 变量。

结束节点： 将 LLM 节点的输出连接到结束节点。

至此，一个完整、稳健、能够自我“翻译”的 RAG 管道就构建完成了！

终章：从脆弱连接到弹性管道

回望这次排查，我想与大家分享几点我的思考：

不要盲信“官方或某些博主的推荐”： 尤其是在两个快速迭代的开源项目之间，文档可能滞后，或者最便捷的路径并不总是最稳健的。
拥抱平台的“核心能力”： Dify 的“外部知识库”功能或许有瑕疵，但它的“工作流引擎”和“自定义工具”能力却异常强大。遇到问题时，多想想如何利用平台的核心优势去“绕过”而非“死磕”其短板。
可观测性是救命稻草： 在这次排查中，虽然 Dify 没有给出明确错误，但通过观察网络请求和响应，我们才能定位到 API 契约不匹配的问题。对于复杂工作流，接入 Langfuse 等可观测性工具，能让你清晰地看到每一步的数据流转，是排查此类“沉默失败”的终极武器。

通过今天的分享，我们不仅解决了一个具体的集成难题，更是将一个原本脆弱、易于失败的“硬连接”，转变为一个弹性、高效、且功能强大的“智能管道”。这不正是我们在日常工作中，不断追求的运维价值所在。

读者福利：倘若大家对大模型感兴趣，那么这套大模型学习资料一定对你有用。

针对0基础小白：