Dify模型供应商配置全攻略：从初始化到接入第一个模型

很多人后台私信问得最多的一句就是：我把 Dify 装起来了，界面也打开了，管理员账号都建好了，为什么新建应用一运行，日志里就提示没有可用的模型？这不是程序出了问题，而是你还没给 Dify 注入“灵魂”。

Dify 本身是一个应用编排平台，数据库、队列、前端、API 各角色各司其职，但它本身不产生任何智能。真正让它“开口说话”的，是大模型。所以初始化完成之后，第一件正经事就是做模型供应商配置。只有把模型接进来，工作流里的 LLM 节点才有推理能力，Agent 才有调度依据，知识库的向量化检索也才跑得起来。

这篇博客主要面向已经装好 Dify、准备正式接入模型做应用的开发者。不需要你有很深的算法背景，只要你会看界面、能填 API Key，就能跟着走完整个流程。我会从“初始化到底做了什么”开始讲，再到模型供应商配置的底层逻辑，最后把实际接入的步骤和踩过的坑一起整理出来。这套内容同样适合负责 Dify 环境运维的同学参考。

1. 初始化不是点两下就完事：先想清楚这一步的价值

很多教程会把 Dify 初始化一笔带过，好像数据库迁移完、浏览器里填个管理员邮箱密码就算结束了。我的看法是，初始化这步值得认真对待，因为它决定了后续整个平台的基础运行状态，尤其是权限体系和系统参数，后面想改要费不少劲。

1.1 初始化到底做了什么

Dify 部署完成以后，数据库是空的。初始化做的事情，就是往空数据库里写入一套运行所需的基础数据：

• 创建超级管理员账号
• 写入系统默认配置（平台名称、登录方式、用户注册开关等）
• 建立初始租户环境，后续创建的应用、知识库、成员都在这个租户下
• 初始化消息队列、任务表、模型供应商相关的元数据表

可以把它理解成新房交付后第一次通水通电。房子骨架是 Docker Compose 拉起来的，但里面能不能住人，取决于这些基础设置是否到位。

这个环节最容易出问题的点，是数据库迁移。容器第一次启动时，Dify 的 API 服务会自动执行数据库迁移脚本，如果数据库版本不兼容、磁盘权限异常，或者 PostgreSQL 连接串配置错了，迁移就会中断。表面上看容器还在运行，但实际上数据库里根本没有管理员表，你打开浏览器永远停在引导页，或者提示数据库错误。

所以初始化不是“点两下”就完事，更多是确认底层基础设施是否健康。我在排查问题时，第一件事就是看 API 容器日志，确认没有迁移报错，再谈后续配置。

1.2 源码部署、Docker 部署和本地开发，初始化路径其实不一样

不同部署方式，初始化的入口和细节是有差异的，这里分三种情况说：

第一种是 Docker Compose 部署，这也是大多数人用的方式。启动容器后，用浏览器访问http://服务器IP，第一次进入会自动跳到管理员设置引导页。填完邮箱和密码，点击下一步，数据库写入完成后，就能进入工作台。整个过程比较顺滑，没有什么额外命令要执行。

第二种是源码部署。你需要自己准备 Python 环境和前端构建工具，自行执行依赖安装、数据库迁移命令，然后用 CLI 或引导路由创建管理员账号。相比 Docker 部署，源码方式对环境的侵入性更强，初始化环节也更依赖操作者对项目结构的了解。如果只是普通使用，完全没必要走这条路。

第三种是本地开发模式。为了调试方便，Dify 支持通过环境变量预设部分初始化参数，比如跳过某些引导步骤。这种方式适合自动化测试、持续集成场景，不适合生产环境，因为会把敏感信息直接写进环境配置里。

无论哪种方式，我都要强调一个通用的建议：生产环境不要用 SQLite。Dify 官方 Docker 配置默认支持 PostgreSQL，请务必保持这个配置。SQLite 看起来轻巧，一旦多用户并发写入，锁冲突问题就来了，后续想迁移数据也麻烦。

1.3 环境变量预置管理员，适合自动部署

Dify 支持在启动时通过环境变量设置管理员密码等参数。这个机制对自动化部署非常友好，比如你要在内部团队快速拉起一套演示环境，不希望人工去点引导页，直接配置好环境变量再启动容器，管理员账号会自动建好。

我自己的实践经验是，这种做法适合一次性环境，比如培训、Demo、临时测试集群。长期使用的环境还是建议手动走一遍引导页。因为自动创建的账号，密码复杂度、邮箱收件能力都不一定符合要求，万一忘记配置的是哪个地址，后面找回密码会很尴尬。

还有一个容易忽略的点：初始化管理员账号时填的邮箱，最好是一个真实可用的邮箱。因为这个邮箱牵扯到后续的密码找回、成员邀请、操作通知。如果随便填了一个假邮箱，后面系统发不了邮件，你又不想配置 SMTP，那就只能去数据库里手动改密码，纯属给自己挖坑。

2. 模型供应商配置的底层逻辑：我们到底在配什么

模型供应商说起来很简单，就是让 Dify 知道去哪儿调用哪个模型。但实际配置的时候，很多人会纠结选哪个平台、填什么 Key、模型名怎么拼。这一章我把底层逻辑拆开讲一下，搞清楚之后再操作，思路就顺了。

2.1 没有模型，Dify 只是空壳

Dify 的核心价值是编排。你可以把提示词、上下文、工具调用、知识库检索这些环节，在画布上像搭积木一样串起来。但每一个环节真正执行的时候，比如让 LLM 节点生成一段回答，底层调用的还是外部的大模型接口。

可以拿点外卖来类比。Dify 是那个外卖平台，界面、订单流程、配送调度都是它负责，但真正炒菜的，是后厨里的那些大模型。平台可以把订单管理得井井有条，但如果后厨没开火，你永远等不到餐。

这也是为什么模型配置被称为“注入灵魂”。没有配置模型供应商，你在应用里写再多提示词，工作流编排得再复杂，一运行就报错。这属于起点问题，绕不过去。

2.2 远程 API 与本地模型，两条路线怎么选

Dify 里能接的模型供应商，大体分成两类：远程商用 API 和本地私有化模型。

远程商用 API 包括大家熟知的 OpenAI、Anthropic，也包括国内的一些模型服务商，比如 DeepSeek、智谱、通义千问等。它们的优点是开箱即用，模型推理能力强，不用自己准备显卡，按 token 付费就行。缺点是数据会经过第三方服务，对数据敏感的业务要慎重评估。

本地私有化模型走的是 Ollama、Xinference、vLLM 这类工具，把开源模型部署在自己服务器上。优点是数据不出内网，推理成本长期看可能更可控，离线也能用。缺点是你需要一台带 GPU 的机器，而且开源模型的效果调优、并发承载能力，都需要投入不少精力。

给你一张对比表，方便做选型判断：

从我的经验看，大多数团队的起步方案都是远程商用 API。先把应用跑通，验证业务逻辑，等真的到了数据合规或成本瓶颈期，再考虑迁移本地模型。这属于典型的低成本试错。

2.3 上下文长度、价格、并发和延迟，选型到底比什么

接哪个供应商、选哪个模型，很多人只看模型名字大不大。实际上，做技术选型时更值得关注的是四个维度：

• 上下文长度：模型一次性能处理多少 token。8K、32K、128K，直接决定你的应用能不能吞下一整份长文档。做文档问答，上下文长度不够就是硬伤。
• 价格：不同模型的输入输出价格差异很大。贵的模型效果好，但跑一天企业级应用，成本可能吓你一跳。省钱的办法是把简单任务交给便宜的小模型。
• 推理能力和响应质量：代码生成、复杂逻辑推理，必须用强模型；意图分类、关键词抽取，小模型足够。
• 并发和延迟：商用 API 通常有并发限制，超过限额会被限流。本地模型则要看 GPU 算力能扛住多大的并发，否则用户一多，响应时间直接起飞。

我见过不少团队在选型时只看模型推理能力，忽略价格，结果月底账单出来才大吃一惊。这里的原则是：按任务难度匹配模型大小。主对话用强模型，副任务用弱模型，能省一大笔钱，效果也不会差。

另外要特别注意模型标识符。OpenAI 的不同版本、DeepSeek 的 chat/reasoner 系列，模型名是完全不同的。配置的时候填错一个字母，系统就会告诉你模型不存在。真实项目里，这类问题占了模型配置报错的一半以上。

3. 手把手实操：完成初始化并接上你的第一个模型

前面聊了不少思路，这一章进入正题。我会从首次打开 Dify 开始，一步一步演示初始化和管理员创建，然后带你完成远程 API 和本地模型的接入，最后设置默认模型。全程按照我实际操作过的方式来写，遇到坑也会同步标注。

3.1 首次打开 Dify：创建管理员账号的完整步骤

假设你已经通过 Docker Compose 把整个 Dify 服务拉起来了。在浏览器里输入服务器地址，正常情况下会自动打开一个引导页面，要求设置管理员账号。

操作步骤其实很简单：

1. 输入管理员邮箱。
2. 输入密码，建议至少 12 位，包含大小写字母、数字和符号。
3. 确认密码后，点击创建管理员账号。
4. 系统初始化完成后，自动进入 Dify 工作台。

这一步有几个细节值得说明。邮箱一定要填真实可用的地址，原因前面说过，不再重复。密码最好不要用团队名称、公司简称这类容易猜的组合，因为管理员账号权限是整个平台最高的，影响所有应用和知识库的访问权限。

如果初始化完成后，你想修改平台显示名称，可以进入右上角头像菜单里的“设置”，在通用设置里调整。这些操作不需要重新初始化，运行时就能改。

需要提醒的是，管理员账号创建之后，不要轻易删除或更换。后续所有成员、应用、数据模型的归属关系都挂在它的租户下，删了容易引发连锁问题。多成员协作的需求，正确的做法是进入“成员管理”邀请新用户，而不是把超级管理员账号共享给所有人。

3.2 找到模型供应商配置页：界面和字段先认清

登录工作台之后，左侧菜单栏往下翻，找到“设置”，点进去就能看到“模型供应商”页面。

页面上是一排供应商卡片。不同的供应商状态不一样：

• 已经配置过的，卡片上会显示绿色对勾
• 没配置的，显示“未配置”或“立即配置”
• 配置失败、Key 失效的，会有红色感叹号

点击任意一个供应商卡片，会进入它的配置详情页。通常需要填写的字段包括：

• API Key
• Base URL（部分平台需要，部分平台固定）
• 模型列表（本地模型平台一般是手动填写或自动拉取）
• 额外参数（比如某些供应商要求填写organization、region等）

填完后，页面一般会有一个“测试连接”按钮。我的习惯是先测再保存，这样可以快速发现 Key 错误、网络不可达、接口地址不匹配等问题。直接保存，然后跑到应用里测试，排查路径就绕远了。

3.3 接入远程模型：OpenAI 与 DeepSeek 配置示例

远程模型配置的套路是通用的，我先以 OpenAI 为例讲一遍。

进入 OpenAI 供应商页面后，把 API Key 粘贴到对应字段，点击“保存”。如果网络畅通、Key 有效，页面会显示连接成功，并自动拉取当前可用模型列表，比如 gpt-4o、gpt-4o-mini 等。

这里有一个很重要的建议：如果你所在的网络环境访问境外接口不稳定，不要硬折腾。商用 API 讲究稳定，三天两头超时，工作流跑一半就失败，生产环境根本没法用。建议直接选择国内模型服务商，比如 DeepSeek、智谱、通义千问，或者企业自己采购的合规模型通道。

就以 DeepSeek 为例，配置过程也类似。在模型供应商页面找到 DeepSeek，填入 API Key，默认 Base URL 一般不需要改。保存后模型列表里会出现 deepseek-chat、deepseek-reasoner 等标识符。挑一个适合当前应用场景的即可。

智谱这边同样是填 Key 的方式，模型标识符可能是 glm-4-flash、glm-4-plus 等，不同版本在免费额度和计算速度上差别很大，调试阶段可以先挑免费的试手。

配置完任何一个供应商，回到“模型供应商”页面，确认对应卡片已经变成“已配置”状态。多个供应商都配好之后，不同应用、不同工作流节点，就可以按需选择各自合适的模型了。

3.4 接入本地模型：把 Ollama 挂到 Dify 下面

如果你想把 Dify 接到本地私有化模型，最常见的方式是用 Ollama。这一节我重点讲一下，因为很多人在这一步卡住过，其实逻辑不复杂，就是“地址通不通”的问题。

首先，在部署了 Ollama 的机器上拉取模型，比如：

ollama pull qwen2.5:7b

然后在 Dify 模型供应商页面，点击 Ollama 卡片，进入配置：

• 模型供应商名称：Dify 默认会给一个，也可以自定义
• Base URL：这里必须填 Dify API 容器能够访问到 Ollama 的地址
• 模型列表：填写你已经拉取的模型名，比如qwen2.5:7b

接下来是重点。在 Docker Compose 部署场景下，Dify 的 API 是跑在容器里的，它访问 Ollama 时的地址不能写localhost，因为 localhost 指向的是 API 容器自己。如果 Ollama 部署在宿主机上，常见写法是http://宿主机IP:11434；如果你用的是 Docker Desktop 环境，可以尝试http://host.docker.internal:11434。

这种地址问题，属于容器网络的基础知识，但第一次接触的人真的很容易懵。我见过有人把http://localhost:11434配进去，点了无数次测试连接都不成功，后来换成宿主机 IP 就好。

最后测试连接，成功的状态下，Dify 就能调用本地模型了。这种模式下，数据完全留在你的服务器上，模型调用没有 token 费用，适合数据敏感业务和长期成本控制。

3.5 配置默认模型：让系统知道该调用谁

接好了模型供应商，最后一步是告诉 Dify，系统默认情况下该把任务交给哪个模型。

入口在“设置”里的“模型”页面。这里可以分别设置：

• 系统推理模型：聊天助手、应用默认使用的模型
• Embedding 模型：知识库做向量检索时用来生成向量
• Rerank 模型：做重排序用，可选

系统推理模型的选择，会直接影响工作台右侧调试对话的体验。建议选一个能力均衡、价格适中的模型作为默认值，保证大多数场景下不会出错。

工作流里的 LLM 节点，也可以单独指定模型。这个设计非常实用，比如知识库问答的主流程用强模型，但摘要提取这一步用轻量模型就够。通过这种方式，你可以把成本摊薄，同时不影响整体效果。

另外，Embedding 模型不需要选择与推理模型同款。只要供应商能提供，knowledge base 建索引时会自动调用这个模型完成向量化操作。

4. 实战中的坑：初始化与模型配置最常见问题

这一章我专门记录自己和其他同行在 Dify 初始化与模型配置过程中遇到最多的几类问题。很多问题现象看起来吓人，实际排查起来并不复杂，掌握思路之后完全可以自己解决。

4.1 引导页不出现：先查容器日志

现象：Dify 服务已经启动，浏览器却一直停在登录页或者提示数据库错误，管理员引导页出不来。

排查思路：

1. 确认容器全部启动成功。用docker compose ps查看状态，看是否有容器反复重启。
2. 查看 API 容器日志。如果初始化管理员信息写入失败，会有明确报错。定位关键信息可以用：

docker compose logs api --tail 200

3. 检查数据库迁移是否完成。如果 PostgreSQL 连接有问题，API 容器可能是 Running 状态，但实际不可用。

还有一种情况，是你之前已经初始化过，再次打开不会重复引导，这是正常现象。如果确实忘记管理员密码，不要试图绕过引导页，正确做法是进入 PostgreSQL 库重置管理员账号密码，或者在部署环境里手动执行 Dify 提供的密码重置流程。

如果是自动部署环境，通过环境变量预置过管理员账号，也会跳过人工引导页。所以出现“引导页不出现”时，先回忆一下当初部署有没有配过这类变量。

4.2 供应商一直红色感叹号：测试连接与状态码分析

现象：模型供应商卡片一直显示红色感叹号，点击测试连接失败。

这种问题通常分为两类，一类是 Key 无效，一类是网络不通。

先看状态码：

• 401：鉴权失败，API Key 不正确或已被删除
• 403：没有权限，可能 Key 被限权
• 429：触发限流，稍等片刻再试
• 超时：网络不通或接口地址填错

确认 Key 是否正确，建议直接去模型平台的密钥管理页面核验。也可以直接在部署机器上用 curl 验证，比如对 OpenAI 格式的接口发起一次最简单的对话请求，观察响应码。这一步能快速区分问题到底出在 Dify 配置，还是出在模型服务方。

我自己常用的命令格式类似：

curl -X POST https://example-llm-api.example.com/v1/chat/completions \ -H "Authorization: Bearer 你的KEY" \ -H "Content-Type: application/json" \ -d '{"model":"模型标识符","messages":[{"role":"user","content":"hi"}]}'

看到正常 JSON 返回，说明 Key 和网络都没问题。如果返回鉴权错误，那就是 Key 的问题。如果请求直接卡死，那就要检查网络和接口地址。

4.3 应用运行时报“模型不可用”

现象：模型供应商已经配置成功，但真正运行应用时，提示类似模型不存在、当前模型不可用。

这种问题最典型的根源是：你在应用里手动指定了一个模型标识符，但该模型并没有在模型供应商配置里启用或同步过来。

比如你在工作流 LLM 节点里填了一个模型名，但供应商页面里的模型列表没有这个标识符，Dify 自然无法用。解决办法很简单，回到模型供应商配置页，确认该模型已出现在可用列表中，并确保应用所在环境中使用的是配置后的模型名。

另外，部分模型供应商同一个 Key 有不同的访问区域，区域选择不对也会导致模型不可用。检查配置里的 region 或部署参数，换成和 Key 一致的区域。

这类排查过程，多利用“测试连接”功能，每次修改字段后都主动测一次。运行时报错的概率会少很多。

4.4 数据集索引失败：Embedding 模型的那点事

现象：创建知识库、上传文档后，索引状态一直卡在“处理中”或直接失败。

大部分原因是 Embedding 模型没有正确配置。知识库的向量检索模式，需要先把文档内容通过 Embedding 模型转成向量，没有可用的 Embedding 模型，索引步骤根本走不下去。

排查方式：

1. 去“设置 -> 模型”页面确认 Embedding 模型是否已设置。
2. 确认该模型供应商的 Key 额度还有余量，部分平台对新建密钥的免费额度很有限，跑几个文档就用完了。
3. 如果数据集同时支持全文检索，你可以临时切换索引方式验证问题，但生产环境建议还是把向量检索和 Embedding 模型配好。

补充一点：Rerank 模型是可选的，它负责在向量检索出候选结果后进一步排序，对检索精度有提升，但并不是索引成功的必要条件。第一次部署时可以暂时不配，先把主链路跑通再说。

5. 我的个人经验和后续扩展建议

几套环境搭建下来，有一些零零碎碎的心得，趁这个机会整理出来，不一定适合所有人，但至少能帮新人少走一点弯路。

5.1 配好模型前的三件事

第一件事，建一张模型配置清单。把供应商名称、API Key、模型标识符、用途、费用上限、联系人，都记在同一张表里。团队协作时，这张表就是“模型资产台账”。

第二件事，千万别在多个环境共用同一个 API Key。开发、测试、生产分开配，哪怕都是同一个供应商，也建议创建多个 Key。这样出现额度超限、数据异常时，才能从 Key 上定位到具体环境。

第三件事，生产环境的系统推理模型和调试模型的区分。工作台临时调试对话建议用便宜小模型，正式上线的应用再绑定稳定的主模型。别把调试会话的消耗算进主要你的生产成本里，这个坑踩过的人不在少数。

5.2 生产环境要多想想“备用方案”

模型供应商也会出状况。接口升级、区域故障、配额耗尽，任何一环抖动，都会影响到 Dify 上跑着的所有应用。

所以生产环境中，模型供应商配置不宜只依赖一家。比较务实的做法是：主模型用一个高性能供应商，备用模型用另一个不同服务商的同等级模型。当主链路出现问题时，把应用或工作流节点的默认模型切换到备用模型，能缩短故障时间。

这个备用策略不是 Dify 自动完成的，需要你提前在基础设施层面留好切换路径。最简单的就是在模型供应商配置里同时维护好两套 Key 和模型列表，切换的时候只需要改掉相应的模型选择。

5.3 再往后可以玩什么

模型供应商配置完成后，Dify 这门手艺才算是入了门。接下来可以尝试的方向就比较多了。

比如构建知识库，把内部文档、产品手册导入进去，配合 Embedding 模型做向量检索，实现私有知识的问答。比如做 Agent 应用，让模型自动决定调用哪些工具、按什么顺序执行步骤。比如把 Dify 应用通过 API 提供给外部系统调用，做成一个独立的 AI 服务。

从我个人体会来说，Dify 这类平台最大的价值，是让团队不用从零造轮子，把精力放在业务逻辑上。而模型供应商配置，是这一切开始前最基础的一道工序。把这步理顺了，后面不管是工作流编排、Agent 设计，还是知识库构建，都会顺畅很多。