很多人后台私信问得最多的一句就是我把 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本地私有化模型接入速度快填 Key 即可慢需要部署和调优模型效果通常更强更新快取决于开源模型选型和微调水平数据合规数据出域需评估数据不出内网安全性高成本结构按 token 计费有隐性成本固定硬件投入长期成本可控运维压力几乎为零需要监控 GPU、模型版本、并发适合场景大多数业务应用、快速上线数据敏感、离线环境、深度定制从我的经验看大多数团队的起步方案都是远程商用 API。先把应用跑通验证业务逻辑等真的到了数据合规或成本瓶颈期再考虑迁移本地模型。这属于典型的低成本试错。2.3 上下文长度、价格、并发和延迟选型到底比什么接哪个供应商、选哪个模型很多人只看模型名字大不大。实际上做技术选型时更值得关注的是四个维度上下文长度模型一次性能处理多少 token。8K、32K、128K直接决定你的应用能不能吞下一整份长文档。做文档问答上下文长度不够就是硬伤。价格不同模型的输入输出价格差异很大。贵的模型效果好但跑一天企业级应用成本可能吓你一跳。省钱的办法是把简单任务交给便宜的小模型。推理能力和响应质量代码生成、复杂逻辑推理必须用强模型意图分类、关键词抽取小模型足够。并发和延迟商用 API 通常有并发限制超过限额会被限流。本地模型则要看 GPU 算力能扛住多大的并发否则用户一多响应时间直接起飞。我见过不少团队在选型时只看模型推理能力忽略价格结果月底账单出来才大吃一惊。这里的原则是按任务难度匹配模型大小。主对话用强模型副任务用弱模型能省一大笔钱效果也不会差。另外要特别注意模型标识符。OpenAI 的不同版本、DeepSeek 的 chat/reasoner 系列模型名是完全不同的。配置的时候填错一个字母系统就会告诉你模型不存在。真实项目里这类问题占了模型配置报错的一半以上。3. 手把手实操完成初始化并接上你的第一个模型前面聊了不少思路这一章进入正题。我会从首次打开 Dify 开始一步一步演示初始化和管理员创建然后带你完成远程 API 和本地模型的接入最后设置默认模型。全程按照我实际操作过的方式来写遇到坑也会同步标注。3.1 首次打开 Dify创建管理员账号的完整步骤假设你已经通过 Docker Compose 把整个 Dify 服务拉起来了。在浏览器里输入服务器地址正常情况下会自动打开一个引导页面要求设置管理员账号。操作步骤其实很简单输入管理员邮箱。输入密码建议至少 12 位包含大小写字母、数字和符号。确认密码后点击创建管理员账号。系统初始化完成后自动进入 Dify 工作台。这一步有几个细节值得说明。邮箱一定要填真实可用的地址原因前面说过不再重复。密码最好不要用团队名称、公司简称这类容易猜的组合因为管理员账号权限是整个平台最高的影响所有应用和知识库的访问权限。如果初始化完成后你想修改平台显示名称可以进入右上角头像菜单里的“设置”在通用设置里调整。这些操作不需要重新初始化运行时就能改。需要提醒的是管理员账号创建之后不要轻易删除或更换。后续所有成员、应用、数据模型的归属关系都挂在它的租户下删了容易引发连锁问题。多成员协作的需求正确的做法是进入“成员管理”邀请新用户而不是把超级管理员账号共享给所有人。3.2 找到模型供应商配置页界面和字段先认清登录工作台之后左侧菜单栏往下翻找到“设置”点进去就能看到“模型供应商”页面。页面上是一排供应商卡片。不同的供应商状态不一样已经配置过的卡片上会显示绿色对勾没配置的显示“未配置”或“立即配置”配置失败、Key 失效的会有红色感叹号点击任意一个供应商卡片会进入它的配置详情页。通常需要填写的字段包括API KeyBase 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 服务已经启动浏览器却一直停在登录页或者提示数据库错误管理员引导页出不来。排查思路确认容器全部启动成功。用docker compose ps查看状态看是否有容器反复重启。查看 API 容器日志。如果初始化管理员信息写入失败会有明确报错。定位关键信息可以用docker compose logs api --tail 200检查数据库迁移是否完成。如果 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 模型索引步骤根本走不下去。排查方式去“设置 - 模型”页面确认 Embedding 模型是否已设置。确认该模型供应商的 Key 额度还有余量部分平台对新建密钥的免费额度很有限跑几个文档就用完了。如果数据集同时支持全文检索你可以临时切换索引方式验证问题但生产环境建议还是把向量检索和 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 设计还是知识库构建都会顺畅很多。