Dify模型API配置指南

Dify模型API怎么配置自定义供应商、模型添加与常见报错Dify 是一个开源的 LLM 应用开发平台支持通过可视化工作流编排 AI 应用。它内置了 OpenAI、Anthropic、Google 等主流模型供应商同时也支持接入自定义的 OpenAI 兼容 API。很多团队用 Dify 做内部 AI 工具需要接入自己的 API 服务或第三方兼容平台。这篇把配置流程、常见坑和验证方法讲清楚。配置入口登录 Dify 后点击右上角头像进入设置Settings→ 模型供应商Model Providers。这个页面列出了所有已安装和可安装的模型供应商。安装 OpenAI 兼容供应商插件Dify 的模型供应商以插件形式管理。要接入自定义的 OpenAI 兼容 API需要先安装OpenAI-API-compatible插件。在模型供应商页面找到安装模型供应商区域搜索OpenAI-API-compatible或访问 Dify Marketplace点击安装安装完成后在供应商列表里会多出一个OpenAI-API-compatible卡片。配置自定义供应商点击OpenAI-API-compatible卡片上的设置填写以下信息配置项说明示例Endpoint URLAPI 服务地址https://your-provider.com/v1API Key你的 API 密钥sk-xxxxxModel Name模型名称gpt-4o配置步骤点击供应商卡片上的设置填写 Endpoint URL注意以/v1结尾粘贴 API Key点击保存Dify 会先验证凭据验证通过后该供应商就可以使用了。添加自定义模型大多数供应商自带模型列表授权后即可使用。但如果你运行着自己的推理服务器如 Ollama、vLLM或者供应商的模型列表里没有你需要的模型需要手动添加。在供应商卡片上点击添加模型填写配置项说明模型名称模型 ID必须和服务端一致模型类型Chat / Completion / Embedding 等上下文长度模型支持的最大上下文 Token 数最大输出 Token单次最大输出 Token 数如果添加的自定义模型名称和类型与已有模型完全相同Dify 会提示冲突。Base URL 的注意事项Endpoint URL 的格式和前面几篇文章提到的一样最容易出错# 正确以 /v1 结尾https://your-provider.com/v1# 错误多了尾部斜杠https://your-provider.com/v1/# 错误少了 /v1https://your-provider.com# 错误写了完整接口路径https://your-provider.com/v1/chat/completions常见报错与排查凭据验证失败原因API Key 无效、Endpoint URL 写错了或网络无法到达目标地址。排查方法用curl测试 Endpoint URL 是否可达确认 API Key 前后没有空格确认 Endpoint URL 以/v1结尾模型列表为空原因供应商的/models接口返回格式不标准或者接口不可用。解决方法手动添加模型名称和类型。调用时报错 404原因模型名称不存在或 Endpoint URL 路径错误。排查方法确认模型名称和服务端一致检查 Endpoint URL 格式工具调用不工作原因自定义供应商可能不支持 Function Calling或者返回格式和 Dify 预期不一致。排查方法确认供应商明确支持 OpenAI 兼容的 Function Calling检查供应商文档是否有特殊配置要求流式输出中断原因网络不稳定或者 Dify 服务器和 API 服务之间的连接超时。排查方法检查网络环境如果 Dify 通过反向代理部署确认proxy_read_timeout足够长和 LiteLLM 的搭配使用如果你的团队已经部署了 LiteLLM 网关Dify 可以直接对接 LiteLLM这样所有模型调用都经过网关享受统一的成本追踪和权限控制。配置方式配置项值Endpoint URLhttp://your-litellm-server:4000/v1API KeyLiteLLM 虚拟 KeyModel NameLiteLLM 配置的模型名这样 Dify 里的所有模型调用都会经过 LiteLLM日志和费用都记录在网关里。快速排错表报错常见原因排查方法凭据验证失败API Key 无效或 Endpoint URL 错误用 curl 测试 Endpoint URL模型列表为空/models接口不可用手动添加模型404模型名称不存在确认模型 ID 和服务端一致工具调用失败供应商不支持 Function Calling确认供应商文档流式中断网络不稳定或代理超时检查网络和代理配置配置检查清单检查项怎么确认插件已安装模型供应商列表中有 OpenAI-API-compatibleEndpoint URL 格式正确以/v1结尾无尾部斜杠API Key 有效凭据验证通过模型可见应用编排时能选择该供应商的模型工具调用正常工作流中工具节点能正常返回Dify 接入自定义 API 的核心就三步装插件、填 Endpoint URL 和 API Key、确认模型可用。大部分问题都出在这三个环节上对着检查清单过一遍基本都能解决。