dify 关联本地大模型

你在自己机器上把模型跑起来了，接口能通，结果接进 Dify 时不是报错就是回答跑偏——多半不是模型不行，而是接口形态、模型类型归类、上下文与并发这几处没对齐。这篇按「先打通、再分类、后调优、最后验证」的顺序给你一套可执行动作，也写清楚哪些情况下本地接入并不划算。数字类信息一律让你去站内对应页面按当时口径核对。

你在自己机器上把模型跑起来了，命令行一敲能出字，接口也能通，结果接进 Dify 不是报错就是回答跑偏。多数时候问题不在模型本身，而在三处没对齐：接口形态是不是 Dify 认的那一种、模型在 Dify 里被归成了哪一类、以及上下文和并发有没有按工作流的真实调用量去留余量。

这篇按「先打通、再分类、后调优、最后验证」的顺序给一套动作，顺带写清楚什么情况下本地接入其实并不划算。凡是涉及具体数字的部分——显存占用、延迟、参数量折算——都请到站内对应页面按当时的测算口径核对，别抄别人博客里的旧数。

接之前先确认三件事，省掉大半返工

• 本地服务要能暴露成 OpenAI 兼容的 HTTP 接口，别指望 Dify 直接认某个推理框架的私有协议。验证方法：用 curl 调一次它的模型列表接口，再调一次对话接口，两个都返回正常结构才算合格。
• 网络可达性是第一坑。Dify 跑在容器里、模型跑在宿主机时，配置里写 localhost 指的是容器自己，要改成宿主机的可达地址，或者把两者放进同一个 docker 网络用服务名互访。
• 先量基线。接进 Dify 之前，用站内的测试工具记下本地接口的首字延迟和单次耗时，接完之后才有对照，否则出问题时分不清是模型慢、网络慢还是编排慢。

这三件事的顺序不要颠倒。接口通了但网络不通，你会以为是配置写错；网络通了但没基线，你会把工作流的开销算到模型头上。先跑通最小闭环，再往工作流里塞逻辑。

接口形态对不上，就是在白折腾

Dify 侧接入本地模型，通常有两条路：一条是按 OpenAI 兼容端点的方式填地址和密钥，另一条是走某些本地推理服务的原生对接方式。先确定你手里的是哪一种，再决定在后台哪个入口建模型，选错了入口会一直报连接失败。

密钥这一步最容易卡人。本地服务基本不看密钥，但 Dify 的模型配置表单会把它当必填项，随便填一个占位串即可，不用纠结。真正要较真的是模型名：拿不准的时候直接调服务端的模型列表接口，把返回的名字原样抄过来。

# 先确认服务端认哪些模型名
curl -s http://你的地址:端口/v1/models

# 再确认对话接口能正常返回
curl -s http://你的地址:端口/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 占位串" \
  -d '{"model":"服务端注册名","messages":[{"role":"user","content":"你好"}]}'

同一个服务，在 Dify 里是要分角色建的

这里有个高频误解：本地跑起来一个模型，就觉得 Dify 的对话、知识库检索、重排全都能用它了。实际上这是三类不同用途的模型，接了一个不代表另外两个也能用。在 Dify 后台是按类型分别添加的，对话模型和文本嵌入模型走的是完全不同的配置入口。

对话模型

负责生成回答，工作流里的 LLM 节点、问答节点用它，绝大多数本地服务都能顶。

文本嵌入模型

负责把文档和问题转成向量，知识库检索靠它，不是每个推理服务都顺手提供。

重排模型

负责把召回结果重新排序，属于可选增强，没有它检索也能跑，只是精度打折。

嵌入模型这一步要一次想清楚。一旦选定并建了知识库、灌了文档，后面再换模型就得重建整个索引，文档多的时候这个成本不低。如果你眼下只跑了一个对话模型，比较务实的做法是先把 Dify 的知识库能力放着别开，或者把检索切到别的可用通道，免得出现「模型接上了但问答查不到资料」这种看起来像 bug 的错觉。

显存和并发必须先算，不然上线就堵

本地部署最容易被低估的就是这一块。显存占用大致由模型参数量、量化档位、上下文长度三项决定，再往上叠加并发路数。具体怎么折算、不同量化方式差多少，到站内的部署测算页面按你选的型号和量化档位实际算一遍，比记别人的经验值靠谱。

• 按上面三项估出单路占用，再留出余量给并发，余量不留就直接上线，多来一个人就排队或直接崩。
• 注意 Dify 的一次请求可能触发多轮模型调用，比如先改写问题、再判断意图、最后生成，你以为的一路对话实际是好几路，并发估算要往上抬一档。
• 量化档位不是越低越好。低比特确实省显存，但可能影响指令遵循和结构化输出，工作流里大量靠模型吐 JSON 的节点要单独验证。
• 把超时时间设得比实测耗时长一截，本地模型冷启动或者被别的进程抢资源时，单次耗时会明显跳动。

量化档位这一条值得单独强调。如果你的工作流里有节点要求模型严格按格式输出，接完以后先用一组带结构化要求的样例压一遍，确认在低比特下格式没崩，再往生产场景推。

工作流里真正决定体验的几个开关

模型接上、参数能调之后，体验好坏基本由几个开关决定。把它们按任务分工来设，比统一调成一个值要有效得多。

上下文长度这一项单独说一句：不要贴着模型上限设，要留出输出空间，否则容易出现回答写到一半戛然而止，看起来像模型能力问题，其实是被长度截断。

还有一条排查顺序上的经验：把检索节点和生成节点分开调。先确认检索召回的片段是对的，再调生成。两件事混在一起改，你永远说不清是没查到还是查到了没用上。

上线前后各做一遍验证，留好回退路径

1. 固定一组测试问题覆盖三类场景：简单问答、需要检索才能答、需要结构化输出。把这组问题存下来，每次改动前后各跑一次，做前后对照，不要凭感觉说好用了。
2. 按错误类型分类统计别只看成功率。超时、连接被拒、模型名错、上下文超限，这四类处理方式完全不同，分开统计才知道下一步改哪里。
3. 保留切换入口在配置里留一个能切回线上 API 的开关或备用模型配置。本地服务挂了、或者显存被别的进程占满时，临时切走，整个应用不至于停摆。
4. 记录每次改动显存参数、上下文长度、温度这些改过什么，简单记一笔。出问题时能快速回滚到上一个可用组合。

什么情况下别硬接本地模型

本地接入不是默认更优解，它换来的是数据不出内网和调用链路自主，代价是运维责任落到自己头上。下面几种情况，硬上往往得不偿失。

• 团队没人能盯服务器，也没人愿意处理显存占满、进程被杀、重启后模型没拉起来这类状况，运维成本会远超本地化带来的收益。
• 并发忽高忽低、峰值差距大的业务。本地显存是固定的，很难弹性应对波峰，本地跑日常流量、峰值切到线上通道的混合方案往往更稳。
• 合规要求并不强制数据不出内网时，先算一笔总账再决定。硬件、电费、维护时间都算进去，再和按量调用对比。具体单价口径到站内的价格追踪页面按当时数字核对。
• 模型迭代快的场景。本地部署的模型更新要自己动手，跟不上上游节奏时，体验落差会一直存在。

反过来，如果数据确实敏感、请求量稳定、有人能兜底运维，本地接入是划算的。判断标准就是这三条同时成立，缺一条就该重新考虑。

先跑通最小闭环，再分类建模型，最后才谈调优——顺序错了，调什么都像在猜。