装好Dify之后，很多人会被那个空白界面卡住：应用模板能创建，但模型列表空空的，连一个最简单的聊天助手都跑不起来。问题几乎都出在同一件事上——模型供应商还没接进来。把Dify比作一套精装交付的房子，初始化就是通电通水，模型供应商配置则是把真正负责思考的“大脑”请进门。前两篇我们聊了环境起步和基础概念，这篇就以“注入灵魂”为主线，把首次初始化和模型供应商配置完整拆一遍，重点讲清楚每一步为什么要这么做、常见坑都在哪里。无论你是刚接触Dify，还是部署完卡在配置环节，这篇文章都值得你从头看完。
1. 初始化前先体检：别把环境问题带进配置阶段
很多人一登录就急着填Key、选模型，结果怎么填都不对，最后发现是Dify服务本身就没跑健康。初始化之前花五分钟把环境状态确认一遍，后面能少踩一半的坑。
1.1 容器状态与迁移日志检查
如果你用的是Docker Compose部署，先看整体容器状态。进到部署目录，执行以下命令：
docker compose ps正常情况下，api、worker、web、db、redis、sandbox、ssrf_proxy 这些核心容器都应该是Up状态。我见过不少情况是 web 起来了、api 却在不断重启，页面能打开但所有请求都超时。此时重点看待：
docker compose logs -f api --tail=100观察日志里有没有重复报错、数据库连接失败、迁移未执行之类的关键字。首次部署时，数据库初始化迁移可能没有自动完成，需要手动执行：
docker compose exec api flask db upgrade这个动作会把数据库表结构建立起来，执行完之后再刷新页面，初始化引导才会正常出现。
提示：如果你是升级版本而不是全新部署，执行前先备份数据库，尤其是
data目录下的内容。升级过程中出现表结构冲突并不罕见，有备份才能从容回滚。
1.2 管理员账号的创建与初始化设置要点
容器健康检查通过后，第一次访问http://你的服务器IP/install，会进入管理员初始化引导页面。这里要设置管理员邮箱、用户名和密码。密码要求至少包含字母和数字，长度够12位更稳妥——这个账号是系统的最高权限，后面所有模型供应商配置、成员管理、系统设置都靠它，千万别图省事用弱密码。
设置完管理员账号，会进入系统初始化设置页，主要包含几项内容：
- 系统名称与描述：会显示在控制台和工作台界面上，按团队场景填就行。
- 系统语言与时区：建议按团队所在地配置，避免后续时间显示错乱。
- 邮件服务器 SMTP：可以推迟配置，但如果你需要邀请成员、密码找回，就必须补上。新版本里还支持通过控制台不限流量，配置完成后建议在“设置—成员管理”里实际发起一次邀请测试，确认信件能正常送达。
初始化向导走完之后，系统会创建一个默认工作空间。Dify 支持多工作空间隔离，但新手阶段不建议一上来就建一堆空间，先在默认空间里跑通流程，再根据团队结构规划。这样排查问题时也更简单，毕竟模型配置粒度是按空间隔离的，配置错了只影响当前空间，恢复成本低很多。
2. 模型供应商配置：把真正的大模型“接”进来
初始化完成后，需要到“设置—模型供应商”页面添加模型服务商。如果你看到的画面还是空白一片，那是正常的——Dify 默认不内置任何模型的Key，所有模型都需要你自己配置。
2.1 模型接入为什么是“中枢环节”
没有模型接入，Dify 的所有核心能力都是空转：聊天应用没有回答来源，Agent 没法调用工具推理，工作流节点执行会报错，知识库文档无法完成向量化索引，RAG 检索更是无从谈起。
Dify 中模型按用途分成几类，配置时一定要区分清楚：
- LLM 类型：负责对话生成、工具调用推理，比如 DeepSeek-V3、通义千问等大语言模型。
- Text Embedding 类型：负责把文本转换为向量，用于知识库的索引和检索匹配。
- Rerank 类型：对检索结果进行重排优化，提升知识问答的精准度。
- Moderation 类型：用于内容审核，可选配置。
新手最常见的误区是只配了一个 LLM，就跑去建知识库，结果文档上传后一直显示“索引失败”，问题就出在 Embedding 模型没有配置。所以配置供应商之前，先想清楚你的应用要用到哪几类模型的组合。
2.2 云厂商 API 配置实操：DeepSeek、通义、智谱
以目前最常用的几家平台为例。首先去对应平台官网注册账号，然后在控制台中创建 API Key。注意创建完成后立即复制保存，大多数平台只在创建成功时完整显示一次Key，页面关闭之后就看不到了。
拿到Key后，回到 Dify 的模型供应商页面，找到对应平台图标，点击“配置”。以 DeepSeek 为例，你需要填入以下信息：
- API Key：粘贴刚才复制的密钥。
- 模型名称：如
deepseek-chat（通用对话）、deepseek-reasoner（推理增强）。 - API Endpoint：通常有默认值，保持默认即可。
从实际上手体验来看，DeepSeek 的deepseek-chat性价比很高，适合大多数对话场景；deepseek-reasoner带深度推理，适合复杂逻辑分析和数学推理，但响应会慢一些、消耗的 token 也更多。
通义千问的接入类似，对应配置项是 DashScope API Key，常用模型有qwen-plus、qwen-turbo、qwen-max，其中long系列模型支持超长上下文。智谱则可以接glm-4-plus、glm-4-flash，其中glm-4-flash是免费模型，适合测试流程时使用。
这些平台配置完之后，Dify 通常会自动拉取可用的模型列表。如果拉取异常，可以手动填模型名，但前提是模型名必须和平台文档里完全一致，大小写和连字符都不能错。建议直接在平台模型列表页复制标准名称，别凭印象手敲。
2.3 本地模型接入：Ollama 与私有化思路
不想把数据都送到云上，或者希望控制成本，可以用 Ollama 跑本地模型。先在装有 Ollama 的机器上拉取模型，例如：
ollama pull qwen2.5:7b ollama pull bge-m3 ollama pull bge-reranker-v2-m3然后在 Dify 模型供应商页面选择 Ollama，关键配置有两项：
- API Base URL：默认
http://localhost:11434，但如果是用 Docker 部署的 Dify，这里的localhost指向的是容器内部，无法访问宿主机上的 Ollama，必须改成宿主机 IP，或使用http://host.docker.internal:11434（macOS/Windows 桌面版 Docker 支持）。 - 模型类型与名称：填 Ollama 拉下来的模型名，注意需要先配置一个 LLM 模型，再单独配置 Embedding 和 Rerank 模型，三类分别填写。
本地模型的好处是数据不出内网，成本固定，不受供应商限流影响；缺点是对服务器资源要求高，7B 级模型至少需要 8GB 以上显存或同等内存，跑起来才能勉强顺手。生产环境中，常见做法是混合配置：对话用云端大模型保证质量，知识库向量化与重排用本地模型保护隐私数据，成本还能压下来。
下面是一个常见组合参考：
| 用途 | 云端方案 | 本地方案 |
|---|---|---|
| 对话生成 | DeepSeek / 通义 qwen-plus | qwen2.5:7b / llama3.1:8b |
| 向量化 | text-embedding-v3 | bge-m3 |
| 相关性重排 | 平台提供的 rerank 模型 | bge-reranker-v2-m3 |
| 内容审核 | 平台审核模型 | 可选，暂不配置 |
3. 配置过程中的核心细节：模型选择、参数与权限
模型配置看起来只是填几个字段，但要是搞不清背后的逻辑，很容易选错模型、浪费 token，甚至引发数据安全问题。这一节把关键细节一次说透。
3.1 LLM、Embedding、Rerank 三类模型为什么要分开
三者的职责完全不一样，技术实现也不同，混着填必然出问题。LLM 是生成式模型，根据上下文预测下一个词；Embedding 是编码模型，把整段文本映射到高维向量空间，让语义相似的文本在向量空间里距离更近；Rerank 则是一种重排模型，它对“问题”和“候选文档”的组合统一打分，比单纯向量余弦相似度更准。
用一个生活化类比：知识库检索就像图书馆找书，Embedding 负责把书按内容主题大致分类摆放，Rerank 决定最终把哪几本书放到你面前，LLM 负责阅读这些书并整理成回答。三个环节都正常工作，回答质量才有保障。
Dify 在配置时要严格按模型类型归类填到对应字段。如果你把 LLM 模型填到 Embedding 位置，知识库索引时会报维度不匹配之类的问题。在新版本中，点击模型类型会自动过滤可选模型，但仍然要留意“基础模型”与“推理模型”的区分。
3.2 模型名称、上下文长度与成本估算
模型名称看起来只是标识，实际上包含了关键信息。以通义为例，qwen-plus和qwen-turbo定位不同，前者质量高，后者速度快成本低；qwen-long则是长文本专用。选模型前，先到供应商文档页查清楚上下文窗口大小，并预估线上实际输入长度。
为什么上下文长度重要？在 RAG 场景中，用户问题加上召回的文档片段会被拼进 Prompt 一起发给 LLM，一旦超出上下文窗口，就会报“context length exceeded”。常见长文本方案是选 128K 或 200K 窗口的模型，但窗口更大不代表越贵越好——上下文越长，单次请求成本越高，响应也越慢。
成本估算比较简单，按 token 计费单价乘用量即可。比如一次问答请求消耗 10K 输入和 2K 输出，平台提供的价格系数分别是输入 0.001、输出 0.002（示例值），那单次成本就是10 * 1000 * 0.001 + 2 * 1000 * 0.002，约 0.014 元。长期运行要关注的是每天调用量，建议在应用分析页面定期查看 token 消耗趋势，而不是等月底账单来吓自己。
提示：Dify 的“设置—模型供应商”里可以做区别范围限制，配置好模型后，在应用编排页面还能给不同模型设置温度、top_p 等采样参数。多数场景温度设 0.7 左右比较稳，知识问答建议比默认值再低一些，减少“发挥过头”的幻觉回答。
3.3 密钥管理与多环境隔离
模型 API Key 是敏感凭证，把它暴露在代码仓库、聊天记录或截图里都是高危行为。Dify 的模型 Key 统一存储在数据库或配置文件的加密字段中，页面配置页面不会明文回显。即便如此，也要注意以下几点：
- 每个环境使用独立 Key：开发、测试、生产分别申请，避免测试流量污染生产账单。
- 对团队协作空间做权限划分：Dify 支持成员角色区分，建议普通成员只给“应用操作”权限，不对所有人开放模型供应商管理入口。
- 预算封顶：部分平台支持设置告警阈值与额度上限，再配合应用侧的调用限制，防止 Key 泄露或被滥用时产生天价账单。
如果你有运维基础，还可以把 Key 放到环境变量里注入，通过基础设施的密钥管理系统统一管理。这样即使服务器磁盘损坏、数据库泄露，密钥也不会随之暴露。多租户场景下，各空间各自配置独立 Key，运维侧也更容易追踪消耗来源。
4. 常见问题与排查技巧实录
配置过程中最消耗耐心的就是各种报错。整理几个高频问题和我自己的排查思路，能帮你快速定位。
4.1 添加模型失败：鉴权错误与模型拉取失败
现象一：填完 API Key 点击保存，提示鉴权失败或 401/403。排查顺序如下：
- 检查 Key 是否完整复制，有没有意外的空格或换行。
- 确认 Key 所属平台和当前配置的供应商是同一个，别把 A 平台的 Key 填到 B 平台的配置里。
- 确认账号是否有调用该模型的权限——有些模型的申请开通是单独的，没开通就调用必然报错。
- 时间不同步也可能影响签名校验，服务器上的时间偏差过大时，部分网关会拒绝请求。
现象二：模型列表拉取为空。先用供应商平台自带的在线调试工具，跑通一次真实调用；如果平台调试正常，那问题多半出在 Dify 与平台的网络连接上。这里可以进 Dify 容器内执行一个简单的连通性测试：
docker compose exec api curl -s https://api.deepseek.com -o /dev/null -w "%{http_code}"返回 200 或 403 都说明链路是通的，403 多数是鉴权问题；如果连接超时，就需要检查服务器出网策略与安全组配置。
4.2 本地 Ollama 连接不上或超时
这是 Docker 部署 Dify 时最经典的坑。前面提过localhost的问题，再强调一遍：容器内访问宿主机服务，不要直接写 localhost。Windows 和 macOS 可以用：
http://host.docker.internal:11434Linux 服务器则建议直接写宿主机内网 IP。另外确认 Ollama 本身监听地址不是只绑了 127.0.0.1，可以修改配置让其监听所有网卡接口，或者用反向代理只向内网开放端口。
测试命令也很关键：
curl http://你的宿主机IP:11434/api/tags能返回 JSON 格式的模型列表，说明 Ollama 服务对外可见。如果返回空数组，检查拉取模型是否成功；如果连接拒绝，检查防火墙和 Ollama 服务状态。
4.3 知识库索引失败、检索效果差
知识库上传文档后一直处于“待索引”或直接报错，最常见的两个原因：
- Embedding 模型没配置：新建知识库时或系统设置里缺少向量化模型。
- 文档格式解析失败：扫描版 PDF、无文本层的图片型文档，Dify 无法直接抽取文本，需要先用 OCR 转换为可编辑文本后再上传。
检索效果差的排查方向更多。建议打开知识库的“召回测试”，观察召回片段的相关性分数。如果分数普遍很低，依次调整：
- 选用更强的 Rerank 模型，或开启 rerank 功能。
- 将检索模式从“向量检索”切换为“全文检索”或“混合检索”。
- 调整召回 TopK 数量，可从默认值往下调，避免噪声片段混入。
- 设置相关性分数阈值，过滤掉低质量结果。
这些操作都可以在知识库设置与应用编排页中直接完成，不用改代码。调整完一轮，再回到“召回测试”里对比效果，形成一个小迭代闭环。
我把常遇问题整理成速查表，方便大家对照：
| 现象 | 可能原因 | 解决思路 |
|---|---|---|
| 模型列表为空 | 网络不通 / Key 权限不足 | 平台调试工具先测通，再进容器 curl 测试 |
| 401/403 鉴权失败 | Key 填错 / 未开通模型 | 检查空格、换行、Key 归属与模型开通状态 |
| Ollama 连接失败 | 容器内 localhost / 监听地址限制 | 改 host.docker.internal 或宿主机 IP，检查防火墙 |
| 文档索引失败 | 缺 Embedding 模型 / PDF 无文本层 | 补配向量模型；先 OCR 再上传 |
| 回答总引用无关内容 | 检索噪声 / 未重排 | 开 Rerank、调 TopK、把相关性阈值调高 |
| 上下文超限 | 选错模型 / 召回过多 | 换更长的上下文模型或降低召回段数 |
5. 从空白应用到跑通第一轮对话
配置完模型供应商，别急着搭建复杂工作流。先创建一个最小闭环，验证整条链路是通的，再做复杂工程。
5.1 最小可用配置组合
我的推荐组合是：
- 对话 LLM：用你申请好且跑通鉴权的云平台模型，比如 DeepSeek 或通义。预算宽松时选质量款，预算紧张时选 Flash/Turbo 款先验证流程。
- Embedding：如果数据量不大，可以用同一个云平台的向量模型；如果对隐私要求高，用本地 bge-m3。
- Rerank：项目初期可以不配，检索效果不满意再加。
模型配置好在“创建应用”页面选择“聊天助手”，找到对应模型后，直接点击“发布”获取公开访问链接，建议先直接用几轮测试对话。
5.2 验证对话链路的三层检查
第一层，普通对话测试：问一个不依赖外部知识的问题，确认模型能正常回复。第二层，带着知识库测试：上传一份文档，建立知识库，在应用编排里把知识库关联进来，然后问一个答案只能在文档里找到的问题，验证召回链路。第三层，工作流测试：搭一个只有两个节点的简单工作流，一个开始节点、一个 LLM 节点，确认节点之间参数传递无误。
这三层都通过之后，再往应用上叠加语音输入、文件上传、Agent 插件等能力，每一步出了错都能立刻知道是哪一层的问题，而不是整坨代码胡乱猜。曾经我见过有人配置完直接搭了一个五节点的复杂工作流，跑不通之后排查了整整一下午，最后发现只是模型名称大小写填错了——先跑最小闭环，能帮你省掉大量类似的无意义排查时间。
Dify 初始化与模型供应商配置，其实是整个团队使用体验的起点。项目跑起来之后，我建议每个月回头看一次模型用量报表，检查各空间消耗趋势，顺带清理没人用的测试应用。大模型调用产生费用是持续的，不像一次性买断的软件，养成看报表的习惯能让你在这个领域走得从容很多。
最后分享一个我自己的操作习惯：任何一个新供应商接入，先在测试空间里用最小配置跑通一遍，再填正式 Key、分发给团队。验证时会顺手把供应商文档里的模型名、价格、上下文窗口三项抄下来汇总成团队内部备忘，后续新同学接手也能照葫芦画瓢，不用每次都在平台上重新翻文档。这套流程跑顺之后，你会发现模型配置并非难事，真正值钱的是对整个调用链路的理解——而那正是你接下来搭复杂应用时最坚实的基础。
