# Dify 自定义模型：接入 OpenAI 兼容 API

> 配置 Dify 自定义模型的凭证、API 模式与能力，区分聊天和知识库向量模型，并通过一个小工作流定位验证失败。

_发布 2026-09-29 · 更新 2026-09-29 · [KeepRouter Editorial](https://keeprouter.com/editorial-policy#editorial-team) · 5 分钟阅读_

![应用、AI Gateway 与模型供应商之间的分层责任图](https://keeprouter.com/editorial/blog/ai-gateway-guide.png)

_应用通过明确的请求边界连接模型 API。概念示意图。_

在 Dify 中使用 OpenAI-API-compatible 模型供应商，填写目标网关的基础地址、准确模型 ID 和凭证，再选择该线路真正支持的能力。勾选工具调用或结构化输出，并不会给模型增加相应功能。

如果是在现有应用里换模型，验收目标是“已发布应用确实用新模型完成指定任务”，不能停留在凭证窗口显示成功。

## 分清供应商、模型与应用

Dify 在工作区配置模型访问，[官方说明](https://docs.dify.ai/zh-hans/guides/model-configuration/readme)列出了管理员职责。应用随后选择模型；新增一个供应商，不会自动把所有工作流切过去。

选择当前版本可用的官方 OpenAI-API-compatible 插件。[插件配置定义](https://github.com/langgenius/dify-official-plugins/blob/main/models/openai_api_compatible/provider/openai_api_compatible.yaml)区分模型名、显示名称、API Key 和基础地址。记录插件版本与工作流版本，便于解释之后的行为变化。

| 配置 | 起步值 | 注意点 |
| --- | --- | --- |
| 模型名 / 端点模型名 | `free` | 用于文本连通测试 |
| API Base URL | `https://keeprouter.com/v1` | 由插件补齐具体操作路径 |
| API Key | 保存在供应商配置中的 KeepRouter Key | 不能用其他服务的 Key |
| 对话类型（Completion mode） | 对话（Chat） | 本例使用 Chat Completions |
| 能力 | 仅填写确认支持的项目 | 会影响插件发送的参数 |

按安装版本中实际出现的字段填写。“客服助手”这样的显示名不能替代发给 API 的真实模型 ID。

## 用三个节点做一个可检查的测试

建立“文本输入、LLM、输出”三个节点，暂不加入知识库、工具或长会话。输入下面的小文档：

```text
规则：试用账户可以创建两个项目，付费账户可以创建十个项目。
问题：试用账户最多创建几个项目？
返回数量，并引用支持答案的原句。
```

正确事实是两个。措辞可以不同，但不能回答成付费账户的十个，也不能凭空增加价格。先运行草稿，再发布到测试应用执行相同输入。如果两次结果不同，优先检查发布版本和模型选择。

## 知识库不是聊天模型的附属开关

知识库通常还需要向量模型，某些工作流还使用 reranker。聊天成功不能证明这两条路径可用；插件支持多种模型类型，也不意味着一个型号可以同时承担全部角色。

先保留原来的向量模型，只替换生成答案的模型。若确实需要换向量模型，应按[重建索引指南](/zh/blog/embedding-model-migration-reindex-checklist)处理，不把不同模型生成的向量混入同一索引。

再加入一个容易混淆的文档，例如另一种账户的项目限制。查看检索片段和最终回答：检索片段错误，应先修检索；片段正确但答案错误，才继续检查提示词与生成模型。

## 查看验证请求到底发了什么

[插件实现](https://github.com/langgenius/dify-official-plugins/blob/main/models/openai_api_compatible/models/llm/llm.py)包含端点与 token 参数差异处理，因此验证失败不一定代表 Key 错误。

| 错误 | 最小排查范围 |
| --- | --- |
| 认证失败 | 目标地址与凭证所属服务 |
| 模型不存在 | 真正发出的端点模型名 |
| token 参数无效 | 插件版本、参数模式和脱敏错误 |
| 不支持输出格式 | 该模型线路是否支持所选格式 |
| 本机成功、Dify 失败 | 插件运行环境的网络，而非浏览器网络 |

不要通过关闭证书验证解决连接问题。反馈问题时保留请求结构和状态码，移除密钥及私有文本。

## 按应用任务核算费用

问题改写、分类、检索总结和最终回答可能各发一次请求。一个包含三个模型节点且其中一个重试一次的示例，就有四次调用。统计真正完成的任务数，再与账单比较。

到[模型目录](/models)选择付费候选，保持相同测试问题，通过[费用计算器](/tools/api-cost-calculator)估算用量。按[快速开始](/docs/quickstart)建立测试凭证，在发布版本通过检查之前保留旧工作流。

## 常见问题

### 改供应商会自动迁移所有 Dify 应用吗？

不会。需要检查每个工作流选择的模型及其发布版本。工作区可用模型与应用实际选择是两项设置。

### 聊天模型能直接给知识库生成向量吗？

需要单独配置合适的向量模型与端点。聊天连接不能替代向量或重排配置。

### 这是 Dify 的性能实测吗？

不是。这是根据官方资料核对的配置与验证指南。需要在实际 Dify 和插件版本运行样本，才能判断性能。

## 参考的一手资料

_本文最近复核 2026-09-29_

1. [Dify model providers](https://docs.dify.ai/zh-hans/guides/model-configuration/readme)
2. [Official compatible-provider schema](https://github.com/langgenius/dify-official-plugins/blob/main/models/openai_api_compatible/provider/openai_api_compatible.yaml)
3. [Official compatible-provider implementation](https://github.com/langgenius/dify-official-plugins/blob/main/models/openai_api_compatible/models/llm/llm.py)

## 继续阅读

- [n8n 接入 OpenAI 兼容 API：配置与工作流排障](https://keeprouter.com/zh/blog/n8n-openai-compatible-api.md)
- [向量模型迁移：重建索引时如何保住检索质量](https://keeprouter.com/zh/blog/embedding-model-migration-reindex-checklist.md)
- [models](https://keeprouter.com/models.md)

## 用一条小请求试用接入配置

按步骤设置，把密钥保留在服务端，并检查返回的答案与用量。

[打开接入指南](https://keeprouter.com/docs/quickstart)

[创建 Key，测试免费模型](https://keeprouter.com/login?returnTo=%2Fconsole%2Fkeys%3Fmodel%3Dfree)

免费测试使用 free 模型；其他付费型号需要足够预付额度。

[全部文章](https://keeprouter.com/zh/blog.md) · [模型与价格](https://keeprouter.com/models.md)