做 Dify 部署，跑到初始化这一步，很多人就卡住了。Docker Compose 拉起来确实不难，真正让人犯迷糊的是首次打开浏览器看到那个初始化向导：管理员账号、模型供应商、系统默认设置，一样接一样，像在给你出题。尤其是模型供应商配置，你明明从某个大模型平台申请了密钥，填进去却怎么都调不通，最后应用连建都建不起来。这篇文章就把 Dify 初始化到模型供应商配置这一段路完整走一遍，讲清楚每一步为什么这么设计，以及你大概率会踩的那些坑。适合刚把 Dify 服务装起来、正准备进入控制台正式配置的新手，也适合那些想理解供应商体系到底是怎么回事的读者。

1. 初始化前的准备：想清楚这三点再点开浏览器

1.1 部署方式决定你从哪个入口进入

很多人以为初始化就是打开浏览器填个账号，结果第一步就卡在"我该访问哪个地址"。这跟你的部署方式强相关，不同方式对应的入口差异很明显。

如果你是用 Docker Compose 方式部署的，并且没有修改默认端口，那服务起来之后直接访问服务器的 80 端口，浏览器会自动跳到初始化页面。本地开发机就直接打开http://localhost，部署在远程服务器上就打开http://服务器IP，当然前提是你没在访问路径上套一层反向代理。

这里有个很多人没注意的细节：如果你之前改过.env文件里的EXPOSE_NGINX_PORT，那入口端口也跟着变了，访问地址要带上对应端口。还有一部分人用源码方式跑的，那入口往往是http://localhost:3000这种开发端口，和 Docker 部署的默认入口完全不同。我见过不止一位朋友用 Docker 部署，却习惯性打开 3000 端口，看到一个空白页或者报错页，就以为部署失败了，其实服务好端端跑着，只是走错了门。

建议在浏览器敲回车之前，先登录服务器执行一下docker ps，确认容器状态是 healthy，同时看清楚端口映射关系。这个动作只需要十秒钟，但能帮你把"部署问题"和"初始化问题"清晰切开，后面排查起来思路会顺很多。

1.2 管理员账号和密钥材料的准备

初始化向导的第一步是创建管理员账号，这个账号拥有平台的最高权限，后续所有成员管理、模型供应商配置、系统设置都依赖这个身份。你需要的材料很简单：一个你能正常收信的邮箱，以及一个足够强度的密码。

我知道很多人在本地环境这步就是随便填，比如admin@example.com加一个12345678。本地实验这样玩没问题，但如果你的 Dify 要拿来跑真实项目、给团队用，我建议认真对待。管理员邮箱是密码找回和登录身份的唯一凭证，一旦找不回来，你只能去数据库里硬改，那滋味不值得体验。密码至少要做到字母、数字、特殊字符混合，长度别低于十位。

密钥材料也要提前备好。模型供应商配置阶段需要你去对应的大模型服务商平台申请 API Key，这个动作要提前做，别等到配置的时候才去注册、实名、开权限。有些服务商的密钥申请审核要等一段时间，尤其是企业级权限和更高额度的配额，提前准备能让你在初始化阶段一气呵成，而不是填到一半卡在"等审批"。

1.3 从服务器到模型API的网络链路，先确认通不通

这是一个常被忽略、却最容易导致"测试连接失败"的隐性因素。你的 Dify 服务跑在哪台机器上，那台机器到模型 API 的网络是否通畅，直接决定了密钥能不能校验通过。

我建议在配置模型供应商之前，先在 Dify 所在的服务器上手动测试一下目标 API 域名的连通性。比如执行一个简单的curl -I https://目标API域名看返回状态，或者用ping配合traceroute观察网络路径。这一步能帮你提前暴露两类问题：一是目标 API 在你的网络环境下不可达，二是链路上存在 DNS 解析异常或者代理干扰。

尤其是服务器部署在境内、模型 API 部署在境外的情况，网络问题几乎是每天都会遇到的。解决方案也很直白：选择网络链路稳定、你在当前部署环境直连通畅的服务商；或者干脆换成本地推理方案；必要的时候在部署层面做区域选择。说白了，Dify 本身不产生模型能力，它只是模型的调度者和编排者，模型 API 不通，界面配置做得再漂亮也白搭。

2. 初始化向导实际会问你什么，以及为什么这么问

2.1 创建管理员账号这一步别跳过

部署完成后的首次访问，Dify 会进入一个专门的初始化流程。第一个环节就是创建管理员账号，要求填写邮箱、密码、确认密码。有些版本还会让你顺便设置团队名称之类的信息，团队名称后面可以改，账号信息才是关键。

这一步提交之后，Dify 会初始化数据库基础结构，写入管理员身份，然后引导你进入下一步。整个过程通常十几秒完成，如果长时间没有反应，建议先检查数据库容器是否正常运行，因为初始化动作依赖数据库写入，数据库起不来流程就会一直转圈。

忘记密码是后续最常遇到的事。Dify 的管理员密码重置不像普通应用那样点个"忘记密码"就能解决，你需要在服务器上操作数据库或者借助其他管理手段。所以在这个环节给自己留一个能记住的、强度合适的密码，比依赖"找回密码"功能靠谱得多。

2.2 模型供应商的"现在配"和"稍后配"怎么选

管理员账号创建完成后，初始化向导会进入模型供应商推荐环节，界面通常展示一组可配置的大模型服务商列表，你可以点击任意服务商进去填密钥。这个环节有一个明显的"跳过"选项，允许你先进入主界面，之后再补配。

那到底是现在就配还是跳过？我的建议是：如果你已经拿到了 API Key，而且服务商的网络可达性也验证过，那现在就配掉，一步到位，省得进了主界面还要再找菜单。如果你根本还没有密钥材料，或者对选哪家服务商还没想清楚，果断跳过，先进主界面逛一圈，看看总览、导航、应用创建流程长什么样，再回头补配也不迟。不要把初始化当成一次必须全部答对的考试，Dify 在这块设计得很宽容，绝大部分配置都支持事后调整。

从我的经验看，跳过并不丢人。恰恰相反，先完成账号初始化，再慢慢研究模型供应商配置，压力更小，你也能在完全理解界面结构之后再动手。模型供应商配置这件事，值得你用更从容的状态去做。

2.3 初始化完成后的控制台长什么样

完成向导之后，你就正式进入 Dify 控制台了。左侧导航通常会看到这些主要模块：应用、知识库、工具、模型供应商、日志与标注、成员管理、设置。不同版本菜单位置和名称会有一点出入，但大体结构是一致的。

其中"模型供应商"是你接下来要重点关注的地方。进入这个页面，你能清晰地看到两个层级的信息：服务商列表和服务商下的模型列表。如果初始化阶段已经配置过密钥，这个页面会显示对应服务商处于"已连接"状态，下面挂着该服务商提供的具体模型。如果还没配置，这里就是一片空白，并提示你先添加模型供应商。

我建议初始化完成后的第一件事，不是急着创建应用，而是先把"模型供应商"页面仔仔细细看一遍。你不用马上动手配，但要搞清楚它长什么样、哪些信息是展示状态、哪些地方是交互入口。这样后续配置的时候，你能更快定位到自己要操作的位置，而不是在界面里来回迷路。

3. 模型供应商配置：从选型到密钥落地的完整动作

3.1 先想清楚你偏向云端API还是本地推理

模型供应商配置的第一步，不是到界面上乱点，而是先从需求层面做一个选择：你打算让 Dify 调用云端的大模型服务，还是使用本地部署的开源推理服务，又或者是两者混合使用？

云端大模型服务商的好处是开箱即用，模型的整体能力强、更新快、生态成熟，你不需要自己准备 GPU 服务器，每个月按量付费就行。这类服务适合绝大多数应用场景，尤其是产品原型验证和业务落地阶段。缺点是你要依赖外部服务的稳定性和计费策略，还要面对前面说的网络链路问题。

本地推理服务的优点是数据不出内网、调用延迟可控、长期使用成本相对稳定，适合对数据隐私有要求、对网络链路不放心、或者需要高频次大量调用的场景。但代价也很明显：你得自己搭推理服务，准备模型权重、显存资源，模型能力通常落后云端一个身位，维护成本从零开始。

我见过不少团队一上来就奔着"本地部署更便宜"去，结果 GPU 采购、模型调优、并发优化折腾了几个月，效果还打不过云端现成的接口。反过来也有团队把大量生产流量压在一个云服务商上，价格飞涨后才开始后悔没做本地兜底。所以选型这件事没有绝对正确答案，关键是先算清楚自己的数据要求、预算和人力，再决定走哪条路。

3.2 对话、Embedding、Rerank不是一回事，别只配一个大模型

这是新手配置模型供应商时最大的认知误区。很多人以为"模型供应商 = 配一个大模型就完事了"，实际上一套能正常干活的应用至少会牵扯到三种类型的能力。

对话/推理模型是最直观的，ChatBot 应用、文本生成、Agent 推理、工具调用都靠它。Embedding 模型用于把文本转换成向量，是知识库能力的地基。没有 Embedding 模型，你把文档传进知识库，系统根本没有办法建立索引，查询的时候也无法做相似度匹配。Rerank 模型则在知识库检索之后做二次精排，提升"从一堆相关片段里挑出最有用内容"的准确率，高级检索模式下尤其依赖它。

对应到 Dify 里，你在"模型供应商"页面配置的每一项能力是分开的。对话模型、Embedding 模型、Rerank 模型的来源可以属于同一服务商，也可以来自不同服务商。比如你用一个服务商的大对话模型，同时用另一个服务商的 Embedding 接口，这在架构上完全没问题。关键是别只盯着对话模型，其他能力没人配，后面应用跑起来才发现知识库直接报废。

配置的时候，你每点开一个服务商，Dify 会列出该服务商支持的模型类型和能力标签，你要按需分别启用。如果是本地推理服务，通常也会暴露一个兼容 API 的入口，同样可以挂在供应商体系下，只是你的模型列表来自本机。

3.3 添加模型供应商的五个实操细节

具体配置流程在界面上看起来很直观：点"添加模型供应商"，从列表里选出服务商，填入 API Key，保存。但我实操下来有五个细节很容易折腾人。

第一，API Key 的复制要小心。从服务商控制台复制密钥的时候，经常会有隐藏字符、换行符或者首尾空格混进去。建议填完之后先把密钥放到一个文本编辑器里看一眼，确认无误再粘贴。很多"密钥是对的但就是通不过"的诡异问题，最后查出来就是复制多了一个字符。

第二，自定义端点的用法。部分服务商支持设置 Base URL 或自定义 API 端点，这意味着你可以把请求指向一个自建的网关、代理服务或兼容接口。如果你配置了自定义端点，一定要确认路径格式和官方 API 完全一致，Dify 会在你填写的端点后面拼接请求路径，少一段或多一段都会导致 404。

第三，模型列表的加载时机。密钥通过校验后，Dify 通常会调用服务商接口拉取可用模型列表。部分服务商的接口对模型列表的返回速度很慢，或者做了权限限制，导致前端一直转圈。遇到这种情况先刷新一次页面，如果列表还是出不来，可以检查一下密钥是否有拉取模型列表的权限，有些只开了对话权限的密钥连列表接口都访问不了。

第四，同一服务商可以配多把密钥。Dify 允许你在同一个服务商下添加多个 API Key，这样在多用户并发或者需要摊薄限流时，请求可以在不同密钥之间分散。后面多供应商管理那节我会展开讲，这里想强调的是：初期只配一把密钥没问题，但不要天真地以为一把密钥能扛住所有流量。

第五，模型命名和备注。Dify 里可以给同一个服务商下的不同密钥或模型写自定义名称，方便区分用途。这个习惯尤其重要，当你手上握着生产环境密钥、测试环境密钥、不同项目的密钥时，一个清晰命名能让你少掉很多头发。

4. 系统默认模型：最容易被忽略但影响面最大的设置

4.1 系统默认模型到底是干什么用的

初始化流程走到后半段，或者你进入"设置"菜单后，会看到一个"系统模型设置"之类的入口。它和单个模型供应商配置的区别在于：供应商配置解决的是"有哪些模型可用"，系统默认模型解决的是"不指定时默认用哪个"。

你可以把系统默认模型理解成整个平台的兜底模型。创建应用时，如果你没有手动选择模型，系统会直接用这套默认设置；知识库的文档索引处理，用的也是系统级 Embedding 模型；一些平台侧的辅助功能，比如自动生成标题、摘要等，同样依赖系统默认模型。说白了，Dify 把模型当成一项"基础设施"，而系统默认模型就是这条基础设施的默认路由。

我见过太多人初始化完成后，模型供应商配置得很齐全，对话模型、Embedding 模型都连上了，但系统默认模型一直处于空置状态。然后创建完应用，进对话界面一测试，模型下拉列表里明明有内容，可点提交就是报"模型未配置"或者"no model provider"之类的错。这多半就是系统默认模型没设置到位。

4.2 选系统默认模型的标准

设置系统默认模型时，Dify 通常会让你分角色选择：系统推理模型、系统 Embedding 模型，有些版本还会有系统 Rerank 模型。这里的选择标准不是"越强越好"，反而是"越稳越好"。

默认模型是整个平台的稳定性锚点，选一个最新发布但稳定性存疑、接口变动频繁的实验性模型，相当于把全平台的命运押在一个不确定因素上。我建议推理模型选你当前服务商里调用最成熟、限流最宽松、兼容性最好的那一款，Embedding 模型优先选成本低、速度快的通用款，Rerank 模型则根据你知识库检索的准确率需求来定。

还有一个小建议：系统默认模型的密钥要走独立额度，不要和某个高强度应用抢同一个账户。因为任何一处的默认调用都会消耗这部分额度，如果额度被打满，整个平台的应用都会跟着受影响，排查起来非常被动。

4.3 我见过的几个由系统模型缺失引发的连锁故障

系统模型没配好，故障往往不是立即爆发的，而是藏在你意想不到的角落里。

最典型的是知识库索引异常。你上传了一份 PDF 到知识库，界面显示上传成功，但文档状态一直停在"待处理"或"索引中"，等半小时也没变化。查日志发现是系统 Embedding 模型没配置，索引任务在调用模型那一步反复失败重试。这个故障的症状在知识库，根因却在系统模型设置，不看日志根本想不到。

另一个常见问题出现在应用分享环节。你在应用里手动指定了对话模型，测试也通过了，但把应用分享出去后，访问者那边却报模型调用失败。原因往往是分享页的请求走的是系统默认推理模型配置，而你本地测试时直接选的手动模型绕过了默认配置。两边配置不一致，最终表现就是"我这边好好的，别人一用就挂"。

还有一种情况是模型列表里全部可用，但页面加载时报错。某些自动化操作（比如批量生成、定时任务）不会走应用里手动指定的模型，而是直接使用系统默认设置。系统默认模型空置，这些任务就会批量失败，而且失败提示往往很隐晦，不会直接报"默认模型未设置"。

所以我把系统默认模型的配置看作初始化阶段的收尾动作，每次搭建完新环境，第一件事就是把它补全，而且是立刻补全，绝不拖延。

5. 配置完成后如何验证，以及报错排查链路

5.1 测试连接失败的五类典型报错

模型供应商配置页面一般都有"测试"按钮，点击后 Dify 会拿你填的密钥发起一次真实调用，验证配置是否可用。这个按钮很管用，但失败率也很高。根据我的经验，绝大多数失败可以归到下面五类：

出现报错先别急，报错信息本身就是最好的线索。Dify 通常会透出服务商返回的错误码和错误描述，你把这些信息复制到服务商文档里一查，大半问题都能定位。很多人输就输在只看"测试失败"四个字，不看具体错误内容，白白在原地打转。

5.2 "密钥没问题但就是超时"的排查顺序

这是我自己踩过最多次的坑。密钥明明在服务商控制台测试正常，但放在 Dify 里就是超时，而且报错信息很模糊。这种问题我必须按固定顺序排查，顺序一旦乱了，很容易绕远路。

第一步，确认 Dify 服务器到目标 API 的网络链路。在服务器上执行一个最简单的请求，比如curl -I https://目标API域名，如果这一步都不通，后面全部不用看了，网络问题无疑。如果通了，再看响应耗时，响应时间如果已经到了好几秒，Dify 侧的默认超时可能都不够用。

第二步，确认自定义端点的路径。很多服务商提供了多个 API 入口，比如统一的网关入口、区域专属入口、兼容入口，路径后缀各不相同。你在 Base URL 里填错了一个路径段，请求就会打到不存在的地址上，表现同样是超时或者 404。

第三步，检查密钥权限范围。有些服务商的密钥默认只开放了某几个模型的能力，没有开放全部接口权限。你在 Dify 里选择的模型如果不在密钥权限范围内，请求会被拒绝，只是不同服务商的错误表达方式不同，有的直接报权限错误，有的表现为连接断开。

第四步，测试一个最简单的对话请求。不要在 Dify 里用复杂知识库或高级编排来测试，先建一个纯对话应用，只配置一个对话模型，调一封最简单的消息看通不通。这种方式能把问题收敛到"模型链路本身"，而不是被上下游逻辑干扰。

5.3 验证通过不代表万事大吉，还要做一次端到端测试

很多人在"测试连接"按钮上看到绿色提示，就觉得配置完成了。测试连接通过，说明 Dify 能成功调用模型 API，但距离"应用真正能用"还差一步端到端验证。

我的做法是：配置完一个供应商后，立刻创建一个最简单的对话应用，用默认模型跑一轮完整对话。如果对话能正常生成结果，再测试一下知识库场景——如果这个供应商要承担 Embedding 能力的话，就上传一个文档、启动索引、发起一次带检索的问答，全程观察有没有报错。

把端到端验证放在配置完成后的十分钟内，能帮你把环境故障在第一时间暴露出来。如果你拖到第二天再测试，大概率要同时面对"是配置错了"和"是哪段逻辑错了"的双重问题，排查成本高得多。别偷懒，配置完当场过一遍全链路，这是最省时间的习惯。

6. 多供应商管理：从单密钥到生产级配置

6.1 同一家供应商配多把密钥的用途

单密钥配置适合个人实验和原型阶段，但一旦到了团队协作或生产环境，多密钥几乎是必然选项。同一个服务商下添加多把密钥，最直接的作用是分摊限流。

大模型服务商通常对单密钥有每分钟请求数、每小时 Token 数等多维度限制。你用一个密钥跑团队所有应用，高峰期一旦触顶，所有人一起报错。拆成多把密钥，再让不同应用或不同功能模块分别挂不同密钥，限流就被分成多个桶，整体可用性明显提升。

Dify 在部分版本里也支持密钥组和权重分配，意思是你给同一服务商配多把密钥后，可以设置它们被调用的权重比例。比如 80% 的流量走主密钥，20% 走备用密钥，这样主密钥的服务压力小一点，备用密钥又不至于完全闲置。不过具体入口在不同版本里有差异，我建议你在"模型供应商"页面仔细找一下，或者在更新日志里确认版本支持情况。

6.2 不同供应商之间的主备策略

多密钥摊薄只在同一服务商内解决限流问题，一旦服务商本身出故障，比如接口大面积超时、服务不可用，所有依赖它的应用还是会一起挂。所以生产环境要建立不同供应商之间的主备策略。

我的建议是：核心应用的主推理模型用一家服务商，备用模型用另一家服务商，两者能力对齐到一个可接受的水平。Dify 支持在应用级别手动切换模型，这意味着你可以在主服务商故障时，快速把应用切到备用服务商，而不是干等恢复。切换前提是备用服务商已经提前配好密钥、通过测试、模型也验证过，别等到故障发生才现场配。

这里有个容易犯的错误：备用方案和主方案选的是同一家服务商的不同模型。这就等于把鸡蛋放在一个篮子里的两个格子里，服务商整体出问题时，备用方案同样失效。真正的备援应该是异构备援，尽量选两家独立的服务商，才能起到隔离故障的作用。

6.3 密钥与权限的日常管理习惯

多供应商、多密钥、多环境跑起来之后，密钥管理就成了一个新的麻烦源。我在实际操作中慢慢养成了一些习惯，分享给大家参考。

首先，密钥命名要强制规范化。比如项目名-环境-用途-编号，像demo-prod-main-01、demo-test-embedding-02。这个名字会出现在 Dify 的模型供应商列表里，命名清晰能让你在多个密钥之间快速定位，而不需要猜测某个密钥到底是干嘛的。

其次，测试密钥和生产密钥要严格分开。很多团队图省事，测试环境和生产环境用同一把密钥，结果测试流量把生产配额吃光，或者在测试阶段误操作触发服务商的封禁措施，直接连带生产环境不可用。多花一分钟把密钥分开，能避免一场事故。

另外，定期轮换和清理。团队成员离职、项目下线、密钥在日志里泄露，都是需要重新生成密钥的理由。Dify 的管理界面能让你方便地移除失效密钥，但前提是你得记得去清理。我建议每季度做一次密钥健康检查，看看有没有过期、超量、不再使用的密钥躺在配置里，该删就删。

最后，给团队分配权限这件事也要养成习惯。Dify 支持多成员机制，不是所有人都需要管理员权限来管理模型供应商。给开发人员分配应用维护权限，让少数人掌握供应商管理权限，能降低误操作风险。密钥这种基础设施类的东西，权限收紧一点没坏处。

最后说一个我自己的习惯：每次初始化完一个新环境，我都会顺手截两张图，一张是模型供应商列表页面，一张是系统默认模型设置页面，记录下当时配了哪些供应商、哪些模型被设为默认。这个习惯看起来微不足道，但在环境出了异常需要对比排查时，这两张图就是最靠谱的参照物。模型供应商配置这件事，不是配完就结束，而是在你后续每次排查故障时都会回来翻的底层配置，早一点建立体系化的管理意识，后面能省下大把时间。