Dify 是目前最常用的开源 LLM 应用开发平台之一，聊天助手、Agent、工作流、知识库问答都能拖拽搭出来。但很多团队卡在第一步：官方模型供应商要海外信用卡、要多个账号分别管理，想用一个 Key 同时调 Claude、GPT、Gemini 却不知道在 Dify 里怎么填。其实 Dify 原生支持「OpenAI 兼容」类型的模型供应商，把 Base URL 指向中转站即可。这篇按步骤讲清配置方法、每个字段该怎么填、不同版本的差异，以及最常见的几类报错。
先理解 Dify 的模型供应商机制
Dify 里所有模型都挂在「模型供应商」下面。在设置页的模型供应商列表中，你会看到 OpenAI、Anthropic、Gemini 等官方供应商，也会看到一个叫 OpenAI-API-compatible 的通用供应商。后者的作用就是：任何实现了 OpenAI 协议的服务，都可以作为一个自定义模型加进 Dify。
需要特别注意版本差异。Dify 在 1.0 前后对模型供应商做了插件化改造：
| 版本形态 | 模型供应商在哪里 | 接入方式 |
|---|---|---|
| 较早的 0.x 版本 | 内置在设置 → 模型供应商列表中 | 直接点击对应供应商配置 |
| 1.x 插件化版本 | 需要先从插件市场安装对应供应商插件 | 安装 OpenAI-API-compatible 等插件后再配置 |
如果你在模型供应商页找不到 OpenAI-API-compatible，大概率是用的插件化版本且还没安装这个插件，去插件市场搜索安装即可。不同版本的按钮文字、字段顺序可能略有不同，下面以字段含义为准，界面对不上时按含义找对应输入框。
配置前准备
- 注册 Zivv 并完成充值（注册入口），充值汇率 ¥1 = $1
- 在控制台创建一个 API Key（sk- 开头），建议命名为「Dify 专用」，方便单独统计用量
- 到 模型广场 确认要用的模型 id，例如 claude-sonnet-5、gpt-5.5、gemini-3.5-flash
自托管 Dify 的用户还要确认一件事：部署 Dify 的服务器能访问 https://zivv.pro。可以先在服务器上跑一条 curl：
curl https://zivv.pro/v1/models \
-H "Authorization: Bearer sk-your-key-here"能返回模型列表，说明网络和 Key 都没问题。返回的 id 列表也正好用来核对后面要填的模型名。
方式一：OpenAI-API-compatible（推荐）
这是最通用、最稳妥的方式。Zivv 的 OpenAI 兼容入口可以调用 Claude、GPT、Gemini 等全部模型，所以一个供应商就能覆盖大部分需求。
第一步：添加模型
进入设置 → 模型供应商，找到 OpenAI-API-compatible（插件化版本需先安装），点击添加模型。
第二步：逐个填写字段
| 字段 | 填写内容 | 说明 |
|---|---|---|
| 模型类型 | LLM | 对话、Agent、工作流里的 LLM 节点都用这一类 |
| 模型名称 | claude-sonnet-5 | 必须与 /v1/models 返回的 id 完全一致 |
| API Key | sk- 开头的 Zivv Key | 注意不要带空格 |
| API endpoint URL | https://zivv.pro/v1 | 填到 /v1 为止 |
| Completion mode | 对话（Chat） | 现代模型都选对话模式 |
| 模型上下文长度 | 按模型实际能力填写 | 见下文说明 |
| 最大 token 上限 | 按模型输出上限填写 | 控制单次输出长度 |
| Function calling | 按模型能力选择 | Agent 需要工具调用时开启 |
| Vision 支持 | 按模型能力选择 | 需要识图时开启 |
部分版本还有「显示名称」「流式模式分隔符」等可选字段，没有特殊需求保持默认即可。
第三步：保存并验证
点击保存时 Dify 会用填写的凭证发一次测试请求。验证通过后，这个模型就会出现在所有应用的模型选择下拉框里。想加更多模型，重复上面的步骤，每个模型名各添加一次，Key 和 URL 填一样的即可。
Base URL 怎么填才对
这是接入失败的头号原因，规则和 Cursor 配置 完全一样：
| 填写内容 | 结果 |
|---|---|
| https://zivv.pro | 缺少 /v1，请求 404 |
| https://zivv.pro/v1/chat/completions | 路径被重复拼接，请求失败 |
| https://zivv.pro/v1 | 正确 |
上下文长度和最大 token 怎么填
这两个字段不会改变模型本身的能力，只影响 Dify 怎么用它：上下文长度决定 Dify 在拼接对话历史、知识库召回内容时的截断阈值；最大 token 上限决定节点里「最大输出」滑块的范围。
填写原则：按模型官方公布的上下文窗口和输出上限填，拿不准就保守一点。填得比实际大，长对话时可能直接报上下文超限；填得过小，Dify 会过早截断历史，模型「记不住」前面的内容。具体数值以模型广场和官方文档为准，不要凭印象填。
方式二：Anthropic 供应商插件
如果你希望 Claude 模型走原生 Anthropic 协议（例如需要原生的扩展思考参数），可以尝试 Anthropic 供应商。关键在于你的 Dify 版本里这个供应商是否提供「自定义 API 地址」之类的字段：
- 有该字段：API Key 填 Zivv 的 Key，API 地址填 https://zivv.pro（Anthropic 原生入口不带 /v1）
- 没有该字段：说明当前版本只能连官方地址，改用方式一，通过 OpenAI 兼容入口调用 Claude 模型即可
对大多数 Dify 场景（客服问答、工作流、RAG），方式一已经完全够用。不确定的时候优先用方式一，字段少、兼容性最好。
知识库 Embedding 怎么办
这是很多人忽略的一点：Dify 的知识库需要 Embedding 模型把文档向量化，部分配置还会用到 Rerank 模型。Zivv 目前不提供 Embeddings 接口，所以：
- LLM 模型（对话、推理、工作流节点）接 Zivv
- 知识库的 Embedding 和 Rerank 模型选择其他提供 Embeddings 的服务商，或者用自部署的开源向量模型
两者在 Dify 里是独立配置的，可以混用。在设置里的「系统模型设置」中分别指定默认推理模型和默认 Embedding 模型即可。添加 OpenAI-API-compatible 模型时，模型类型也请只选 LLM，不要用 Zivv 的 Key 去添加 Text Embedding 类型。
在应用里选模型
配置完成后，在聊天助手、Agent 或工作流的 LLM 节点中，从模型下拉框选择刚添加的模型。几条实用建议：
| 场景 | 建议模型 |
|---|---|
| 客服问答、FAQ 机器人 | gemini-3.5-flash 或 gpt-5.4 |
| 工作流中的分类、抽取节点 | 中档模型即可 |
| 复杂 Agent、多步推理 | claude-sonnet-5 或 gpt-5.5 |
| 高难度分析、长文写作 | claude-opus-4-8 |
工作流里不同节点可以用不同模型：意图分类用便宜模型，最终生成用强模型，是 Dify 降本最有效的方式。更系统的思路见 多模型路由策略。
常见报错排查
凭证校验失败 / 401。 Key 复制不完整、带了空格，或者 Key 已被停用。到控制台确认 Key 状态和余额，详细排查见 401 报错解决。
404 / model not found。 模型名和平台 id 不一致，或者这个模型不在 Key 所属分组。用 curl 调一次 /v1/models 核对，参考 模型不存在 404 排查。
上下文超限。 对话轮数多或知识库召回内容太多，超过了模型窗口。调小召回数量、开启对话历史截断，或者检查「上下文长度」字段是否填得比实际大。
Agent 不调用工具。 检查添加模型时是否开启了 Function calling 支持；没开启时 Dify 可能退回提示词方式模拟工具调用，效果差很多。
自托管请求超时。 先在 Dify 所在服务器上跑 curl。curl 也超时就是服务器出网问题；curl 正常而 Dify 超时，检查 Dify 容器的网络与代理配置。长输出任务也可能撞上 Dify 自身的超时设置，可以适当调大。
429 或偶发 5xx。 多为单模型高峰拥堵，可在工作流里给节点配置重试，或换一个模型。参考 429 报错处理。
团队使用建议
Dify 往往是团队共用的平台，多个应用、多个负责人。建议：
- 每个 Dify 实例或每个重要应用使用独立 Key，用量分开统计
- 通过 团队模式 给 Key 设置日 / 月 / 总额预算，避免某个工作流死循环把余额跑空
- 定期在用量页按 Key、按模型看消费，找出可以降档的节点
隐私方面，Zivv 不存储请求与响应内容，只记录 token 用量用于计费。
常见问题 FAQ
Q：Dify 里找不到 OpenAI-API-compatible 供应商怎么办？ A：插件化版本需要先到插件市场安装 OpenAI-API-compatible 插件，安装后才会出现在模型供应商列表中。较早版本则是内置的，直接在设置 → 模型供应商里找。
Q：Dify 的 API endpoint URL 要不要带 /v1？ A：要带。OpenAI-API-compatible 供应商填 https://zivv.pro/v1，不要只填域名，也不要补全到 /chat/completions。
Q：能用 Zivv 的 Key 做 Dify 知识库的 Embedding 吗？ A：不能，Zivv 目前不提供 Embeddings 接口。知识库的 Embedding 和 Rerank 请选择其他服务商，LLM 推理部分继续用 Zivv，两者可以混用。
Q：一个供应商能添加多个模型吗？ A：可以。在 OpenAI-API-compatible 下重复添加模型，每个模型名各一条，Key 和 URL 相同即可。
Q：Dify 云版和自托管版配置一样吗？ A：字段含义一样。自托管版额外要确认服务器能访问 zivv.pro，以及容器的代理和超时配置。
Q：在 Dify 里调用 Claude 是满血原版模型吗？ A：Zivv 转发到上游官方模型，按官方价格乘以分组倍率、按实际 token 计费。模型 id 和定价以 模型广场 为准。
写在最后
在 Dify 里接中转，本质就是一个 OpenAI-API-compatible 模型：URL 填 https://zivv.pro/v1，Key 填 sk- 开头的 Zivv Key，模型名照抄平台 id，上下文长度按实际填。知识库 Embedding 另选服务商，其余全部交给一个 Key。更多接口细节可查看 接口文档，现在就去 注册 Zivv，十分钟把 Dify 的模型供应商配好。