Dify 把提示词编排、知识库检索、工作流和 Agent 做进了同一个可视化界面，但平台预置的模型列表未必覆盖你手上的模型。只要目标服务提供 OpenAI 兼容接口，就可以作为“自定义模型”接进来，用自己的 Key、自己的账单跑应用。

实际配置时，卡住大多数人的不是点哪个按钮，而是几个细节：Base URL 少写了 /v1、模型名和网关上架的名字不一致、函数调用开关没打开、Dify 所在网络访问不到你的内网地址。本文按“准备—添加—绑定—排错”的顺序讲一遍，界面名称以当前版本为准。

说明：Dify 为其权利人的商标，本文与相关厂商无隶属关系；模型名称、上下文长度与价格以站内 模型价格 为准，本文以 2026 年 10 月的常见版本为例。

一、接入前先确认四件事

不要急着打开 Dify，先用最小请求验证上游能不能通。需要确认的是：

  1. 协议：接口是否为 OpenAI 兼容，至少提供 /v1/chat/completions。
  2. Base URL：多数服务要求填到 /v1，而不是完整的 /v1/chat/completions。
  3. 模型名：必须和网关 /v1/models 返回的一致，注意大小写、日期后缀和别名。
  4. 能力：是否支持流式输出、函数调用、视觉输入；做知识库还要确认 Embedding 维度。

用 curl 做一次预检：

curl https://你的网关地址/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "你的模型名",
    "messages": [{"role": "user", "content": "只回复 OK"}]
  }'

返回里能看到 choices，说明地址、Key、模型名三件事都对。先跑通这一步，再接 Dify，可以少走一半弯路。

二、在 Dify 中添加模型供应商

Dify 的模型接入以插件形式管理，入口和字段名称可能随版本调整。典型流程如下：

  1. 进入模型供应商设置页。
  2. 找到 OpenAI-API-compatible（OpenAI 兼容）插件并安装或启用，名称以当前版本为准。
  3. 点击添加模型，选择模型类型。
  4. 填写模型名称、API Key、Base URL。
  5. 按模型真实能力填写上下文长度、最大输出等参数。
  6. 保存后点击测试，确认能返回内容。

几个字段的填写要点：

字段 正确做法 常见错误
Base URL 一般填到 /v1，例如 https://api.example.com/v1 多写 /chat/completions 导致 404
模型名称 与 /v1/models 返回完全一致 大小写、版本后缀写错，报模型不存在
API Key 整串粘贴，不要手动加 Bearer 多了空格或引号，返回 401
模型类型 LLM、Embedding、Rerank、语音转写、TTS 按用途选 类型选错，应用里看不到该模型
上下文长度 按服务商实际支持值填，宁小勿大 填成理论上限，长请求被上游拒绝
能力开关 流式、函数调用、视觉按实际支持打开 Agent 调工具失败、图片上传被拒

三、参数不要照抄宣传页

模型页上的“最大上下文”通常是理论上限，实际可用值还受输出长度、计费方式和网关限制影响。配置时建议留出余量：

  • 上下文长度填服务商明确支持的值，不要为了“看起来更强”填到极限。
  • 最大输出单独设置，避免长文生成被截断或费用失控。
  • 不确定是否支持函数调用时，先关掉，用普通对话验证，再逐项打开。
  • 视觉模型要确认图片是走 URL 还是 Base64，部分兼容接口只支持其中一种。
  • Embedding 模型一旦用于知识库，维度就固定了；换模型通常要重建索引。

如果同一个供应商下要接多个模型，逐个添加即可。对外暴露的模型名可以和上游不同，但建议保持可读、可追溯，例如在名称里带上用途或版本。

四、把模型绑定到应用

模型添加成功，不等于应用已经用上。Dify 里至少有三个位置需要检查：

  • 聊天助手 / 文本生成应用：在应用编排页选择模型，并确认提示词变量没有把模型名写死。
  • 工作流 / Agent：每个 LLM 节点或 Agent 节点单独选模型，不同节点可以混用。
  • 知识库：在系统模型设置里指定 Embedding 模型和 Rerank 模型，索引与查询要使用同一套。

一个实用的分工是：分类、改写、抽取这类简单任务用小模型，最终生成用强模型。这样既控制成本，也减少强模型被大量短请求占满的情况。

五、常见报错与排查顺序

现象 可能原因 处理
401 Unauthorized Key 错误、过期、带上了多余字符 用 curl 复测，重新粘贴 Key
404 Not Found Base URL 路径不对 确认是 /v1，不要带完整接口路径
model not found 模型名与网关上架名不一致 调 /v1/models 核对，注意大小写
请求超时 Dify 访问不到上游，或上游响应慢 检查网络、DNS、防火墙和代理
400 context length 上下文或输出上限填得比实际大 下调参数，长文本先切分
429 Too Many Requests 触发上游限流 降低并发，配置重试与退避
工具调用失败 模型不支持函数调用或参数格式不符 关闭工具，先验证纯对话
知识库检索异常 Embedding 维度不一致 换回原模型，或重建知识库索引

还有一个容易忽略的点：如果 Dify 部署在云端或容器里，localhost、127.0.0.1 和私网地址通常不可达；部分版本还启用了 SSRF 防护，会直接拦截内网请求。把模型服务暴露为公网 HTTPS 地址，或在自部署环境里按文档配置代理与白名单。

六、稳定性与成本

接入完成后，建议再补三件事：

  1. 设置超时与重试：超时按业务最慢链路设置，重试只对 429 和 5xx 生效，避免重复计费。
  2. 记录调用日志：至少保留模型名、耗时、Token 用量和错误码，出问题能定位到具体节点。
  3. 控制上下文：知识库召回条数不是越多越好，无关片段既增加成本，也干扰回答。

成本方面，Dify 本身只负责编排，费用来自上游模型调用。把简单节点换成小模型、压缩提示词、减少无效重试，通常比换供应商更有效。具体单价以 模型价格 为准，不要用固定数字做长期预算。

常见问题

Dify 必须安装插件才能接自定义模型吗？

较新版本通过模型供应商插件管理接入，插件名称和入口以当前版本为准。若你的版本没有该插件，可先在插件市场搜索 OpenAI 兼容相关插件，或升级到支持该能力的版本。

为什么 curl 能通，Dify 里却报错？

优先检查三处：Dify 所在网络是否能访问该地址；Base URL 是否在界面里被自动拼接了路径；Key 是否被空格或换行污染。云端 Dify 无法访问你的内网地址，这是最常见的原因。

非 OpenAI 兼容的接口能直接接吗？

不能直接接。需要先用网关或适配层转换成 OpenAI 格式，再接入 Dify。转换层要处理消息结构、工具调用和流式事件，不能只做 URL 转发。

一个供应商可以添加多个模型吗？

可以。每个模型单独配置名称、上下文和能力开关，应用里按需选择。建议在命名上区分用途，避免团队成员选错。

换 Embedding 模型后知识库还能用吗？

通常不能直接混用。向量维度或语义空间变化后，旧索引与新查询不匹配，需要重建知识库并重新索引。换模型前先在小数据集上验证检索效果。

下一步

Dify 接入的核心可以归纳为三句话：先用 curl 验证上游，再按真实能力填参数，最后逐个节点确认绑定。需要统一的 OpenAI 兼容入口和用量管理，可以先 注册中商起航 AI 网关，模型与价格以 模型价格 为准。

相关阅读：