Free AI API and chat, one OpenAI-compati

Dify 配置 OpenAI 兼容模型 API：Base URL、模型名与报错排查

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

简答：Dify 配置 OpenAI 兼容模型 API，建议先用 API Base URL 加 API Key 请求 /v1/models，确认真实模型 ID 和权限，再在“集成 > 模型供应商”安装或启用 OpenAI-API-compatible 供应商。Base URL 填 API 根地址，不填 /chat/completions；LLM 通常选择 Chat Completions，只有服务端明确支持时再选 Responses。

定义：OpenAI 兼容模型 API，是使用近似 OpenAI 请求格式的服务接口，通常通过 API Base URL、API Key、模型 ID 和 Chat Completions 或 Responses 等协议接入 Dify。

先做接口自检：确认 Base URL、Key 和真实模型名

本文是 onomeo.cyou 的第三方接入指南，不代表 Dify 或任一 API 服务商的官方文档。配置前准备四项信息：API Base URL、API Key、接口返回的真实模型 ID，以及该模型支持的调用协议。

OpenAI 的模型列表接口返回模型的 id，这个 ID 才是可以放进 API 请求中的模型标识。兼容服务通常也沿用类似接口，因此不要直接把网页显示名称、套餐名称或自定义备注当作请求模型名。可先参考模型列表接口文档确认返回结构。

curl --fail-with-body --max-time 20 "$API_BASE_URL/models" \
  -H "Authorization: Bearer $API_KEY"

上面的示例假设 API_BASE_URL 已经包含正确的版本路径，例如 https://example.com/v1。如果服务商要求在根地址后拼接 /v1，应按其文档设置；不要为了“保险”重复拼接。

如果兼容服务没有提供 /models，公开示例只展示了部分服务的接口行为，不能据此推断所有服务都支持该路径；此时应到服务商文档核对模型列表接口，或使用其明确给出的模型 ID。

在 Dify 中安装并配置 OpenAI-API-compatible 供应商

Dify 官方文档将入口描述为“集成 > 模型供应商”，并说明工作空间所有者和管理员可以管理供应商密钥。对不在内置列表中的服务，应先安装对应供应商，再填写自己的 API 密钥和其他必要信息。具体入口可查看Dify 模型供应商文档。

  1. 进入 Dify 工作空间的集成 > 模型供应商。
  2. 搜索并安装或启用OpenAI-API-compatible供应商。
  3. 选择添加自定义模型，先选择模型类型 LLM。
  4. 在“模型名称”中填写接口返回的真实模型 ID。
  5. “模型显示名称”只用于 Dify 界面展示，可以填写便于识别的名称；不确定时可与真实模型 ID 保持一致。
  6. 在 API Key 中填写供应商密钥，在 API Base URL 中填写接口根地址。
  7. 选择对话类型、API 类型、上下文长度和最大输出 token 等字段，然后保存凭据。

官方兼容插件配置文件列出了模型名称、显示名称、API Key 和 API Base URL 等字段，并将 LLM、Rerank、文本向量、语音转文字和文字转语音作为不同模型类型处理。字段和默认值应以当前插件配置为准，可查看OpenAI-API-compatible 供应商配置文件。

字段怎么填核对重点
模型类型聊天模型一般选 LLMEmbedding、Rerank、语音模型不要混用 LLM 配置
模型名称填写接口返回的真实 ID不要只填显示名称或产品别名
模型显示名称填写界面中容易识别的名称它与请求中的模型 ID 可以不同
API Key填写供应商密钥不要放进 URL 查询参数或提交到前端代码
API Base URL填写 API 根地址不要填写完整的 /chat/completions 路径
对话类型按服务端协议选择 Chat 或 Completion大多数聊天接口优先核对 Chat Completions
上下文长度按模型或服务商文档填写未核实时不要自行宣称具体上限

Base URL、/v1 和最终请求地址怎么判断

API Base URL 与最终接口地址不是一回事。假设 Base URL 是 https://api.example.com/v1，常见的 Chat Completions 请求地址会在其后追加 /chat/completions；Base URL 不应直接填写到这个完整路径，除非该插件字段明确要求完整端点。

官方兼容插件的示例将 API Base URL 写成类似 https://api.openai.com/v1，并将其作为独立字段。配置时应先确认插件是否负责追加版本路径，再决定是否填写 /v1。可以用下面的判断表排查：

现象可能填写方式处理动作
请求变成 /v1/v1/models插件自动追加版本路径，但 Base URL 也手动加了 /v1查看插件说明，尝试去掉重复的版本路径
请求变成 /chat/completions/chat/completionsBase URL 填了完整接口路径退回 API 根地址或包含 /v1 的 Base URL
/models 能通，聊天请求 404模型接口和聊天接口的路径规则不同核对服务商的 Chat Completions 路径以及插件拼接规则
保存时提示地址无效协议、域名、路径或末尾斜杠不符合插件预期复制服务商文档中的 Base URL，再逐步删减路径测试

官方 OpenAI 插件 README 说明，其 API base 可以带或不带末尾 /v1，但这条规则属于该插件的配置说明，不能直接套用到所有兼容服务。对于 OpenAI 官方插件，可参考Dify OpenAI 插件配置说明；对于通用兼容插件，应优先以其当前字段定义和服务商文档为准。

Chat Completions、Responses API 和 token 参数怎么选

OpenAI-API-compatible 插件当前配置中提供 Chat Completions 和 Responses 两种 API 类型，默认值是 Chat Completions；同时提供 auto、max_tokens 和 max_completion_tokens 三种 token 参数选择。相关字段可以在官方插件供应商配置文件中核对。

配置项适用判断排错动作
Chat Completions服务商公开文档只提供 /chat/completions，或兼容接口明确要求该协议确认消息格式、流式格式和工具调用能力
Responses服务商明确支持 /responses，并说明请求字段与返回事件不要仅因为模型名称相同就直接切换协议
token 参数为 Auto插件可以根据模型或配置自动判断若服务端提示参数不支持，再显式选择对应字段
max_tokens服务端文档要求传统 token 参数名用最小请求验证是否接受该字段
max_completion_tokens服务端或接口协议明确要求该字段不要与不支持它的网关混用

如果接口返回“参数不支持”，先把模型配置切换到严格兼容模式，关闭未确认的扩展设置，再检查 token 参数名、用户标识参数和流式用量选项。兼容插件配置文件说明，严格模式与扩展模式会影响额外参数；部分网关还可能拒绝顶层 user 参数。找不到服务端支持声明时，应把该项视为未核实，不要凭经验强行开启。

保存后怎么验证：从最小聊天到 Dify 工作流

  1. 先验证供应商凭据：保存 API Key 和 Base URL 后，观察 Dify 的供应商验证结果。失败时不要马上修改模型能力，先回到地址和 Key。
  2. 再添加一个 LLM：只填写真实模型 ID、API Key、Base URL、对话类型和上下文长度，其余扩展能力先保持默认。
  3. 执行最小聊天：使用一条简单文本，不启用工具、联网、结构化输出、图片和复杂系统提示。
  4. 再验证流式：若非流式成功、流式失败，检查服务端是否支持 SSE，以及是否能返回结束事件和用量字段。
  5. 最后放进工作流：先用一个开始节点、LLM 节点和结束节点验证，再逐项加入知识库、工具、Agent 或结构化输出。

兼容插件的配置文件包含流式用量选项。它说明某些兼容服务只有在请求中显式要求 stream_options: {include_usage: true} 时才返回流式用量；如果端点拒绝该字段，可以关闭该选项。这个设置只应在服务端行为已经确认后调整。

如果你使用的是自建 vLLM、LM Studio、Ollama 网关或第三方聚合服务，差异通常集中在 Base URL 是否包含 /v1、是否提供 /models、模型 ID 写法、Chat Completions 支持范围、流式格式以及是否接受额外参数。不要把一个服务的端点规则直接复制给另一个服务。

Dify 常见错误对照表

错误或现象优先检查下一步
401 UnauthorizedAPI Key 是否正确、是否带 Bearer、Key 是否被撤销用同一 Key 单独请求 /models，确认不是 Dify 表单输入问题
403 Forbidden账户、项目、组织或模型权限查看服务商控制台和 Key 的访问范围
404 Not FoundBase URL、/v1、最终接口路径记录 Dify 实际请求路径，排除重复或缺少路径
模型不存在模型名称不是接口返回的真实 ID，或 Key 无权访问重新获取模型列表并复制 data[].id
429 Too Many Requests服务商速率限制、并发或配额降低并发，等待服务端给出的重试时间，并检查用量限制
参数不支持max_tokens、max_completion_tokens、user 或扩展参数切换严格模式，逐项关闭未确认的可选参数
连接超时域名解析、网络路径、服务端响应时间和 Dify 部署环境从部署 Dify 的同一环境请求 /models，区分网络与模型处理耗时
流式中断SSE 支持、代理缓冲、结束事件、include_usage 设置先关闭流式或用最小提示测试，再检查服务端流格式
/v1/v1插件和 Base URL 是否都添加了版本路径只保留一处版本路径，并重新保存凭据

排错时建议保留三份信息：Dify 中填写的 Base URL、脱敏后的请求路径、服务端返回的状态码和错误正文。不要在日志、截图或 URL 中暴露完整 API Key。

API Key、Dify 应用 Key 与供应商密钥不是一回事

配置模型供应商时填写的是上游 API 服务的供应商密钥，用于让 Dify 调用模型。Dify 应用自身的 API Key 则用于外部客户端调用 Dify 应用，两者作用方向不同，不能互相替代。

Dify 官方文档还说明，供应商密钥在工作空间范围内生效，并可能由自己的供应商账户承担调用费用；因此生产环境应限制管理员权限，区分开发与生产凭据，并定期轮换密钥。

参考资料

常见问题

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

没有适用于所有服务的统一答案。应先看兼容服务和 Dify 插件如何拼接路径：如果 Base URL 已包含 /v1，最终请求不应再次出现 /v1；如果插件会自动追加版本路径，则应按插件要求填写根地址。出现 /v1/v1 时，优先检查是否重复填写。

模型名称可以填写模型显示名称吗？

通常不建议这样做。模型显示名称主要用于界面展示，模型名称应填写接口返回的真实模型 ID。先请求模型列表，复制返回 JSON 中的 data[].id，再添加到 Dify。若服务没有模型列表接口，应以服务商公开文档给出的模型标识为准。

Dify 保存模型时提示 404，应该先改模型名还是 Base URL？

先检查 Base URL 和最终请求路径，再检查模型名。404 可能来自缺少或重复的 /v1、误填完整接口路径，也可能来自服务端没有对应端点。建议先用同一 Key 请求 /models，再核对 Dify 实际调用的 Chat Completions 或 Responses 路径。

Chat Completions 和 Responses API 应该怎么选？

如果服务商文档只提供 /chat/completions，选择 Chat Completions；只有在服务端明确支持 /responses 且字段和返回格式与插件兼容时，才选择 Responses。不能仅凭模型名称相同就判断两种协议可以互换。

为什么 Dify 流式调用成功，但用量统计不准确或流式中断？

先确认服务端是否支持 SSE 和结束事件，再检查流式用量设置。官方兼容插件说明，部分服务端只有在请求包含 stream_options.include_usage 时才返回 usage；如果端点拒绝该字段，可以关闭流式用量选项，并先用最小请求验证完整输出。

自建 vLLM、LM Studio 或 Ollama 网关都能直接套用同一配置吗？

不能直接假设完全相同。它们可能在 /v1 路径、模型 ID、/models 支持、流式格式、工具调用和额外参数上存在差异。应分别核对网关文档，再用 /models 和最小聊天请求完成两步验证。

相关阅读

参考资料

  1. Dify Docs：模型供应商（docs.dify.ai）
  2. Dify 官方插件：OpenAI-API-compatible 供应商配置文件