2.2 模型接入：挂上第一个大模型

2.2 模型接入：挂上第一个大模型

模型接入分两步：先在"设置-模型供应商"里装上供应商并填密钥（让平台"认识"这些模型），再到"系统模型设置"里指定默认的推理、嵌入、重排三件套（让平台"用上"这些模型）。只做第一步不设默认，建应用时就会频繁遇到"无可用模型"的提醒。

平台已就绪，本节让它开口说话。这是开台三步的第二步，也是第 4 章的前置——知识库对嵌入模型的依赖，在这里一次讲透。

从设置页讲起

进入控制台的"设置-模型供应商"，你会看到一张长长的大厂名单：OpenAI、Anthropic、通义千问、智谱、月之暗面等国际与国内主流供应商，以及 Ollama、Xinference、OpenAI-API-compatible 这类"自托管入口"。接入动作对所有供应商都一致：点"安装"或直接展开，填 API 密钥，保存。密钥以加密形式存在你自己的数据库里（这正是 2.1 节强调 SECRET_KEY 的原因）。

装好供应商只是"认识"，还要"指名道姓"。往下找到系统模型设置，四个下拉框各选一次：

• 系统推理模型：聊天、Agent、工作流里 LLM 节点的默认模型，决定日常回答质量与成本；
• Embedding 模型：把文本变成向量的模型，知识库的"索引员"；
• Rerank 模型：对检索结果二次排序的模型，混合检索的质量放大器（可暂空，第 4 章再开）；
• 语音转文字：语音输入场景才需要，客服首期用不上。

这张时序图里有个值得停留的细节：调用模型的是平台后端而非浏览器。所以密钥永远不会暴露给终端用户，浏览器里走的只有你自己的应用密钥——安全边界天然清晰。

三条路线怎么挑

接入方式实质是三选一（或组合），成本、质量、合规各有侧重：

我的建议跟 1.2 节的分期思想一致：起步用云上国内供应商把流程全跑通，质量瓶颈出现后再评估本地化。反着来——第一天就折腾本地模型——最常见的结局是两周过去还卡在显卡驱动上，业务一行没跑。

本地路线：Ollama 接法

有内网闭环需求时，Ollama 是最省事的本地推理入口。先在宿主机或另一台机器上装好 Ollama 并拉一个模型：

ollama pull qwen2.5:7b        # 拉一个 7B 量级的开源模型，约 4.7 GB
ollama serve                   # 默认监听 11434 端口
​

然后回 Dify 设置页：模型供应商列表里找 Ollama，填本地服务地址（Dify 装在 Docker 里时，localhost 指向容器自身，要用宿主机的局域网地址或 host.docker.internal），模型名填 qwen2.5:7b。保存后它就出现在可用模型列表里，系统模型设置里也可以选它。

本地路线的两个诚实提醒：其一，7B 级模型与云端旗舰的质量差距在复杂推理上肉眼可见，客服问答这种"知识查找型"任务差距小；其二，嵌入模型同样可以本地化（Ollama 也托管嵌入模型），但一旦知识库用某个嵌入模型建了索引，换模型就必须重建全部索引——这行字值一次停机窗口，第 4 章会再强调。

验证接入是否真的通了

接入完成不等于接入可用，用三十秒做三步验证：

# 1) 在控制台顶部或设置页找到"系统模型设置"旁的连通状态提示，无红色告警
# 2) 新建一个空白聊天助手，模型选刚接入的那个，进入调试面板
# 3) 发一句"你好，请自我介绍"，收到流畅回复即全链路通
​

第三步收到的是分句流出的打字机文本，说明流式链路（网关→API→供应商→回程）整条无断裂。如果卡住或报错，记下报错文案，2.3 节的排障清单有对应条目。

给模型配额和预算上个闸

云上路线别忘了成本闸门：供应商控制台里给密钥设月度消费上限，比事后看账单心疼要体面得多。团队内部也可以按工作区区分密钥——试验田用低限额密钥，正式环境用正式密钥，账单天然分开。第 7 章的用量监控会把这件事闭环。

一次接入翻车的复盘

接入环节最迷惑的故障往往"看起来全对"。我第一次接国内某供应商时，密钥正确、模型名复制自控制台、连通测试通过，但调试面板一发消息就报"模型内部错误"。按 2.3 节的三步次序走：容器全绿；API 日志里找到真实报错——供应商返回"无权访问该模型"；回供应商控制台核对，发现该密钥只开通了对话模型，没开我选的那款推理模型。修复只花十秒（换密钥权限），定位花了半小时，因为报错文案在界面层被泛化了。

这个案例的通用教训：界面报错文案是二手信息，容器日志里才有供应商的原话。遇到"接入成功但调用失败"，第一时间去翻 API 容器日志，别在设置页反复重试。

问题：多个供应商能同时接吗？

能，而且推荐。Dify 的模型供应商是并列关系，接三家就拥有三家的模型清单，建应用时按需选。常见组合是"一家主力 + 一家备用"：主力跑日常，主力的模型在维护窗口时，应用的模型下拉框切换到备用即恢复服务——这是低成本的高可用方案，比死守单供应商从容得多。系统默认模型三件套每样都要指定，切换时记得三件套一起切，别出现推理用甲家、嵌入用乙家的意外组合（能跑，但账单与延迟都会让你疑惑）。

⚠️ 常见坑：把"安装供应商"当成"接入完成"，没做系统模型设置。症状是聊天应用里模型下拉框是空的或默认项异常。另一个方向的坑：Docker 部署后 Ollama 地址填了 localhost——容器里的 localhost 不是宿主机，换成局域网地址或 host.docker.internal 即可。

本节要点回顾

• 两步接入：供应商密钥让平台认识模型，系统模型设置让平台用上模型，缺一不可；
• 三件套分工：推理模型管回答，嵌入模型管索引，重排模型管检索质量放大；
• 路线选择：先云上跑通流程，合规与成本压力出现后再本地化，不要倒序；
• Ollama 地址：容器内 localhost 不指向宿主机，用局域网地址或 host.docker.internal；
• 嵌入模型锁定：索引与嵌入模型绑定，中途更换等于全量重建知识库；
• 成本闸门：密钥设消费上限，工作区分密钥，账单先分家。

模型已经出话，下一节给整套装好的环境做一次系统体检，把常见故障的诊断次序固化成清单。