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 入门](https://docs.dify.ai/en/api-reference/guides/get-started) 和 [聊天应用 API](https://docs.dify.ai/en/api-reference/guides/chat)。

## 在后台配置 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 中验证应用可以回答。 |