Dify 添加自定义模型（接入中转站）配置指南

# Dify 添加自定义模型（接入中转站）教程

> 在 Dify 里通过「OpenAI-API-compatible」模型供应商接入中转站，添加模型后即可在应用编排中选用。  
> 全文接口地址统一为 `https://api.zaimod.com`。

---

## 一、开始之前

### 1.1 准备清单

| 项目               | 应该填什么                      | 说明                                          |
| ---------------- | -------------------------- | ------------------------------------------- |
| 模型类型             | **LLM**                    | 加对话模型选 LLM；做知识库检索才选 Text Embedding / Rerank |
| 模型名称             | 控制台模型列表里的完整 ID             | 截图中的 `o3-mini-all` 是该账号下的具体模型，**不要照抄**      |
| API Key          | `sk-` 开头的令牌                | 中转站控制台「令牌」页新建                               |
| API endpoint URL | `https://api.zaimod.com/v1` | **必须带 `/v1`**，详见 1.2                        |
| Completion mode  | 对话                         | 旧版字段，选「对话」即 chat 模式                         |

### 1.2 最关键的一处：地址必须带 `/v1`

原文正文只有一句「API地址填写 …」，给的是纯域名。但 Dify 这个字段要的是 **endpoint（基础路径）**，不是站点根地址——官方 OpenAI-API-compatible 插件里该字段名叫 `endpoint_url`，必填，占位符就是 `https://api.openai.com/v1`；插件底层用 OpenAI SDK，会在你填的地址后面自动拼 `/chat/completions`。

两种写法的实际结果我在这台机器上实测过：

| 字段填写                         | 实际请求                                        | 结果                                                   |
| ---------------------------- | ------------------------------------------- | ---------------------------------------------------- |
| `https://api.zaimod.com`      | `https://api.zaimod.com/chat/completions`    | 返回 **200 + HTML 页面**（命中前端入口），Dify 报「解析失败 / 模型列表获取失败」 |
| `https://api.zaimod.com/v1` ✅ | `https://api.zaimod.com/v1/chat/completions` | 返回 **401 Invalid token**，说明路径正确、只差鉴权                 |

所以这里写成 `https://api.zaimod.com/v1`。这一条不是我"顺手加"的：原文压根没写字段名，只给了一个域名，而字段本身要求带版本段。

**判断口诀**

- 报错里出现 **HTML / Unexpected token / 解析失败** → 八成是**少了 `/v1`**，请求打到了前台页面。
- 报错里出现 **404** 且路径是 `/v1/v1/...` → 是**多了 `/v1`**，去掉即可。
- 报错里出现 **401 Invalid token** → 路径已经对了，问题在密钥或分组。

### 1.3 请求是怎么走的

```
模型配置（地址 + Key + 模型名）
   → Dify 插件在地址后拼 /chat/completions
   → api.zaimod.com/v1/chat/completions
   → 中转站按模型名路由到上游模型
```

---

## 二、操作步骤

### 步骤 1 · 打开设置

![](/uploads/editor/20261031/img_6ae5f6396eccb9.03335295.png)

> 截图右下角显示版本 `0.15.2`。Dify 1.x 的入口位置相同，菜单项叫「设置」，只是设置页改成了全屏弹窗。

### 步骤 2 · 进入「模型供应商」并找到兼容卡片

左侧菜单点 **「模型供应商」**，在右侧卡片列表里找到 **`OpenAI-API-compatible`**（说明文字：兼容 OpenAI API 的模型供应商），点这张卡片上的 **「+ 添加模型」**。

![](/uploads/editor/20261031/img_6ae5f647033ba0.84809879.png)

> 列表里 `OpenAI`、`Anthropic`、`deepseek` 这些是官方预设供应商，只能填 Key、地址不可改，接中转站用不了。**必须走 `OpenAI-API-compatible`** 这张卡片。  
> Dify 1.x 里这张卡片默认未安装，需先到「插件 → 安装模型供应商」里装 `OpenAI-API-compatible`，装完卡片上才会出现「+ 添加模型」。

### 步骤 3 · 填写模型配置

弹窗里逐项填：

![](/uploads/editor/20261031/img_6ae5f657aff393.16341735.png)

| 字段               | 填什么                        | 注意                                           |
| ---------------- | -------------------------- | -------------------------------------------- |
| 模型类型             | 选 **LLM**                  | 单选，截图中 LLM 为选中态                              |
| 模型名称             | 控制台里的完整模型 ID               | 截图为 `o3-mini-all`，这是示例账号下的模型名，**按你自己的模型列表填** |
| API Key          | `sk-` 开头令牌                 | 粘贴后只显示首尾，属正常                                 |
| API endpoint URL | `https://api.zaimod.com/v1` | 必须带 `/v1`，见 1.2                              |
| Completion mode  | 选 **对话**                   | 旧版字段；对应 chat 模式，不要选补全                        |
| 模型上下文长度          | 按模型实际填（如 `128000`）         | 新版字段，默认常为 `4000`，不改正文字稍长就会被截断                |
| 函数调用类型           | 需要工具调用就选 **Tool Call**     | 新版字段，默认 `no_call`，不改正 Agent / 工具节点用不了        |
| 模型显示名称           | 可留空                        | 留空则界面显示模型名                                   |

填完点底部 **「保存」**。保存时 Dify 会立刻拿这组配置去请求一次模型列表做校验，校验不过会当场报错，不会"假装成功"。

### 步骤 4 · 确认模型已挂到供应商下

回到「模型供应商」页，`OpenAI-API-compatible` 卡片下方应出现 **`1 个模型`**，并列出刚加的 `模型名 / LLM / CHAT / 4K`。

![](/uploads/editor/20261031/img_6ae5f666167331.89567241.png)

> 卡片上的 `4K` 就是上下文长度。看到 `4K` 说明用的是默认值，长文档场景建议回步骤 3 改成实际值。

### 步骤 5 · 设为系统推理模型（可选但建议）

同一页面右上方点 **「系统模型设置」**（齿轮图标），在 **「系统推理模型」** 下拉里滚到最底部——自定义模型排在列表末尾、`OpenAI-API-compatible` 分组下，选中刚添加的模型。

![](/uploads/editor/20261031/img_6ae5f674e1f634.46254516.png)

> 这一步决定「未在应用里单独指定模型」时的默认模型，以及应用模板、工作流里没配模型的节点用哪个。不设也能在单个应用里手动选。

### 步骤 6 · 在应用编排页切换模型

进入（或新建）一个应用 → 编排页右上角的模型选择器 → 选刚添加的模型。选择器上显示 **`模型名 CHAT`** 即表示该应用已切过去。

![](/uploads/editor/20261031/img_6ae5f67f4726f0.28745514.png)

> 这一步原文完全没提，但很关键：**添加模型不会自动替换已有应用正在用的模型**。加完不回应用里重选，对话仍然走原来的默认模型，看起来就像"中转站没生效"。

### 步骤 7 · 预览区发一条消息验证

在右侧「调试与预览」输入 `你好` 发送，出现回复即打通。

![](/uploads/editor/20261031/img_6ae5f6898a8f96.01521141.png)

成功判据（三条都满足才算真的通了）：

1. 右上角模型选择器显示的是你添加的模型；
2. 预览区有内容返回，不是空回复或报错卡片；
3. 回复里的思考过程/正文都能正常显示（上图模型返回了 Reasoning 段 + 正文）。

---

## 三、配置速查表

| 字段               | 值                                           |
| ---------------- | ------------------------------------------- |
| 供应商              | `OpenAI-API-compatible`                     |
| 模型类型             | `LLM`                                       |
| 模型名称             | 控制台模型 ID（示例 `o3-mini-all`，按实际填）             |
| API Key          | `sk-xxxxxxxx`                               |
| API endpoint URL | `https://api.zaimod.com/v1`                  |
| Completion mode  | `对话`                                        |
| 实际请求             | `https://api.zaimod.com/v1/chat/completions` |

---

## 四、常见问题

| 现象                                       | 原因                                | 处理                                           |
| ---------------------------------------- | --------------------------------- | -------------------------------------------- |
| 保存时提示「模型列表获取失败」                          | 地址少 `/v1`、Key 错误、或模型名在该账号下不存在     | 先看 1.2 的三条口诀；地址改成 `https://api.zaimod.com/v1` |
| 报 `Failed to parse response` / 提示拿到 HTML | 地址缺 `/v1`，请求打到前端页面（返回 200 + HTML） | 补 `/v1`                                      |
| `401 Invalid token`                      | Key 错、Key 被删、或令牌分组没有该模型权限         | 重新生成令牌，确认分组包含目标模型                            |
| `404`                                    | 地址多写了一段版本（`/v1/v1/...`），或模型名拼错    | 去掉重复版本段；核对模型 ID                              |
| `400` 参数错误                               | 模型不支持所选参数（如推理类模型限制 temperature）   | 换模型或调低参数；或先在控制台用 curl 试通再回来配                 |
| 加完模型，应用里对话没变化                            | 没在编排页重新选模型                        | 回步骤 6，右上角选一次                                 |
| 能聊天，但 Agent / 工具节点不调用工具                  | 函数调用类型是默认的 `no_call`              | 编辑该模型，把函数调用类型改为 `Tool Call`                  |
| 长文档/长对话被截断                               | 上下文长度用了默认 4000                    | 编辑模型，把上下文长度改为模型实际值                           |
| 回复一直不输出（卡在转圈）                            | 部分中转/上游不支持流式                      | 关掉应用里的流式开关，或换支持 stream 的模型                   |
| 同一个模型名，不同应用表现不同                          | 一个应用内不同节点各配了模型                    | 检查每个 LLM 节点各自的模型设置                           |

---

## 五、附录 A · 原文勘误

原文（`dify添加模型`）全篇 509 字符，只有一句正文「API地址填写 + 域名」和 6 张无编号截图，没有字段名、没有步骤说明、没有成功判据。整理时修正/补齐如下：

1. **地址没带 `/v1`**：原文给的纯域名若是直接填进 `API endpoint URL`，会拼成 `/chat/completions` 打到前端页面，返回 HTML 而非 JSON。已按字段实际要求改为 `https://api.zaimod.com/v1`，并在 1.2 给出实测对比。
2. **地址被写成带星号的文本**：原文是 `***API地址填写  https://api.zaimod.com***`，在 Markdown 里 `***` 是加粗斜体标记，这行渲染会错乱，域名也可能被格式标记吞掉。
3. **没有步骤编号，也没对应到字段**：6 张图是平铺的，读者不知道每张图该点哪里、填什么。已按 7 个步骤重排，每步配图 + 图注。
4. **模型名称是示例账号的私有模型**：`o3-mini-all` 是该中转站某个具体模型/分组名，照抄到别的账号必然失败。已标注「按控制台实际 ID 填」。
5. **没说要选「LLM」类型、Completion mode 要选「对话」**：这两个都是弹窗必选项，选错（如选了 Text Embedding）后续在应用里根本选不到该模型。
6. **没标注 Dify 版本差异**：截图来自 `0.15.2`，该版本内置兼容供应商；`1.x` 需先在插件市场安装 `OpenAI-API-compatible`，且字段名从 `API endpoint URL` 变为 `API Base URL`。已分别注明。
7. **漏了「添加模型不会自动切换已有应用的模型」**：这是最容易误判成"没生效"的一步，已补为步骤 6。
8. **没有任何成功判据**：原文最后一张图只是摆在那里。已补三条可核对的判据（选择器显示、有回复、内容完整）。
9. **标题小写、无平台说明**：`dify添加模型` → 改为《Dify 添加自定义模型（接入中转站）教程》，并补充了适用范围。

---

## 六、附录 B · 地址变更对照

| 项目             | 原地址                                              | 现地址                                         |
| -------------- | ------------------------------------------------ | ------------------------------------------- |
| 原文唯一一处 API 地址  | `https://api.zaimod.com`（原文写作 `***API地址填写 …***`） | `https://api.zaimod.com/v1`                  |
| 实际请求的对话接口      | 未提及                                              | `https://api.zaimod.com/v1/chat/completions` |
| 模型列表接口（保存时校验用） | 未提及                                              | `https://api.zaimod.com/v1/models`           |

> 迁移提示：令牌需要在 `api.zaimod.com` 重新生成，原平台令牌在新域名下无效（会返回 `401 Invalid token`）。

上一篇：Cherry Studio桌面端API基础配置教程{else}上一篇：没有了下一篇：Cline 配置教程（接入中转站）{else}下一篇：没有了