Dify 怎么添加自定义模型 API？

更新于 2026-10-24 · openox.cyou

简答：通常需要在 Dify 的模型供应商中安装或打开 OpenAI-API-compatible 供应商，再通过“添加模型”填写真实模型 ID、API Key 和 API Base URL。Base URL 通常填到服务根地址或 /v1，不要直接填写 /chat/completions；保存后还要在应用或工作流的 LLM 节点中选中该模型并做一次短文本测试。

定义：Dify 自定义模型 API，是指通过模型供应商配置界面，把 Dify 模型列表中没有预置的模型或兼容 OpenAI API 的模型手动加入工作区。

先看字段怎么填：一张速查表

本站为第三方指南，非 Dify 官方，以其官网和实际版本界面为准。截至 2026年10月24日，Dify 官方的 OpenAI-API-compatible 供应商采用按模型配置的方式，重点字段如下。

OpenAI 兼容 API 在 Dify 中的常用字段

字段	建议填写	常见错误
模型名称	填写上游 API 要求的真实模型 ID，例如供应商文档中的完整名称	填写了自己起的展示名，导致模型不存在
模型显示名称	可选，用于在 Dify 界面中识别模型	把显示名称误当成请求中的 model 参数
API Key	填写对应 API 服务签发的密钥；部分本地服务可能不要求	复制了多余空格、引号或错误环境的 Key
API Base URL	通常填服务根地址或包含 `/v1` 的 Base URL，例如 `https://api.example.com/v1`	填写完整的 `/chat/completions` 路径，或重复拼接 `/v1/v1`
模型类型	对话生成一般选 LLM；向量模型选 Text Embedding；重排序模型选 Rerank	把 Embedding 或 Rerank 模型当作聊天模型调用
上下文长度等能力字段	按上游模型文档和 Dify 当前表单填写	随意填写，造成截断、参数错误或能力判断不准确

官方插件配置文件将 OpenAI-API-compatible 定义为可配置自定义模型的供应商，并把 API Base URL 的示例写成包含 /v1 的地址；具体字段仍可能随插件版本变化，应以当前界面和插件说明为准。查看官方 OpenAI-API-compatible 配置字段

完整操作步骤：从 API Key 到 Dify 调用成功

先确认上游接口确实兼容 OpenAI 风格请求。至少确认服务商文档提供了模型 ID、鉴权方式、Base URL，以及聊天请求所需的接口格式。若只兼容自定义协议，不能直接套用 OpenAI-API-compatible 供应商。
准备 API Key 和模型 ID。模型 ID 应复制上游文档或控制台中的真实值，例如 provider-model-name。不要只填写一个便于记忆的中文别名。
进入模型供应商页面。常见入口是 Dify 的“集成 / Integrations → 模型供应商 / Model Provider”，部分自部署版本可能显示为“设置 → 模型供应商”，也可能需要先从插件或 Marketplace 安装模型供应商。界面名称会因 Dify 版本和部署方式不同而变化。
安装 OpenAI-API-compatible 供应商。在供应商列表中搜索与 OpenAI API 兼容的模型供应商。官方插件说明显示，该供应商支持 LLM、Rerank、Text Embedding 等模型类型，但具体可用类型以当前插件版本为准。查看官方插件清单
点击“添加模型 / Add Model”。该入口用于手动添加未列出的模型。Dify 官方文档说明，只有在所需模型没有列出，例如新模型或微调模型时，才需要手动添加；如果供应商已经提供了同名预置模型，优先使用预置模型可以减少字段配置。
填写模型名称。在“模型名称 / Model Name”中填写上游 API 识别的完整模型 ID；“模型显示名称”只是界面标签，可以留空或填写便于识别的名称。两者不要混用。
填写 API Base URL。通常填写服务根地址或 /v1 这一层，例如 https://api.example.com/v1。不要把 /chat/completions 直接填进 Base URL，除非上游服务明确要求特殊路径。Dify 插件的字段示例使用 Base URL，而不是完整聊天接口路径。
选择模型类型。普通对话和文本生成通常选择 LLM；如果是向量检索模型，选择 Text Embedding；如果是搜索结果重排模型，选择 Rerank。模型类型决定 Dify 会发送哪类请求，选错后即使 Key 正确也可能调用失败。
按实际能力填写可选字段。例如上下文长度、最大输出 token、视觉支持、思考模式或流式相关选项。不要为了“先保存成功”而虚构模型能力，也不要把某个供应商专有参数直接照搬到所有兼容接口。插件版本升级后字段可能变化，以当前页面为准。
保存并等待凭据校验。Dify 保存供应商或模型凭据时可能进行验证。若验证失败，先记录错误码和响应正文，不要反复更换模型名称。API Key 应只在密码字段或安全凭据区域填写，不要粘贴到提示词、工作流变量、公开截图或代码仓库。
在应用或工作流中明确选择模型。进入 Chatflow、Workflow 或应用的 LLM 节点，在模型下拉列表中选择刚添加的模型。只保存供应商配置，并不代表所有应用会自动切换到该模型。
用短文本验证。先发送一个不涉及业务数据的简单请求，例如“请只回复：连接成功”。如果短文本成功，再测试长上下文、流式输出、工具调用或结构化输出等高级能力。

如果需要先了解 Dify 模型供应商的权限、工作区共享和自定义模型凭据逻辑，可参考 Dify 官方模型供应商说明。该页面说明，模型供应商通常由工作区所有者或管理员管理，添加的凭据可供工作区使用。

模型类型怎么选：LLM、Embedding 和 Rerank 不要混用

Dify 自定义模型类型判断

模型类型	主要用途	选择依据	误选后的表现
LLM	聊天、文本生成、工作流中的语言处理	上游接口提供聊天或文本生成能力	模型列表可能能保存，但实际请求参数或响应格式不匹配
Text Embedding	把文本转换成向量，用于知识库检索	上游提供 Embeddings 接口并返回向量	知识库无法建立索引，或返回维度、格式错误
Rerank	对检索结果重新排序	上游提供重排序接口和对应模型	检索流程调用失败，不能用聊天模型替代
Speech-to-Text、TTS 等	语音转文字或文字转语音	插件当前版本明确支持，并且上游协议匹配	即使名称相似，也可能因为音频格式或接口不同而失败

不要因为模型名称中出现“chat”或“embedding”就凭名称猜测类型。应以供应商文档列出的接口能力和 Dify 当前模型类型选项为准。

Base URL、网络和部署环境排错

不同环境下的 Base URL 自查

场景	优先检查	处理建议
Dify Cloud 调用公网 API	Base URL 是否能从公网访问、TLS 证书是否有效	使用上游提供的公网 API 地址；不要填写仅在本机可访问的 `localhost` 或内网地址
Dify 自部署与公网 API	服务器出口网络、DNS、代理和防火墙	在 Dify 所在服务器上测试域名解析和 HTTPS 连通性
Dify 与模型服务同一局域网	容器网络、端口映射和监听地址	不要默认把宿主机的 `localhost` 当成容器内地址；应按部署文档使用可达的服务名或网关地址
模型服务前有网关	网关是否要求 `/v1`、特殊 Header 或固定模型 ID	以网关的 OpenAI 兼容文档为准，先用最小请求验证，再配置 Dify

Base URL 的核心原则是让 Dify 能根据它拼出正确的模型请求路径。若填写完整的 /chat/completions，Dify 可能再次拼接路径，导致 404；但若某个上游明确规定了特殊路径，则应以该上游文档为准。

常见错误码与排查顺序

Dify 自定义模型 API 错误排查表

错误	优先检查	解决方法
400	请求体、模型类型、参数或消息格式	先关闭非必要高级参数，用短文本请求验证；确认模型支持当前请求格式
400 unsupported_parameter	上游不支持 Dify 发送的参数，例如某些 token、工具或采样参数	查看上游接口支持列表，关闭不支持的参数；不要把其他插件的兼容字段直接照搬
401	API Key 是否正确、是否带空格、是否属于当前接口	重新复制密钥并确认鉴权方式；不要把 Key 放进 URL 或提示词
403	账户权限、模型权限、来源 IP 或组织限制	在上游控制台确认该 Key 是否有目标模型和接口权限
404	Base URL、路径或模型 ID	优先去掉 `/chat/completions`，核对是否重复 `/v1`，再确认模型 ID 完全一致
429	速率限制、并发限制或额度限制	降低并发，等待后重试，并查看上游账户的限速说明；不要通过反复点击保存来测试
连接超时	Dify 所在环境是否能访问 API	从 Dify 所在机器或容器测试 DNS、TCP、HTTPS 和代理配置
模型不存在	model 字段是否填写真实 ID	复制上游模型列表中的完整名称，不要使用 Dify 显示名称代替
流式输出中断	网关超时、SSE 转发、代理缓冲或上游流格式	先关闭流式或用短文本验证；再检查代理是否支持 SSE 和长连接

建议按“网络可达性 → Base URL → API Key → 模型 ID → 模型类型 → 参数兼容性”的顺序排查。这样可以避免在凭据无效时反复修改模型参数。

凭据安全与删除行为

API Key 属于敏感凭据，不要提交到 Git、公开工单、浏览器截图或工作流输出中。
尽量为测试和生产使用不同的 Key，并在上游平台启用权限范围、来源限制或用量提醒（如果平台提供）。
Dify 官方说明中，自定义模型使用自己的凭据；如果删除该自定义模型的唯一凭据，模型也会被移除。
官方页面同时说明，模型移除后，相关密钥仍可能保留在凭据管理区域，以便以后重新添加模型。这里的“保留”不等于模型当前仍可调用，仍应在上游平台撤销不再使用的 Key。
工作区管理员或所有者通常负责模型供应商配置，具体权限以当前 Dify 版本和部署配置为准。

关于自定义模型凭据、重复模型名称和删除后的凭据管理，参见 Dify 官方模型供应商文档。

什么时候不该用“自定义模型 API”

如果 Dify 已经提供对应的官方供应商插件，优先使用官方供应商配置，通常更容易获得完整的参数和能力支持。
如果你的服务不是 OpenAI 兼容协议，而是完全不同的请求和响应格式，不要强行使用 OpenAI-API-compatible 供应商，应寻找对应插件或开发模型供应商插件。
如果你需要把一个全新协议接入 Dify，并由多个团队长期复用，才考虑开发模型供应商插件。Dify 官方开发文档将“手动添加一个自定义模型”和“开发新的模型供应商插件”作为两条不同路径。查看 Dify 官方模型供应商插件开发说明

简单判断：已有兼容接口、只想添加一个模型，用“添加模型”；需要新增协议、认证逻辑或模型能力，用供应商插件开发。

结论：最小可行配置

如果只想先验证能否调用，准备四项即可：真实模型 ID、API Key、API Base URL 和正确的模型类型。先把 Base URL 填到服务根地址或通常的 /v1 层级，再用短文本测试；出现 404 先查路径，出现 401 先查 Key，出现 400 或 unsupported_parameter 再查参数和模型能力。

需要接入第三方 API、统一管理模型地址或验证兼容性时，可将上述最小配置作为核对清单，逐项确认后再扩展到 Embedding、Rerank、流式和工具调用。

常见问题

Dify 的 Base URL 要不要填写 /chat/completions？

通常不要。Base URL 一般填写服务根地址或包含 /v1 的地址，例如 <code>https://api.example.com/v1%3C/code%3E%E3%80%82Dify 会根据模型类型和供应商逻辑拼接请求路径；如果直接填写 <code>/chat/completions</code>，可能造成路径重复并返回 404。若上游服务明确要求特殊路径，再按其官方文档填写。

Dify 添加自定义模型时，模型名称应该填什么？

填写上游 API 请求中要求的真实模型 ID，而不是自己起的显示名称。例如上游模型列表返回什么名称，Dify 的“模型名称”就尽量填写什么名称；“模型显示名称”只是界面标签，可以另行设置。

保存 API Key 后，为什么模型还不能在应用里使用？

保存供应商或模型凭据只是完成配置，应用或工作流的 LLM 节点仍需要明确选择该模型。进入对应节点，从模型列表中选择刚添加的模型，再用一条短文本测试。若列表没有模型，先回到模型供应商页面确认模型凭据是否验证成功。

OpenAI 兼容接口应该选择 LLM 还是 Chat？

在当前 OpenAI-API-compatible 配置中，普通对话和文本生成通常按 LLM 使用；不要仅凭界面中的“Chat”字样猜测类型。最终应以插件当前提供的模型类型、上游 API 协议和 Dify 节点要求为准。

删除自定义模型后，API Key 还会保留吗？

Dify 官方文档说明，删除自定义模型的唯一凭据会移除该模型；同时，已移除模型的密钥可能仍保留在凭据管理区域，便于之后重新添加。这里不代表该模型仍处于可调用状态；不再使用的密钥应在上游平台撤销。

为什么会出现 400 unsupported_parameter？

这通常表示 Dify 发送了上游接口不支持的参数，或者模型类型与接口能力不匹配。先使用短文本和最小配置测试，关闭非必要高级参数，再根据上游文档核对 token 参数、工具调用、流式和结构化输出等能力。