Dify 接入 OpenAI 兼容模型配置教程
Dify 自带的模型供应商不够用、想接自己的聚合网关怎么办？这篇从验证 Key 开始，一步步在 Dify 里添加 OpenAI 兼容模型，附字段填写对照表、五个高频报错和计费核对方法。
Dify 装好之后第一件卡人的事，往往不是编排工作流，而是「模型从哪来」。默认的 OpenAI 供应商要绑官方 Key，国内直连还不稳；想换成自己的聚合网关，就得走 OpenAI-API-compatible 这一条路。配置项不多，但三个字段填错一个就报 404 或 401，而且报错信息往往指向不到真正原因。
这篇按操作顺序走一遍：先用 curl 确认 Key 和地址没问题，再进 Dify 填字段，最后核对计费和常见坑。
先说结论
- Dify 接第三方网关，用 OpenAI-API-compatible 供应商，只填三项：模型名、API Key、Base URL
- Base URL 必须带
/v1，模型名必须和价格页上的名字逐字一致，这是 90% 报错的来源 - 一个供应商条目只能填一个模型名，要多模型就多建几条，或用「自定义模型」逐个添加
- 配完先在 Dify 的「模型可用性测试」里跑一次，别等到应用报错才回头查
为什么 Dify 后面常挂一层聚合网关
Dify 的应用场景天然是多模型的：同一个工作流里，意图分类用便宜的小模型，改写用中档模型，最终回答用旗舰模型。如果每家官方各绑一个 Key，你会同时面对三种计费后台、三种限流策略、三种余额告警。
挂一层 OpenAI 兼容网关后，所有模型共用一个 Key、一份余额、一套限流规则，Dify 里也只需要维护一个供应商条目。协议层面的细节可以看 OpenAI 兼容协议详解，Dify 用的就是最标准的 POST /v1/chat/completions。
第一步：命令行验证 Key
在配 Dify 之前，先确认这个 Key 在网关侧是通的：
curl -sS https://api.zaimod.com/v1/chat/completions \
-H "Authorization: Bearer $ZAIMOD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-mini",
"messages": [{"role": "user", "content": "只回复 ok"}],
"max_tokens": 16
}'返回里有 choices[0].message.content 就算通了。如果这里就 401，说明 Key 复制时带了空格或换行；如果返回 model_not_found，说明模型名写错了，去 价格页 复制原始字符串，不要自己推断命名规则。
同一个 Key 也能列模型清单，配置时对着它核对名字：
curl -sS https://api.zaimod.com/v1/models \
-H "Authorization: Bearer $ZAIMOD_API_KEY" | head -c 600第二步：在 Dify 里添加供应商
不同版本的 Dify 菜单措辞略有差异，路径大体一致：
- 右上角头像 → 设置 → 模型供应商
- 在列表里找 OpenAI-API-compatible，没装过就先点安装（新版 Dify 把供应商做成了插件）
- 点 添加模型，模型类型选 LLM（做知识库就再加一条 Text Embedding）
- 按下表填字段
- 保存后点该模型右侧的 测试，或在应用里发一条消息验证
- 回到 系统模型设置，把系统推理模型指到刚加的模型
字段对照：
| Dify 字段 | 该填什么 | 常见错法 |
|---|---|---|
| 模型名称 | 与价格页完全一致的 ID，如 gpt-4o-mini | 写成「GPT-4o mini」或加厂商前缀 |
| API Key | 网关生成的 sk- 开头密钥 | 粘贴时带换行，或误填成官方 Key |
| API endpoint URL | https://api.zaimod.com/v1 | 漏掉 /v1，或误填成网页域名 |
| 模型类型 | LLM / Text Embedding / Rerank 按用途选 | 一个条目混填多种类型 |
| 上下文长度 | 按模型实际能力填，如 128000 | 填得比真实值大，长文直接截断报错 |
| 最大 token | 输出上限，通常 4096 起 | 设成 0 或超过模型上限 |
第三步：把嵌入模型也配好
知识库检索走的是 embedding 接口，和对话模型是两条独立链路。Dify 要求 embedding 模型维度固定，一旦灌了库就不能随便换——这一点和 Embedding 模型怎么选 里说的一样，选型阶段就要定死。
配置方式和 LLM 一样，只是模型类型选 Text Embedding，模型名填 text-embedding-3-small 这类实际存在的 ID。Dify 里同时要填「向量维度」，必须和模型真实维度一致，否则检索时报维度不匹配。
五个高频报错
| 报错现象 | 真实原因 | 处理 |
|---|---|---|
| 404 Not Found | Base URL 多了或少了 /v1 | 只写到 /v1 |
| 401 Unauthorized | Key 带空白字符，或用了别家的 Key | 重新复制，去掉首尾空白 |
| model_not_found | 模型名大小写或连字符不一致 | 从价格页原样复制 |
| 400 参数错误 | 传了模型不支持的字段，如给旧模型加 reasoning 参数 | 去掉该参数或换模型 |
| 429 Too Many Requests | 并发或 RPM 超限 | 见 429 排查思路，降低并发或加退避 |
429 的处理细节单独写过一篇：大模型 API 429 限流怎么解，Dify 里表现为「工作流执行失败」而不是明确限流，容易被误判成模型故障。
配完之后核对计费
Dify 自己不算钱，账单在网关侧。上线前建议做一次对账：在 Dify 里跑一个固定输入的应用，记录返回的 usage，再和网关的用量记录比对。
# 在 Dify 的 HTTP 节点或本地脚本里跑一次，确认 usage 正常回传
import os
from openai import OpenAI
client = OpenAI(api_key=os.environ["ZAIMOD_API_KEY"],
base_url="https://api.zaimod.com/v1")
r = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "用一句话解释什么是向量检索"}],
)
print(r.usage) # prompt_tokens / completion_tokens 都有值才正常
print(r.choices[0].message.content)usage 为 0 或缺失，通常说明该模型走的是特殊计费口径（按次计费的图像、视频模型就是如此），这类模型不适合放在 Dify 的对话节点里逐字计费，要单独核算。
定价口径参考站内 价格速查：以 gpt-4o-mini 为例，$0.156 / $0.624 每百万 tokens（输入 / 输出），一个日常问答应用一天跑一万次、每次平均两千 tokens，成本大致在小几美元量级，属于可以先上线再优化的范围。
常见问题
Q：Dify 里能一个供应商挂多个模型吗？
OpenAI-API-compatible 是按条目管理的，一条对应一个模型名。多模型就多建几条，共用同一个 Key 和 Base URL 即可，成本不会因此变化。
Q：为什么 Dify 测试通过，应用里还是失败？
多数是系统模型设置没切过去，或工作流里某个节点单独指定了别的模型。逐个节点点开看模型选择，别只看全局设置。
Q：自建的 Dify 需要改环境变量吗？
不需要为网关改任何变量。除非你要绕开公司代理，那需要给容器配 HTTP_PROXY / NO_PROXY，把 api.zaimod.com 加进白名单。
Q：本地 Ollama 和网关能混用吗？
能。Ollama 走自己的供应商条目，网关走 OpenAI-API-compatible，两者在同一个工作流里可以并存，按节点选即可。
延伸阅读
- OpenAI 兼容协议详解：为什么改个 base_url 就能换供应商
- API Key 怎么购买：从注册到首次调用
- Embedding 模型怎么选：RAG 场景选型指南
- 注册账户领取 Key，配好即可在 Dify 里跑通