Dify 配置 OpenAI 兼容 API：模型与 Base URL 设置步骤

更新于 2026-10-30 · gpt.boats

简答：Dify 接入 OpenAI 兼容 API，核心是安装或启用 OpenAI-API-compatible 模型供应商，然后填写实际模型 ID、API Key 和 API Base URL。Base URL 通常填服务商文档给出的根地址，例如以 <code>/v1</code> 结尾的地址，不要直接填完整的 <code>/chat/completions</code>。配置前先用同一地址和密钥发一次最小请求，确认模型名、认证方式和协议都能工作，再在 Dify 中保存并测试。

定义：OpenAI 兼容 API 是指使用与 OpenAI 接口结构相近的请求方式、认证方式或响应格式，让支持该协议的工具能够通过 Base URL、API Key 和模型名调用其他模型服务；兼容程度仍以具体服务商文档为准。

先看字段对照：Dify 里到底怎么填

截至 2026-10-30，Dify 官方 OpenAI-API-compatible 插件的配置字段包括模型名称、模型显示名称、API Key、API Base URL，并为 LLM 提供 Chat Completions API 与 Responses API 选项。字段名称和可选项应以当前安装的插件版本为准，官方字段定义可查看 Dify 官方插件配置文件。

字段	填写内容	判断方法
Model Type	通常选择 LLM	用于文本对话或工作流中的大语言模型节点
Model Name	服务端实际识别的模型 ID	必须与服务商模型列表或调用文档中的名称一致
Display Name	在 Dify 界面显示的名称，可自定义	只影响界面识别，不应替代实际模型 ID
API Key	兼容接口要求的密钥	不要把密钥写进公开工作流、截图或前端代码
API Base URL	接口根地址，例如 `https://api.example.com/v1`	不要填写完整的 `/chat/completions`
API Type	Chat Completions 或 Responses	按服务端明确支持的协议选择，无法确认时先选其文档示例对应的类型

最容易出错的一点：“模型名称”和“显示名称”不是一回事。假设服务商要求请求体中的模型字段为 provider-model-7b，那么 Model Name 应填写这个实际 ID；Display Name 可以写成“测试模型”，但不能只把“测试模型”填入 Model Name。

配置前先完成一次最小请求验证

不要直接在 Dify 里反复猜 Base URL。先向兼容服务发一次最小请求，可以把问题分成“服务地址或密钥有问题”和“Dify 字段填写有问题”两类。下面示例中的地址、模型名和密钥都是占位符，必须替换为你实际服务商提供的值。

验证模型列表：如果服务商实现了模型列表接口，可以先尝试：

curl -sS -H "Authorization: Bearer YOUR_API_KEY" "https://api.example.com/v1/models"

如果服务商要求其他认证头，不要强行使用 Bearer，按其 API 文档改用指定的 Header。模型列表请求成功后，记录返回的实际模型 ID。

验证 Chat Completions：

curl -sS "https://api.example.com/v1/chat/completions" -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"model":"YOUR_MODEL_ID","messages":[{"role":"user","content":"只回复：连接成功"}],"stream":false}'

成功判定不是只看 HTTP 状态码，还要确认响应是 JSON，并且包含服务商文档规定的 assistant 内容或等价输出字段。如果返回 HTML、网关错误页或空响应，先不要继续改 Dify 字段。

这里的 /v1 只是常见的兼容接口路径示例，不代表所有服务都必须使用它。Dify 官方插件示例将 API Base URL 写作类似 https://api.openai.com/v1 的根地址；实际地址仍以你接入的服务文档为准。不要把完整的 /chat/completions 追加到 Base URL，否则 Dify 可能再次拼接路径。

在 Dify 中添加 OpenAI 兼容模型

登录 Dify，进入模型供应商或模型提供商相关设置。不同 Dify 版本、部署方式和权限下，入口名称可能不同；如果搜索不到供应商，先检查插件市场或当前实例是否允许安装模型插件。
找到并安装或启用 OpenAI-API-compatible 模型插件。Dify 官方插件仓库将它定义为用于连接兼容 OpenAI API 标准的模型供应商，并列出 LLM、重排序、文本嵌入、语音转文本和文本转语音等支持类型；本文只讨论 LLM 接入。
添加自定义模型，Model Type 选择 LLM。
在 Model Name 中填写服务端实际模型 ID，例如 YOUR_MODEL_ID；不要填写模型昵称。
在 Display Name 中填写便于你在 Dify 中识别的名称。这个字段可以自定义，也可以留空，具体以当前表单要求为准。
填写 API Key。密钥只放在 Dify 的凭证字段中，不要粘贴到公开知识库、工作流文本、浏览器前端或截图。
填写 API Base URL。优先复制服务商文档中的 Base URL；如果文档给出 https://api.example.com/v1，就填写这一层，不要填写 /chat/completions。
选择 API Type。服务商明确提供 Chat Completions 示例时，选择 Chat Completions；只有在服务商确认支持 Responses 且接口路径、请求体和响应格式都匹配时，才选择 Responses。Dify 官方字段定义同时列出了这两个选项。
保存凭证并执行连接测试。如果保存成功但应用调用失败，仍要继续测试实际模型节点，因为“凭证可保存”不等于每个模型、端点或参数都具备权限。

Chat Completions 和 Responses 怎么选

这两个选项不是模型名称，而是 Dify 应向服务端发送请求时采用的 API 协议。OpenAI 兼容服务常见的是 Chat Completions，但不能仅凭“兼容 OpenAI”四个字推断一定支持 Responses。

场景	优先选择	注意事项
服务商文档示例是 `/chat/completions`	Chat Completions	确认消息格式、模型字段和流式返回格式一致
服务商明确提供 `/responses`	Responses	确认 Dify 当前插件版本和服务端都支持该协议
只知道“支持 OpenAI 兼容”，没有具体协议说明	不要猜	先查接口文档或用最小请求验证，不要把两个协议混用
工具调用、思考模式或特殊参数失败	回到严格兼容模式	先关闭扩展参数，再逐项确认服务端支持范围

Dify 官方配置中还提供严格兼容和扩展模式等选项。严格模式更适合先完成基础文本调用；如果服务端不接受额外参数，优先关闭扩展能力，再测试普通对话。

保存后如何在应用或工作流中验证

新建或打开一个 Dify 聊天应用、Chatflow 或工作流。
在模型选择器中找到刚才配置的 Display Name。
在 LLM 节点中发送短文本，例如“用一句话说明 API Key 的作用”。不要一开始就测试长上下文、图片、工具调用或复杂 JSON。
确认节点出现正常文本输出，并查看运行详情中的请求错误、响应状态和耗时。
基础文本成功后，再单独测试流式输出、工具调用、视觉、Embedding 或 Rerank。OpenAI 兼容并不代表这些能力全部兼容。

如果 Dify 的基础对话已经成功，说明 Base URL、认证和模型 ID 至少在当前调用路径下基本匹配；如果只有某一项高级能力失败，应把它当作能力或参数兼容问题排查，而不是立即更换 API Key。

常见报错：按现象分流排查

401 Unauthorized：先检查 API Key 是否复制完整、是否带了多余空格、认证 Header 是否符合服务商要求。用 curl 复现同一请求；curl 也返回 401 时，问题在凭证或认证方式，不在 Dify 模型显示名称。
403 Forbidden：常见排查方向是账户权限、模型权限、来源限制、IP 白名单或接口权限。不要通过反复重试解决权限问题，直接查看服务商控制台和文档中的权限说明。
404 Not Found：重点检查 Base URL 是否已经包含版本路径、是否误填了完整端点、服务端是否真的提供 /chat/completions 或 /responses。如果 Base URL 写成完整端点，Dify 可能产生重复路径。
400 Bad Request：检查 Model Name、API Type、消息格式和参数名。某些兼容服务不接受额外的 user、工具调用或特定 token 参数；先用最简单的文本请求验证。
模型不存在：把服务商返回的实际模型 ID 原样复制到 Model Name。Display Name 可以自定义，但不会改变服务端识别的模型 ID。
连接超时：先在部署 Dify 的服务器或容器内测试目标地址，而不是只在本地电脑测试。若本地能通、Dify 所在环境不通，重点检查容器网络、DNS、出口策略和 TLS 证书。
流式输出中断：先关闭流式或改用非流式请求确认基础调用，再检查服务端是否按兼容格式发送事件、是否在代理层被缓冲或截断。
工具调用失败：基础文本成功不代表 Function Calling 或 Agent 能力可用。根据服务商文档确认工具调用格式，并在 Dify 中不要同时开启未经验证的扩展参数。

Dify Cloud 与私有化部署的差异怎么处理

Dify Cloud 和 Docker 私有化实例的界面入口、插件可用性、网络出口和权限设置可能不同，因此不要把某一篇教程中的菜单路径当成所有版本的固定路径。通用判断顺序是：先确认当前实例能否安装 OpenAI-API-compatible 插件，再确认实例所在环境能否访问 Base URL，最后在模型供应商中保存凭证。

如果是私有化部署，curl 应尽量在 Dify 后端实际运行环境中执行；如果是云端实例，则重点确认服务商是否允许来自云端的请求，以及是否要求特定来源、区域或 IP。无法从 Dify 官方插件字段推断某个兼容服务的网络限制，相关限制应以该服务的公开文档为准。

配置前后的安全检查清单

API Key 使用最小权限或专用密钥，避免与个人开发环境共用。
不要把密钥写进 Git、前端 JavaScript、公开工作流变量、日志或截图。
示例中的 YOUR_API_KEY、YOUR_MODEL_ID、api.example.com 都是占位符，发布前必须替换或删除。
先用短文本验证，避免首次测试就消耗大量上下文或触发高成本能力。
余额、权限、未知错误和模型不存在不应自动重试；只有确认是临时限流时，才按服务商给出的等待时间和总时限重试。
记录你实际使用的 Base URL、模型 ID、API 类型和插件版本，后续排错时不要只记录 Display Name。

本文只说明通用配置方法，不代表任意 OpenAI 兼容服务都支持全部 Dify 能力。若某个字段、参数或高级功能没有公开文档支撑，应标记为未核实，并先完成最小文本请求。

结论

Dify 配置 OpenAI 兼容 API 的最短闭环是：确认服务端实际模型 ID和认证方式 → 用 curl 验证 Base URL 与最小请求 → 安装或启用 OpenAI-API-compatible 插件 → 填写 Model Name、API Key、API Base URL → 按服务端选择 Chat Completions 或 Responses → 在 LLM 节点发送短文本测试。出现 401、404 或模型不存在时，优先检查密钥、路径和实际模型 ID，不要先修改显示名称。

本文为第三方接入说明，Dify 本身的插件字段以其公开仓库和当前实例界面为准。

常见问题

Dify 的 API Base URL 要不要填写 /v1？

不能一概而论。若服务商文档给出的根地址是 https://api.example.com/v1，就填写到 /v1；如果文档给的是其他版本路径，就按文档填写。不要把完整的 /chat/completions 写进 Base URL，因为 Dify 还可能继续拼接请求路径。

Model Name 和 Display Name 有什么区别？

Model Name 是服务端识别的实际模型 ID，必须与模型列表或调用文档一致；Display Name 只是 Dify 界面中的显示名称，可以自定义。模型不存在时，优先检查 Model Name，而不是修改 Display Name。

Dify 保存 API Key 成功，但调用模型仍然失败，为什么？

保存凭证不等于当前模型、端点和高级参数都可用。先用同一个 Base URL、API Key 和模型 ID发送最小请求，再按 401、403、404、400 或超时分流排查。

Chat Completions 和 Responses 应该选哪个？

服务商文档使用 /chat/completions 时选择 Chat Completions；只有服务商明确提供并兼容 /responses 时才选择 Responses。仅写“OpenAI 兼容”不足以判断协议。

Dify 中找不到 OpenAI-API-compatible 插件怎么办？

先确认当前 Dify 实例版本、账户权限和插件市场可用性，再查看模型供应商或插件管理入口。菜单名称可能随版本和部署方式变化，无法看到入口时不要直接假设插件已经安装。