ollama + langchain 官方文档

你要用 Ollama 起本地模型，再套 LangChain 写应用，结果一搜全是零散博客，官方文档又分散在两边，不知道该先读哪页、哪些参数是关键。这篇不讲完整教程，只给一份文档阅读顺序和排查清单：先确认本地服务通了，再对齐调用层写法，最后按报错类型回查对应文档段落和站内资料。

用 Ollama 拉本地模型、再套 LangChain 写应用，最容易卡在不是代码难，而是文档太散。Ollama 一份、LangChain 一份，两边还各自更新，接口命名时不时对不上，搜出来的博客又常常是过时写法。这篇不教你写完整应用，只给一条阅读顺序和一份排查清单，让你少走弯路。

核心思路就一句：先把本地服务跑通，再对齐调用层写法，最后按报错类型回查文档。顺序错了，你会在 LangChain 的抽象层里绕半天，结果问题其实出在 Ollama 根本没起来。站内 /stacks 里能按技术栈找到对应条目，配合着看更省事。

两份文档先看哪一份、按什么顺序看

别一上来就啃 LangChain 的抽象设计文档，那是给已经跑通的人看的。先跑通 Ollama 侧：本地服务地址能不能访问、模型列表里有没有你要的模型、发一次最简单的请求能不能返回结果。这三件事都不依赖 LangChain，纯命令行或 HTTP 就能验证。

1. 确认 Ollama 服务活着用命令行或直接发一个 HTTP 请求打本地服务，能返回结果再往下走。这一步不通，后面全是白搭。
2. 核对模型名跑一次列出本地模型的命令，把显示的名字原样记下来，后面 LangChain 侧的模型名必须跟它完全一致。
3. 照抄最小示例进 LangChain 文档找它给 Ollama 提供的封装类，照着最小可运行示例抄一遍，先跑通再说。
4. 回头理解参数跑通之后再回头读参数含义，这时候每个参数对应你刚才踩的坑，理解快得多。

如果本地环境反复出问题，别急着改代码。用站内 /tools/speed-test 量一下接口延迟基线，先分清是网络慢还是模型慢，再决定往哪个方向查。

配置里真正要盯的几个字段

很多人调半天，问题就出在两三个字段上。下面这几个是最常出错的，建议逐项对照检查，别跳。

• 模型名必须和本地列表里显示的完全一致，多一个字符都不行。
• 服务地址换环境后要重新确认，端口没映射对就报连接失败。
• 首 token 慢不等于服务挂了，先把超时放宽再判断。
• 温度、上下文长度这类参数，用站内 /ai-dict/category/tips 对照术语再下结论。

这些字段的默认值两边文档不一定写得一样，真拿不准就去站内核对当时的数字，别凭印象改。

跑不起来时的排查顺序

排查最忌讳东改一点西改一点。按固定顺序来，一次只动一个变量，才能定位到真正的问题。

1. 先确认 Ollama 本身活着单独用命令行或 HTTP 请求打一次，能出结果再怀疑 LangChain 层。
2. 按报错类型分流连接类指向服务，模型不存在类指向模型名，参数校验类指向调用写法，三类别混着改。
3. 换最小输入复现把 prompt 砍到一句话，排除是上下文太长或特殊字符导致的问题。
4. 量延迟基线用站内 /tools/speed-test 测接口延迟，区分网络慢还是模型慢，本地地址怎么查看 /ai-dict/category/infra。

这三类报错对应的文档段落不一样，回查时直接跳对应章节，比从头翻一遍快得多。想找现成的工具和指南，站内 /tools 里有目录可以翻。

什么情况别照这套走

这套顺序适合本地单机尝鲜和开发验证。但有些场景它不适用，硬套只会把简单问题搞复杂。

• 要跑高并发或多人共用服务，Ollama 定位是本地单机体验，该看推理框架选型，不是这份文档顺序能解决的。
• 只想要个带界面的聊天框，不必走 LangChain，直接用现成的本地前端更快。
• 团队已有云端调用链路的，先想清楚为什么本地化，否则只是把简单问题复杂化。
• 生产环境要考虑稳定性和并发，本地跑通不等于能上线。

文档只是地图，你本地实际报的错才是路标。