AIGoCode

Dify 接 OpenAI 兼容 API：配置、验证与常见报错排查

更新于 2026-10-26 · aigocode.cyou

简答：Dify 接 OpenAI 兼容 API，通常应在模型供应商中安装或选择 OpenAI-API-compatible 插件，填写 API Base URL、API Key、模型 ID和模型类型，再到 LLM 节点明确选中该模型。先用兼容服务公开的模型接口验证地址与模型名，再运行最小 Workflow，可避免凭据验证成功但实际调用失败。

定义：Dify 接 OpenAI 兼容 API，是指在 Dify 工作区配置一个遵循 OpenAI 请求格式的模型服务，使 LLM、Embedding、Rerank 或其他模型能力能够被 Dify 应用和工作流调用。

先看配置对照表：你需要填什么

这套方法适用于已经拥有 OpenAI 兼容服务的 API Key、Base URL 和模型名称的用户。Dify 官方插件仓库将 OpenAI-API-compatible 定义为兼容 OpenAI API 标准的模型供应商，并支持 LLM、Rerank、文本嵌入、语音识别和语音合成等模型类型；具体能力仍取决于上游服务和插件配置。官方插件说明

配置项填写内容示例检查重点
供应商OpenAI-API-compatibleOpenAI-API-compatible不要误装成仅面向 OpenAI 原生服务的供应商
模型类型根据用途选择 LLM、Text Embedding、Rerank 等LLM对话模型、向量模型和重排模型不能混用
Model Name上游接口实际识别的模型 IDprovider-model-id优先以服务返回的模型 ID 为准，不要只填展示名称
API Key上游服务提供的密钥sk-...不要把密钥写入公开文章、截图或 URL
API Base URL兼容接口的基础地址https://api.example.com/v1不要直接填完整的 /chat/completions 路径
API TypeLLM 的请求协议Chat Completions只有上游明确支持 Responses 时才选择 Responses

官方配置文件显示，LLM 的 API Type 可选择 Chat Completions 或 Responses，token 参数名还可以选择自动、max_tokens 或 max_completion_tokens；如果上游对参数有明确要求，应按上游文档选择，而不是仅凭模型名称猜测。官方供应商配置文件

配置 Dify 接入 OpenAI 兼容 API

  1. 准备四项信息。先从兼容 API 服务的控制台或文档确认 API Key、Base URL、模型 ID和可用协议。本文不绑定某一家服务；如果某个字段在服务方文档中没有明确说明，应标记为“未核实”，不要根据其他服务的写法直接套用。
  2. 进入模型供应商。在 Dify 工作区打开模型供应商配置入口。Dify 文档说明，模型供应商是在工作区级别配置的，通常只有工作区管理员或所有者能够添加、修改和删除供应商凭据。不同 Dify 版本或部署方式的菜单名称可能不同，看到“设置 → 模型供应商”或类似的 Model Provider 入口即可。Dify 模型供应商文档
  3. 安装或选择 OpenAI-API-compatible。在插件市场或模型供应商列表中查找该名称。官方插件清单显示，该插件属于模型插件，并支持自定义模型配置；插件版本会随 Dify 官方插件仓库变化，界面字段以你当前安装的版本为准。官方插件清单
  4. 选择模型类型。只做聊天或文本生成时选择 LLM；做知识库向量化时使用 Text Embedding；需要重排检索结果时使用 Rerank。不要因为一个服务同时宣传多种能力，就默认同一个模型 ID可以用于所有类型。
  5. 填写模型名称和凭据。Model Name 填上游接口识别的完整模型名，API Key 填密钥，API Base URL 填基础地址。显示名称只是 Dify 界面中的称呼，不能替代请求时使用的模型 ID。官方配置文件将模型显示名称、API Key、模型名称和 API Base URL 分成不同字段。官方字段定义
  6. 保存并验证。先完成供应商层面的凭据验证，再进入应用或 Workflow 的 LLM 节点，明确选择刚添加的模型。验证凭据只代表 Dify 能完成该阶段的检查，不等同于所有模型、参数和业务请求都已验证成功。

Base URL、/v1 和 /chat/completions 怎么填

最容易出错的是把 Base URL、版本前缀和完整接口路径混在一起。通常应把 Base URL 填到兼容服务要求的基础层级，例如 https://api.example.com/v1，而不是直接填写 https://api.example.com/v1/chat/completions。但是否包含 /v1 不能脱离当前插件版本和模型类型判断。

官方 OpenAI-API-compatible 示例对 LLM/chat 模型使用带 /v1 的地址；同一份官方说明还指出，部分非 LLM 类型会在内部追加 API 版本，因此示例中使用不带 /v1 的基础地址，以避免出现 /v1/v1。这意味着你应先确认当前字段对应的模型类型和插件逻辑，再决定是否添加版本路径。官方兼容插件示例

先用接口验证，再在 Dify 中跑最小 Workflow

如果兼容服务提供模型列表接口，可以先在本地验证地址、密钥和模型 ID。下面的命令仅展示通用检查思路，实际路径和鉴权方式以服务方文档为准。密钥通过交互式输入，避免写进 Shell 历史或命令行参数：

read -s API_KEY; curl -sS -H "Authorization: Bearer $API_KEY" "https://api.example.com/v1/models"

如果返回模型列表，检查其中的 id 是否与 Dify 中填写的 Model Name 完全一致，包括大小写、连字符、版本后缀和组织前缀。如果服务方没有公开 /models，不要据此断定服务不可用；应按其文档提供的最小 Chat Completions 请求进行验证。

在 Dify 中建议创建一个最小 Workflow：输入节点接收一段短文本，连接一个 LLM 节点，再连接输出节点。官方快速入门说明了创建 Workflow、添加输入变量、选择模型、测试运行以及通过对应节点的 LAST RUN 日志定位错误的基本流程。Dify Workflow 快速入门

  1. 输入节点添加一个必填的短文本变量，例如 question。
  2. LLM 节点选择刚配置的 OpenAI 兼容模型，不要继续使用系统默认模型。
  3. 在提示词中引用输入变量，例如要求模型用一句话复述用户输入。
  4. 将 LLM 输出连接到 Output 节点，运行一次最小测试。
  5. 若失败，查看失败节点的 LAST RUN 日志，记录请求协议、模型名、错误码和响应正文，再按下表排查。

401、400、404、429、超时和流式中断排查表

现象优先检查常见配置原因处理动作出处
401 或鉴权失败API Key 与请求头密钥错误、过期、权限不足或 Base URL 指向了错误服务重新复制密钥；用服务方最小请求验证；确认 Dify 保存的是当前凭据Dify 模型供应商文档
400 参数错误API Type 与 token 参数上游要求 max_completion_tokens，但当前配置发送了 max_tokens，或请求能力不匹配按上游文档切换 Chat Completions、Responses 或 token 参数名；暂时关闭不需要的扩展能力官方配置文件
404Base URL 拼接重复出现 /v1/v1，或把完整接口路径填入 Base URL打印或查看实际请求地址；按模型类型重新确认是否需要 /v1官方兼容插件说明
429上游配额与限速服务方限流、账户配额不足或并发过高降低并发，确认服务方配额和限速；必要时在 Workflow 增加失败分支或稍后重试Dify 错误处理文档
超时网络出口、响应时间与模型负载Dify 部署环境无法访问上游，或模型响应时间超过当前限制先用同一网络环境发最小请求；检查部署机出口、防火墙和上游超时设置Dify Workflow 快速入门
流式中断或无输出流式协议与网关兼容性上游 SSE 格式、流模式鉴权或中间代理处理方式不匹配先关闭流式或改用非流式确认基础调用；再按插件字段检查流模式授权与分隔符官方配置文件

兼容 API 的能力边界：不要把“能对话”当成全部兼容

OpenAI 兼容通常只表示某一组请求格式相似，不代表所有能力完全一致。一个服务可能支持 Chat Completions，但不支持 Responses；也可能支持文本对话，却不支持 Embedding、Rerank、工具调用、结构化输出、视觉输入或流式返回。Dify 官方插件配置已经把 LLM、Rerank、文本嵌入、语音识别和语音合成分成不同模型类型，并将 API Type、结构化输出、流模式授权等作为独立配置项。官方字段定义

安全与部署提醒

API Key 应保存在 Dify 的凭据配置中，不要放入公开 Workflow 输入、URL 查询参数、前端代码或截图。Dify 文档说明，模型供应商凭据是在工作区范围内使用的，管理员应只授予需要承担模型调用和计费责任的可信成员。Dify 模型供应商文档

Dify Cloud、社区版和私有化部署在菜单、插件版本、网络出口和权限上可能存在差异。本文按官方公开字段和通用流程整理，具体界面以你当前 Dify 实例显示为准；如果某个字段在当前版本中不存在，应优先查看该版本插件说明，而不是强行照搬旧教程。本文为非官方配置指南，AIGoCode 不是 Dify 官方站点；品牌归属、插件版本和服务能力以对应文档域名的公开资料为准。

配置完成后的验收清单

常见问题

Dify 的 API Base URL 要不要带 /v1？

不能一概而论。对 LLM/chat 模型，官方兼容插件示例使用带 /v1 的地址；部分非 LLM 类型可能由插件内部追加版本路径。应结合当前模型类型、插件版本和上游文档检查，避免出现 /v1/v1。

Dify 验证 API Key 成功，但运行 Workflow 仍然报 404，怎么办？

先查看失败节点的实际请求地址和模型 ID，重点检查 Base URL 是否填成了完整的 /chat/completions，或插件拼接后出现 /v1/v1。凭据验证通过不代表所有模型路径都可用。

OpenAI-API-compatible 和 OpenAI Compatible 扩展是同一个插件吗？

不是。OpenAI-API-compatible 模型供应商用于让 Dify 调用外部兼容模型；OpenAI Compatible 扩展用于把 Dify 应用暴露成兼容接口。后者官方说明支持 /chat/completions，但不支持 /models 和 /embeddings。

为什么模型能聊天，却不能做 Embedding 或 Rerank？

兼容 API 只代表特定请求格式兼容，不代表能力全部相同。应分别确认上游是否提供 Embedding 或 Rerank 接口，并在 Dify 中选择对应模型类型和模型 ID。

遇到 max_tokens 或 max_completion_tokens 参数错误怎么处理？

查看上游接口文档和 Dify 当前插件字段。官方配置支持自动选择，也支持显式指定 max_tokens 或 max_completion_tokens；如果自动判断不准确，可按上游要求手动选择。

相关阅读

参考资料

  1. 模型供应商 - Dify Docs（docs.dify.ai）
  2. OpenAI-API-compatible 模型插件说明 - Dify Official Plugins
  3. OpenAI-API-compatible 供应商字段配置 - Dify Official Plugins
  4. OpenAI-API-compatible 插件清单 - Dify Official Plugins
  5. OpenAI Compatible 扩展说明 - Dify Official Plugins
  6. 30-Minute Quick Start - Dify Docs（docs.dify.ai）
  7. 处理错误 - Dify Docs（docs.dify.ai）