Dify 接入 OpenAI 兼容模型的完整配置指南
简答：在 Dify 中进入“设置 → 模型供应商”，安装或选择“OpenAI API Compatible”，再填写模型名称、API Key、API Base URL 和上下文长度，保存并测试后，即可在工作流或聊天应用的 LLM 节点中使用该模型。
定义：OpenAI 兼容模型是指能够按照 OpenAI API 请求格式提供服务的模型或网关，通常至少需要兼容聊天接口、鉴权方式和模型名称参数。
一、接入前需要准备什么
Dify 接入 OpenAI 兼容模型前，先确认服务端提供的是可调用的兼容接口，而不是只有网页端或其他厂商专用 SDK。至少需要准备以下信息：
- API Key：用于鉴权的密钥。不要把真实密钥写入公开仓库、截图或前端代码。
- API Base URL：服务商提供的基础地址，例如
https://api.example.com/v1。具体路径必须以服务端文档为准。 - 模型名称：请求中实际使用的模型标识，通常需要完整填写，不能只写展示名称。
- 模型类型：普通对话模型一般选择 LLM；如果要做知识库检索，还可能需要单独配置文本嵌入模型或重排模型。
- 上下文长度：填写服务端允许的上下文上限。无法核实时不要凭经验填写过大的数值，应以模型服务商文档为准。
Dify 官方文档将自定义供应商定义为使用自己的 API 密钥直接访问模型服务，并说明模型供应商配置位于工作区层面；只有工作区管理员或所有者通常可以修改这类配置。可先阅读 Dify 模型供应商文档确认当前版本的入口和权限。
二、Dify 添加 OpenAI 兼容模型的步骤
- 进入模型供应商设置。登录 Dify 工作区，打开“设置”或工作区管理中的“模型供应商”。不同版本的菜单文字可能略有差异。
- 安装或启用兼容供应商。搜索并选择“OpenAI API Compatible”。Dify 官方插件配置中，该供应商支持通过自定义模型方式添加模型，适用于兼容 OpenAI API 标准的服务。
- 选择模型类型。普通文本对话选择 LLM。若配置的是向量模型或重排模型，应分别选择 Text Embedding 或 Rerank，而不要把它们当作聊天模型添加。
- 填写模型名称。在“Model Name”或“模型名称”中输入服务端要求的完整模型 ID，例如
your-model-name。这个值应与服务端模型列表或接口文档一致。 - 填写 API Key。把密钥填入密钥字段。若服务端不要求密钥，只有在其官方文档明确说明时才可以留空；不要为了绕过错误随意填写虚假的密钥。
- 填写 API Base URL。填写基础地址，例如
https://api.example.com/v1。通常不要把/chat/completions再拼到 Base URL 末尾，因为 Dify 会根据 API 类型继续构造请求路径；但最终仍应以服务端接口规范为准。 - 设置上下文长度和能力选项。根据服务端文档填写上下文长度、最大输出 token、视觉支持和思考模式支持等选项。没有明确证据时，建议关闭未确认的能力，避免 Dify 发送服务端不支持的参数。
- 选择 API 类型。官方兼容插件目前提供 Chat Completions 和 Responses 等选项。若服务端只兼容传统聊天接口，应优先选择 Chat Completions；只有服务端明确支持 Responses API 时才选择 Responses。
- 保存并测试。保存模型后，在 Dify 的模型测试区域或应用的 LLM 节点中发起一条最短文本请求，例如“请只回复：连接成功”。能返回正常文本，才说明基本接入完成。
官方插件配置文件列出了 API Key、API Base URL、模型名称、上下文长度、兼容模式和 API 类型等字段，可参考 Dify OpenAI API Compatible 插件配置核对字段含义。
三、推荐的最小测试方法
完成 Dify 配置后，不要立即接入复杂 Agent 或知识库。先用一个只包含用户输入和 LLM 节点的最小应用测试。建议按以下顺序操作：
- 新建一个 Chatflow 或 Workflow。
- 添加一个 LLM 节点。
- 在模型列表中选择刚刚添加的兼容模型。
- 系统提示词填写“你是一个连接测试助手，只输出收到的文本”。
- 用户输入填写“连接测试”。
- 运行并观察是否返回文本、是否发生超时、是否出现参数不兼容。
如果服务端本身支持标准 OpenAI 风格的聊天请求，也可以先用命令行独立验证，排除 Dify 配置之外的问题。示例结构如下，地址、密钥和模型名都必须替换为服务端文档中的实际值：
curl https://api.example.com/v1/chat/completions -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"model":"your-model-name","messages":[{"role":"user","content":"只回复：连接成功"}]}'
命令行能够成功而 Dify 失败，通常应重点检查 Base URL、API 类型、模型名称和 Dify 发送的额外参数；命令行也失败，则优先检查密钥权限、接口路径和服务端状态。OpenAI 官方 API 文档可用于理解标准鉴权和请求结构，但兼容服务是否完全支持这些字段，仍应以对应服务端文档为准：OpenAI API Reference。
四、常见错误与排查表
| 现象 | 优先检查项 | 处理方法 |
|---|---|---|
| 401 Unauthorized | API Key 或鉴权格式 | 重新复制密钥，确认服务端要求 Bearer 鉴权，并检查密钥是否过期或被撤销。 |
| 403 Forbidden | 账号权限、模型权限或访问限制 | 确认当前密钥是否有目标模型权限；不要仅通过更换模型名称来猜测权限问题。 |
| 404 Not Found | Base URL 和接口路径 | 检查是否把完整的 /chat/completions 地址错误填入了 Base URL，或是否多写、少写了 /v1。 |
| 400 参数错误 | API 类型、参数和能力设置 | 关闭未确认的视觉、工具调用、思考模式等选项，并确认服务端支持 Dify 当前发送的字段。 |
| 429 Too Many Requests | 服务端限速、并发或余额 | 降低并发，减少短时间重复测试，并查看服务端返回的限速说明或用量状态。 |
| 请求超时 | 服务端响应时间、网络和模型负载 | 先用短提示词测试，确认基础接口可用，再逐步增加上下文；不要一开始把问题归因于 Dify。 |
| 流式输出中断 | 网关、反向代理或流式兼容性 | 先关闭复杂工具调用并测试普通文本；确认服务端和中间代理是否支持 SSE 或 Dify 所需的流式格式。 |
五、配置时容易忽略的兼容性问题
- Base URL 不等于完整请求 URL：插件配置将 API Base URL 作为独立字段，示例形式是带版本路径的基础地址。最终是否需要
/v1，要看服务端实际路由。 - 模型名称是服务端 ID：Dify 中的显示名称可以自定义，但请求使用的模型名称必须是服务端能够识别的值。
- Responses 与 Chat Completions 不能混用：有些服务只实现其中一种接口。遇到 404 或参数错误时，应先确认服务端支持的 API 类型。
- 工具调用不一定兼容：即使文本聊天成功，也不代表函数调用、结构化输出、视觉输入或 Agent 工具调用全部可用。应逐项测试。
- 知识库通常需要额外模型：聊天模型能正常返回文本，不代表它可以直接承担 Embedding 或 Rerank 任务。知识库场景应分别确认对应模型类型和接口。
- 插件版本会影响字段：Dify 及其官方插件会持续更新，实际界面可能比旧教程多出兼容模式、token 参数名等选项。遇到字段名称不同，应优先以当前插件配置和界面提示为准。
六、配置完成后的安全建议
- 不要把 API Key 放在浏览器前端、公开仓库、教程截图或工作流输出中。
- 为不同环境使用不同密钥，测试密钥和生产密钥分开管理。
- 定期查看服务端用量、请求日志和错误日志，发现异常时及时撤销密钥。
- 为生产应用设置合理的并发、超时和最大输出 token，避免单次请求消耗过多资源。
- 如果要切换多个模型供应商，先统一记录每个模型的 Base URL、模型 ID、上下文长度和能力差异，再在 Dify 中分别配置，不要只依赖相同的展示名称。
需要注意，Dify 官方文档说明自定义供应商通常由供应商直接计费，并且密钥配置具有工作区范围的访问影响，因此应谨慎分配管理员和所有者权限。
相关页面导读
如果你已经完成模型接入，下一步可以继续查看 文档中心了解接口和配置概念；通过 Token 管理整理密钥使用；通过 请求日志定位 401、429 和超时问题；需要比较不同模型调用成本时，可查看 价格说明。具体服务价格、限速和可用模型应以服务方当时公布的信息为准。
常见问题
Dify 中找不到 OpenAI API Compatible 怎么办？
先确认当前 Dify 版本是否支持官方兼容插件，并在模型供应商或插件市场中搜索对应名称。插件安装后仍未显示时，刷新工作区或重新登录；如果是自托管版本，还应检查插件服务是否正常。具体界面会随版本变化，应以当前 Dify 文档和插件页面为准。
API Base URL 应该填写到 /v1 还是 /chat/completions？
通常应填写服务端定义的基础地址，例如带版本路径的 /v1，而不是完整的 /chat/completions 请求地址。Dify 会根据所选 API 类型构造后续路径，但不同兼容服务的路由可能不同，因此最终必须以服务端接口文档为准。
模型已经添加成功，但 LLM 节点仍然报 404，怎么处理？
优先检查 Base URL 是否重复包含接口路径、是否遗漏版本路径，以及模型名称是否与服务端真实 ID 一致。然后用最小聊天请求独立测试；如果独立请求也返回 404，问题通常在接口地址或模型路由，而不在 Dify 工作流。
普通对话能用，为什么知识库还不能用？
知识库通常需要文本嵌入模型，部分场景还需要重排模型。LLM 只负责生成文本，并不自动具备 Embedding 或 Rerank 能力。应在 Dify 中分别添加对应模型，并确认兼容服务确实提供这些接口。
OpenAI 兼容模型一定支持工具调用和视觉输入吗？
不一定。OpenAI 兼容通常只说明请求格式相近，不代表所有能力完全一致。工具调用、结构化输出、图片输入、流式输出和思考参数都需要分别查看服务端文档并测试，未确认的能力建议先关闭。