ruoyi-ai/docs/dify-cloud.md

Dify 官方云服务配置

本指南适用于本地运行 RuoYi-AI Java 后端、连接 Dify 官方云服务的场景。

准备 Dify 应用

在 Dify 中创建并发布聊天应用，先在 Dify 自己的调试页面确认可以正常回答。首次接入可以使用 Chatbot（聊天助手）。在该应用的 API 访问页面创建应用 API Key。

应用 Key 对应具体的 Dify 应用；知识库 Key 不能用于聊天。Dify 官方云服务的 API 基础地址为 https://api.dify.ai/v1。参见 Dify API 入门 和 聊天应用 API。

在后台配置 Key

API Key 统一在 ruoyi-admin → 对话管理 → 模型管理 中直接填写并保存，无需配置后端环境变量。

模型管理填写示例

先确认厂商管理中的 Dify 已启用，再在模型管理中修改 Dify 模型：

字段	填写内容
模型分类	聊天（chat）
模型供应商	Dify（编码 dify）
模型名称	dify-chat
模型描述	Dify 聊天助手
请求地址	https://api.dify.ai/v1
密钥	从 Dify 应用复制的真实 API Key，如 app-...
是否显示	是

直接填写真实应用 Key，不需要 env: 或 Bearer 前缀。编辑时回显已保存的 Key，默认隐藏，点击眼睛可查看原文。输入内容原样保存，清空后保存会清除原 Key。保存后新的调用读取最新配置，无需重启后端。

请求地址填写到 /v1，不要追加 /chat-messages，也不要填写 Dify 应用的网页分享链接。模型名称是本系统的选择标识，可以取一个不重复的应用名称；实际调用哪个 Dify 应用由应用 Key 决定。

已有数据库直接在模型管理中按上述内容保存即可，无需重新导入全量 SQL。保存后在聊天页面选择该模型，发送一条简单消息验证。

适用范围

• 官方云服务使用 https://api.dify.ai/v1；自建 Dify 填写后端可以访问的服务 API 地址。
• 不同模型可以填写不同的应用 Key，分别连接对应的 Dify 应用。
• 当前适配器使用聊天消息接口，普通 Workflow 应用不能通过此模型配置调用。
• 当前请求的自定义 inputs 为空。接入的聊天应用应能在不提供额外必填输入变量的情况下运行。
• 当前聊天适配器没有实现 Dify 的 Human Input 表单交互和文件上传流程；首次验证请使用简单文本聊天应用。

常见情况

现象	检查方法
后台无法保存	检查厂商是否启用，以及模型分类、名称等必填项是否齐全。
查看已保存的密钥	编辑时默认隐藏，点击密钥框右侧的眼睛查看原文；清空后保存会清除密钥。
Dify 返回鉴权失败	在模型管理中填写当前应用的有效 API Key，检查复制时是否带入空格或 Bearer 前缀。
Dify 返回应用类型或输入参数错误	检查是否使用聊天应用，以及应用是否要求额外输入变量；先在 Dify 中验证应用可以回答。