Dify OpenAI 兼容 API 配置方法

更新于 2026-10-31 · laozhang.cfd

简答：Dify 接入 OpenAI 兼容 API，先确认服务商给出的 Base URL、API Key 和真实模型 ID，再在 Dify 的 OpenAI-API-compatible 模型供应商中添加 LLM。最容易出错的是 Base URL：如果完整地址是 <code>https://example.com/v1/chat/completions</code>，通常先填写 <code>https://example.com/v1</code>，不要把 <code>/chat/completions</code> 一起填入。本文只讲“Dify 作为客户端调用外部模型”，不讲把 Dify 应用暴露成 OpenAI 兼容 API。

定义：OpenAI 兼容 API 是采用相近认证方式、请求结构或端点命名的模型接口，但不同服务对 Chat Completions、Responses、流式输出、工具调用和视觉输入的支持范围可能不同。

先试这一步：用最小请求确认接口真的可用

配置 Dify 前，先在能访问模型服务的机器上验证四项信息：Base URL、API Key、模型 ID和聊天端点。不要一开始测试 Agent、工具调用、图片或结构化输出；先用一条普通文本消息确认基础调用。

curl --fail-with-body --silent --show-error \
  --connect-timeout 10 --max-time 60 \
  https://example.com/v1/chat/completions \
  -H 'Authorization: Bearer REPLACE_WITH_API_KEY' \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'JSON'
{
  "model": "REPLACE_WITH_MODEL_ID",
  "messages": [
    {"role": "user", "content": "只回复：连接成功"}
  ],
  "stream": false
}
JSON

上面的域名、密钥和模型名都是占位符。成功不能只看 HTTP 200：Chat Completions 常见响应会在 choices[0].message.content 中返回文本，但兼容服务可能存在响应字段差异，因此应同时检查响应是否为 JSON、是否出现错误字段，以及是否有可读的助手内容。LM Studio、Ollama、vLLM 和 llama.cpp 的官方文档都提供了类似的 /v1/chat/completions 接口示例，但具体模型 ID仍应以各自接口实际返回或服务文档为准。LM Studio 官方兼容端点说明、Ollama 官方兼容接口说明、vLLM 官方在线服务说明、llama.cpp 官方服务端说明。

Dify 中逐字段配置 OpenAI 兼容模型

在 Dify 中安装或启用模型插件后，选择名称为 OpenAI-API-compatible 的模型供应商，添加一个 LLM 模型。不同 Dify 部署形态、工作区权限和插件版本的菜单位置可能不同；不要只按截图找入口，应以“插件已安装、模型供应商可见、配置字段能保存”为判断标准。Dify 官方插件仓库的清单显示，该模型插件由 langgenius 维护，并包含 OpenAI 兼容模型供应商配置。查看 Dify 官方插件清单。

Dify 官方字段文件当前列出了 LLM、Rerank、文本嵌入、语音转文本和文本转语音等模型类型；本文只讨论 LLM。该文件还列出 API Base URL、模型上下文长度、API 类型、token 参数名、流式用量、视觉、结构化输出等配置项。由于这些字段会随插件代码变化，发布前应以Dify 官方 Provider 字段定义和你工作区实际安装版本为准。相关字段页面同时说明，max_tokens 与 max_completion_tokens 不能在不了解上游要求时随意互换；流式用量字段也可能被某些接口拒绝。github.com

LM Studio、Ollama、vLLM、SGLang、llama.cpp 怎么填

下面的表格只列官方资料能够核验的配置差异。对于 SGLang，Dify 的官方字段说明把它列为支持流式 usage 的 OpenAI 兼容服务示例，但没有在本文中推断其所有参数都与其他服务相同。云端聚合 API 也不能因为标注“OpenAI 兼容”就默认支持 Responses、工具调用或视觉输入，仍需以该服务的端点文档和实测响应为准。

LM Studio 官方示例把本地 Base URL写为 http://localhost:1234/v1；Ollama 官方示例使用 http://localhost:11434/v1/，并展示了 Chat Completions 与 Responses 调用；vLLM 官方文档列出 Chat Completions、Responses 和 Embeddings 等接口；llama.cpp 官方服务端文档列出 Chat Completions、Responses 和 Embeddings 路由。LM Studio Base URL 与端点、Ollama Base URL 与模型调用、vLLM API 支持范围、llama.cpp API 路由。github.com

云端版、自部署版和插件版本如何判断差异

不要把某一张 Dify 截图当作所有环境的固定界面。云端版通常由平台控制插件运行环境；自部署版还会受到 Dify 版本、插件安装方式、Runner 架构、网络出口和工作区权限影响。实际配置时按以下顺序判断：

1. 打开当前工作区的插件管理页面，确认 OpenAI-API-compatible 插件是否已安装、启用，并记录页面显示的插件版本。
2. 进入模型供应商设置，确认是否能看到 API Base URL、模型类型和 API 类型等字段；字段不存在时，不要按旧教程强行填写。
3. 对照插件清单和 Provider 字段定义，确认当前版本是否包含 Responses、token 参数名、流式 usage、结构化输出等选项。
4. 如果自部署环境无法安装插件或保存后供应商不出现，先检查插件 Runner、工作区管理员权限和 Dify 到模型服务的网络连通性。
5. 无论云端还是自部署，最终都用外部 curl 与 Dify 的最小文本调用分别验证；外部成功、Dify 失败时，比较实际请求地址、请求体、流式设置和 token 字段。

本文核验时间为 2026 年 10 月 31 日。插件仓库的主分支和你当前环境可能不同，因此版本号、字段名称和菜单位置以当前工作区实际显示为准。Dify 官方插件仓库还提供了另一个“把 Dify 应用暴露为 OpenAI 兼容接口”的扩展，两者方向相反：模型供应商插件是 Dify 调用外部模型，兼容接口扩展则是外部客户端调用 Dify 应用。查看 Dify 官方兼容接口扩展说明。

按错误现象完成排错闭环

Dify 官方字段定义说明，流式 usage 配置会请求 stream_options: {include_usage: true}；部分 OpenAI 兼容服务只有在显式请求时才返回用量，如果接口拒绝该字段，应关闭此选项。排错日志只保留脱敏后的请求地址、状态码、响应体片段、模型类型和 API 类型，不要公开完整 Key 或 Authorization 请求头。查看流式 usage 字段说明。github.com

完成配置后的验收清单

• 外部最小请求返回可读取的助手文本。
• Dify 中已安装并启用 OpenAI-API-compatible 模型插件。
• 模型类型选择为 LLM，模型 ID与服务端真实名称一致。
• Base URL 与最终请求路径拼接后没有重复的 /v1 或 /chat/completions。
• API 类型、对话类型和上游接口实际支持范围一致。
• 在 LLM 节点、Chatflow、工作流或 Agent 中明确选择了刚添加的模型。
• 先通过普通短文本，再单独测试流式、工具、视觉和结构化输出。
• 日志和工单中没有暴露 API Key、Authorization 头或敏感用户输入。

如果 curl 成功而 Dify 失败，优先比较实际请求地址、模型字段、请求体、流式开关和 token 参数名；如果 curl 本身失败，则先修复上游接口，不要继续反复修改 Dify 界面字段。

常见问题

Dify 的 OpenAI 兼容 API Base URL 到底要不要加 /v1？

没有对所有服务都成立的固定答案。如果完整聊天地址是 https://example.com/v1/chat/completions，通常把 https://example.com/v1 填入 Base URL，再由插件补上聊天路径。若出现 404，检查 /v1 是否重复、遗漏，或 Base URL 是否误填了完整的 /chat/completions。

Dify 中的模型显示名称和模型 ID有什么区别？

显示名称主要用于界面识别，可以自定义；模型 ID会进入实际请求，必须使用服务端能识别的字符串。遇到模型不存在时，应以模型列表、启动参数或服务商文档中的真实 ID为准。

为什么已经能调用 Chat Completions，还不能使用工具或视觉？

OpenAI 兼容通常只说明部分请求格式相近，不代表所有能力都实现。聊天、流式、工具调用、视觉和结构化输出应分别验证；先用普通短文本成功，再一次只开启一个高级能力。

Dify 配置后返回 400，最先应该关闭哪些选项？

先关闭工具调用、视觉输入、结构化输出、扩展思考和非必要额外参数，保留 LLM、Chat、普通文本消息和非流式请求。基础请求成功后，再逐项启用并记录是哪一个字段触发错误。

Ollama、LM Studio 或本地 llama.cpp 没有真正的 API Key，Dify 怎么填？

应按 Dify 字段要求填写一个占位值或本地服务要求的值，同时以本地服务官方文档为准。Ollama 官方 OpenAI 兼容示例注明本地接口示例中的 Key 会被忽略；这不代表所有本地服务或远程网关都允许空 Key。

Dify 的 OpenAI-API-compatible 模型插件和把 Dify 应用变成兼容 API 是同一个功能吗？

不是。前者让 Dify 作为客户端调用外部模型；后者让外部客户端调用 Dify 应用。本文只覆盖前者，即在 Dify 中配置外部 OpenAI 兼容模型。

相关阅读

• Continue OpenAI 兼容接口配置教程
• Cline OpenAI 兼容接口配置与排错
• API 返回 401 时如何核对 Key、请求头和 Base URL

参考资料

1. Dify 官方 OpenAI-API-compatible Provider 字段定义
2. Dify 官方 OpenAI-API-compatible 插件清单
3. Dify 官方 OpenAI 兼容接口扩展说明
4. LM Studio 官方 OpenAI 兼容端点说明（lmstudio.ai）
5. Ollama 官方 OpenAI 兼容接口说明
6. llama.cpp 官方服务端与 OpenAI 兼容 API 说明
7. docs.vllm.ai（docs.vllm.ai）