本地模型跑起来了，可一到 LangChain 里就连不上，或者 Dify 里填了地址却报模型不存在——这类问题多半不是模型的问题，而是接口地址、模型名、容器网络这三处口径没对齐。这篇按「先确认 Ollama 对外是谁、再决定谁去连它」的顺序，把 LangChain 与 Dify 两条接入路径的配置项、报错对照和验证步骤列一遍，让你少在猜错误信息上花时间。
本地模型跑起来了，一到 LangChain 里就连不上，或者 Dify 里填了地址却报模型不存在——这类问题多半不是模型坏了，而是接口地址、模型名、容器网络这三处口径没对齐。这篇按「先确认 Ollama 对外是谁、再决定谁去连它」的顺序，把两条接入路径的配置项、报错对照和验证步骤列一遍。
先划清范围：这篇只讲接入和排查，不讲选型、不讲硬件账。你的本地模型如果是新装的，建议先到 /tools/speed-test 用最简请求确认它本身能出字，再来折腾框架侧；否则你可能在两个变量上同时猜。
先把 Ollama 暴露成「别人能连的东西」
动手前先做一个决定：走 Ollama 自己的原生接口，还是走它提供的 OpenAI 兼容接口。两条路的地址后缀不一样，模型名的写法也可能有差异，混着试只会让错误信息互相干扰。先定一条，后面所有配置都按同一条口径填。
- 原生接口
- 地址根路径通常就是主机加端口，模型名用 Ollama 里列出来的那个标识
- OpenAI 兼容接口
- 地址后面通常要多一段兼容路径，模型名写法可能和原生不完全一致，两条别混用
- 默认只监听本机：宿主机以外的进程或容器直接连不上，要么改监听地址，要么让调用方跑在同一网络命名空间里
- 端口不是唯一变量：防火墙、云主机安全组、Docker 端口映射任一处没通，现象都一样是连接超时，别只盯着 Ollama 配置
- 验证动作：改完在另一台机器或容器里用命令行请求一次，看是否能拿到返回，而不是只看进程还在不在
- 如果中间有反向代理，确认它有没有把长连接或流式响应截断，本地推理首字慢，容易被误判成卡死
LangChain 侧：连接参数与调用验证
初始化客户端时，把 base_url 和模型名当成两个独立参数分别确认。模型名要写成 Ollama 里实际存在的那个标识，写错只会得到找不到模型的报错，而这个报错和连不上是完全不同的两类问题，别混在一起查。
- 第一步：最小纯文本调用先只发一次纯文本补全，不加链、不加检索。跑通说明接入层是好的。
- 第二步：显式设置超时与最大生成长度本地推理首字延迟偏大，默认超时下看起来像卡死。把这两项显式写出来，再看行为是否变化。
- 第三步：再逐层加编排链、检索、工具一个一个加，每加一层跑一次。链路一长，出错时你无法判断是接入层还是编排层。
- 第四步：开流式单独验一次流式和一次性返回走的代码路径不同，分开验证，别等到上应用才发现流式被中间层截断。
Dify 侧：容器网络与模型配置
Dify 常以容器方式部署，这是最容易翻车的地方：配置里的 localhost 指向的是容器自己，不是宿主机。你把宿主机地址填成 localhost，连通性测试必然失败，而且还容易误以为是模型服务的问题。
| 场景 | 填什么更稳 | 容易踩的坑 |
|---|---|---|
| Dify 在容器、Ollama 在宿主机 | 宿主机在容器网络里的可达地址 | 填 localhost 连的是容器自己 |
| 两者都在容器 | 放进同一自定义网络，用服务名互连 | 默认网桥下容器名不通 |
| Ollama 在另一台机器 | 那台机器的可达地址 | 安全组没放行，表现为超时 |
| 本地开发和线上共用一套配置 | 按环境分开，别硬编码 | 换环境后地址失效 |
- 在模型供应商里选本地/Ollama 类型还是 OpenAI 兼容类型，决定了地址格式和是否需要补一个占位密钥，两种填法不要混用
- 先点测试连通，再建应用：这两步的报错含义不同
- 应用里报错多半是提示词或上下文长度，模型配置页报错才是接入问题
- 如果配的是兼容接口，确认路径后缀没漏，少一段就是另一条错误信息
报错的排查顺序（照着走，别跳步）
跳步是最浪费时间的做法。下面这个顺序的作用是：每走一步，就把一半的可能性排除掉，而不是同时改三处配置再看结果。
- 一、宿主机直连在宿主机上用命令行直接请求接口，确认模型本身能出字。这一步不通，就别往下查框架。
- 二、换环境再请求同一地址从调用方所在环境（容器内或另一台机器）请求同一地址，区分「服务不通」还是「网络不通」。
- 三、回到框架配置页此时才动 LangChain 或 Dify 的配置。前三步都通了还报错，通常落在模型名大小写、兼容接口路径、上下文长度超出这几处。
- 四、留一份最小复现把出错的地址、模型名、请求体记下来，换个框架试同一个请求。同一份请求两边都不通，说明问题在最底层，不在框架。
什么时候这条路不适用
接得通不等于该这么用。下面几种情况，硬套本地 Ollama 接入的收益很低，早点换路子反而省事。
- 需要高并发、多卡并行或生产级吞吐时，本地这套更适合做开发和验证环节，正式服务换推理框架更合适
- 依赖平台专有能力的功能（特定工具调用格式、特定多模态输入）未必能在兼容接口里原样还原，接入前先用最小样例验一遍，别等上线才发现
- 团队里没人能碰宿主机和容器网络时，直接在 Dify 或 LangChain 里配远程托管模型，比自己搭这一套更稳
- 合规或数据不能出内网的场景另说：这个约束优先，接入方式要围着它选
数据别凭印象判断，比如各家接口的稳定性、延迟体感、哪些中转站更值得托付，这些都随时间变。要看数字就去看站内当时的口径，别抄别人文章里的旧值。
下一步如果你的问题正好卡在网络和地址口径上，去站内看看同类环境的配置对照和连通性自查清单，按你的部署形态对号入座；如果你还没决定本地还是托管，先看价格与延迟的横向页再动手。→常见问题
LangChain 连 Ollama，用原生接口还是 OpenAI 兼容接口？
看你要不要复用现成的 OpenAI 风格代码。想少改代码、链里已经有 OpenAI 客户端写法，就用兼容接口；只做最简单的一次性调用，原生接口的参数字段更少、报错更直白。两种方式对模型名的写法和地址后缀不一样，先定一种，别在同一份配置里混着填。
Dify 里填了 Ollama 地址还是连不上，最可能是哪里？
先看 Dify 是不是跑在容器里。容器内的 localhost 指向容器自身，不是跑 Ollama 的宿主机，这是最常见的原因。改成宿主机在容器网络中的可达地址，或者把两者放同一网络再试。如果改用兼容接口，别忘了一个占位密钥，有时是密钥字段空了导致请求被拒。
接入成功后回答很慢，是接入方式的问题吗？
多数不是。本地推理的首字延迟本来就比云端高，尤其模型加载后的第一次请求。先确认是不是首次调用，再把流式输出打开、把超时调大，观察是「很慢」还是「看起来卡住其实在出字」。如果连续多次都慢且和并发无关，再回到显存与量化档位那边找原因。
