Dify 接入自定义 API 教程：模型供应商、Key 与工作流（2026）

Dify 把提示词编排、知识库、工作流和 Agent 放进同一个可视化界面。它本身不生产模型，能力来自你接入的供应商。国内团队常见的做法是自托管 Dify，再通过 OpenAI 兼容接口接入统一 API 网关，把 Key、模型和用量管理放在网关侧。

本文按部署、添加供应商、填参数、搭最小工作流、团队使用和安全加固的顺序讲。界面、插件和变量名称以当前版本官方文档为准；模型与价格以站内模型价格为准，价格可能调整。

说明：Dify 为其权利人的商标，本文仅作技术接入说明，与相关厂商无隶属关系。

一、云端还是自托管

Dify 提供云端服务和社区版自托管。云端省运维，适合快速验证；自托管的数据留在自己的服务器，适合对网络、数据和权限有要求的团队。

只做试用：云端更快，但要确认数据位置和网络可达性。
要接内网模型或自定义插件：自托管更灵活，但要自己负责升级、备份和 HTTPS。
团队长期使用：都要规划成员权限、Key 管理和预算。

二、Docker Compose 部署

推荐用 Docker Compose 跑社区版。当前文档的最低配置是 2 核 CPU、4 GiB 内存；macOS 的 Docker Desktop 虚拟机建议至少 8 GiB。Linux 需要 Docker 19.03 以上、Compose 2.24 以上。

克隆最新 release 标签的仓库，需要 git、curl 和 jq。
进入 dify/docker 目录，把 .env.example 复制为 .env。
执行 docker compose up -d 启动服务。
用 docker compose ps 检查状态，等待服务就绪。
打开 http://服务器地址/install 创建管理员，然后从根地址登录。

git clone --branch "$(curl -s https://api.github.com/repos/langgenius/dify/releases/latest | jq -r .tag_name)" https://github.com/langgenius/dify.git
cd dify/docker
cp .env.example .env
docker compose up -d
docker compose ps

默认通过 80 端口访问，初始化入口是 /install。容器数量随版本变化，不要照旧教程数；init_permissions 显示 Exited 通常是一次性任务，属正常现象。

配置写在 .env，它会覆盖 envs/ 下的同名变量。改完用 docker compose down 再 up -d。升级前读对应版本说明，对比 .env.example 的新增变量，不要直接沿用旧 compose 文件。

三、添加 OpenAI 兼容模型供应商

只有工作区所有者和管理员能管理模型供应商。入口通常是 Integrations 或设置里的 Model Provider，先装 OpenAI-API-compatible 插件，再点 Setup 填凭据。名称随版本调整，找不到时以当前文档为准。

添加模型的典型顺序是：

安装或启用 OpenAI 兼容插件。
填写 API Key 和自定义 Base URL。
保存，等待凭据校验通过。
添加模型并选择类型。
填写模型名、上下文长度和能力开关。
用测试入口或一个最小应用验证。

字段	怎么填	常见错误
Base URL	一般填到 `/v1`，例如 `https://ai.zhongshangqihang.com/v1`	多写 `/chat/completions`，返回 404
API Key	整串粘贴，不手动加 `Bearer`	空格、换行或引号污染，返回 401
模型名称	与 `/v1/models` 或模型价格页一致	大小写、日期后缀写错，报 model not found
模型类型	LLM、Embedding、Rerank、语音等按用途选	类型选错，应用里看不到该模型
上下文长度	按服务商实际支持值填，留出余量	填理论上限，长请求被上游拒绝
能力开关	流式、函数调用、视觉按实际支持打开	Agent 调工具失败、图片上传被拒

同一供应商下可添加多个模型，逐个配置。命名建议带用途或版本。Embedding 模型用于知识库后维度就固定了，换模型通常要重建索引。

四、先 curl 预检，再回 Dify 测试

填完直接测试，失败时难分网关、网络还是字段问题。先用 curl 验证上游：

export ZSQH_API_KEY="sk-你的密钥"

curl -sS "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"你的模型ID","messages":[{"role":"user","content":"只回复 OK"}]}' \
  -w "\nHTTP %{http_code}\n"

返回 choices 说明 Key、地址和模型名有效。401 查 Key，404 查路径，model not found 查模型名。Base URL 填到 /v1，不要填完整接口路径；Key 不要手动加 Bearer，Dify 会自己加。

Dify 保存供应商时会校验凭据，但通过校验不等于每个模型都能用，还要确认类型、上下文长度和能力开关。没有测试按钮时，可建一个最简单的聊天应用，或调用应用 API 验证。

五、搭一个最小工作流

先用最小链路跑通，再逐步加节点。以工作流为例：

在 Studio 新建 Workflow 或 Chatflow：对话型选 Chatflow，批处理或自动化选 Workflow。
在开始节点定义一个输入变量，例如 query。
添加 LLM 节点，选择刚接入的供应商和模型，在提示词里引用开始节点的变量。
添加结束节点，把 LLM 的输出接到输出变量。
用测试运行输入真实问题，逐节点查看输入、输出和 token 用量。
确认无误后发布，再通过嵌入页面或应用 API 调用。

需要检索时，在 LLM 前加知识检索节点，并先在工作区设置里配置 Embedding 和 Rerank 模型。需要分支时加问题分类或条件分支。Agent 节点适合调用工具的场景，但要选支持函数调用的模型，先单独验证工具调用，再接进主流程。

每个 LLM 和 Agent 节点都可单独选模型；未指定的节点回退到工作区默认模型。简单分类、改写用小模型，最终生成用强模型。关键节点建议显式绑定，避免默认模型变更后行为漂移。

六、团队使用：成员、Key 与环境

工作区成员通常分为所有者、管理员、编辑者和普通成员，权限以版本和套餐为准。供应商凭据属于整个工作区，不是个人配置，要限制管理员数量。

开发和生产用不同的供应商凭据或 Key，便于限额和吊销。
每个应用单独生成 API Key；应用 Key 只作用于该应用，但覆盖该应用的所有终端用户。
调用方用 user 参数区分最终用户，不要把应用 Key 写进前端或客户端。
Dify Cloud 的服务 API 根地址是 https://api.dify.ai/v1；自托管用你自己的域名加 /v1。
请求头使用 Authorization: Bearer <key>，只在后端调用。

多人编辑时，建议先约定命名、变量和发布流程，否则工作流很快会难以维护。对外应用还要约定版本发布和回滚方式，不要在生产应用上直接改提示词。

七、安全与运维清单

上 HTTPS，不要直接暴露 80 端口；反向代理同时处理证书和访问控制。
初始化后限制 /install，使用强密码，并开启可用的二次验证。
密钥只放在 .env 或密钥管理服务里，不提交到代码仓库；成员变动时轮换。
防火墙只开必要端口，数据库和向量库不要暴露到公网。
自托管的 SSRF 代理和网络出口按当前文档配置，改网络前先读 .env 说明。
定期备份 PostgreSQL、上传文件和 .env，并做恢复演练。
升级前备份，固定 release 标签，按对应版本说明操作。
在网关侧设置预算、并发和告警，避免循环调用消耗额度。
代码节点只运行自己审查过的代码，不要把它当成通用安全边界。

安全不是一次配置，而是升级、成员变动和 Key 轮换时都要复查的流程。

八、常见报错速查

401 Unauthorized：Key 错误或带多余字符；重新粘贴，确认用的是该供应商的 Key。
404 或 model_not_found：Base URL 路径不对，或模型名不一致；核对 /v1 和模型标识。
请求超时：Dify 访问不到上游，或上游响应慢；检查 DNS、防火墙、代理和 SSRF 配置。
供应商装不上：插件市场不可达或版本不兼容；检查网络与当前文档。
应用里选不到模型：类型选错，或节点未绑定；检查供应商模型列表和节点配置。
知识库检索异常：Embedding 维度不一致或索引未建好；换模型或重建索引。

常见问题

Dify 自托管最低配置是多少？

当前文档给的是 2 核 CPU、4 GiB 内存；macOS 的 Docker Desktop 虚拟机建议至少 8 GiB。实际还要看并发和知识库规模，生产环境留余量。

Dify Cloud 和自托管怎么选？

想快速验证、不想运维，选云端；要求数据留在自己服务器、接内网服务或自定义插件，选自托管。两者都能接 OpenAI 兼容模型，差别在运维责任和网络边界。

供应商添加成功，应用里却选不到模型？

先看模型类型是否选对，例如把 Embedding 当成 LLM；再看模型是否已添加到该供应商下，以及应用或节点是否绑定。部分节点只接受特定能力的模型。

工作流里每个节点都要单独选模型吗？

可以单独选，也可以用工作区默认模型。多节点流程建议按任务分工：分类和抽取用小模型，最终生成用强模型；关键节点显式绑定，避免默认模型变更后漂移。

团队共用一把 API Key 可以吗？

可以但不建议。共用 Key 无法区分调用方，泄露后影响面大，也不方便限额。按应用或环境分别发 Key，用 user 参数区分最终用户，并定期轮换。

下一步

Dify 接入可以拆成四步：先跑起实例，再用 curl 验证上游，然后按真实能力填模型参数，最后用最小工作流验证节点绑定。需要统一的 OpenAI 兼容入口和用量管理，可以注册中商起航 AI 网关；模型与计费方式以模型价格页为准。