你本地把模型拉下来了，也能在终端里对话，但一到要把 Ollama 接进自己的脚本、知识库或者编程工具，就开始卡：服务到底监听在哪、走原生接口还是 OpenAI 兼容接口、返回体里哪个字段才是答案、报错该从哪儿查。这篇不抄文档原文，只给你一份能照着做的对接顺序，以及每一层卡住时先看什么。
你本地把模型拉下来了，命令行里也能对话，但一到要接进自己的脚本、知识库或者编程工具，就开始卡：服务到底监听在哪、走原生接口还是那套兼容接口、返回体里哪个字段才是答案、报错该从哪儿查。这篇不抄文档原文，只给你一份能照着做的对接顺序，以及每一层卡住时先看什么。
读官方文档的正确姿势是先建立一个调用链路的心理模型：进程 → 地址 → 端点 → 请求体 → 返回体 → 解析。后面所有问题基本都能挂到这六层里的某一层，而不是「Ollama 又出 bug 了」。下面按对接顺序分段说。
先确认服务在跑，再谈接口
Ollama 装完不是一个常驻云服务，默认只有一个本机监听地址。很多人代码报错的第一反应是改代码，其实一半的坑是服务根本没起或者早就退了。所以顺序一定要倒过来：先用命令行确认进程活着、端口有人听、模型列表里确实有你要的那一个，再去写第一行 HTTP 请求。
- 确认进程与端口在终端看服务进程是否在跑，再用监听端口检查命令看那个端口有没有被占用。如果进程不在，先手动起一次，看到服务就绪的日志再继续。
- 列出本地模型跑一次模型列表命令，把返回的名字原样记下来。代码里写错模型名的报错信息往往很像「模型不存在」，和地址写错的报错容易混。
- 量一次延迟基线用一个最小请求跑几次，记下首次响应和整体耗时。这一步是为了把「服务本身慢」和「你的代码慢」分开。测速口径可以直接参照 接口测速（/tools/speed-test） 里的做法。
- 记一张模型小表把模型名、量化档位、上下文设置记成一张表。换模型出问题时，先对比这张表比翻代码快得多。
原生接口和 OpenAI 兼容接口，先选一条路
Ollama 对外有两套说话方式：一套是它自己原生的接口形态，一套是模仿 OpenAI 的兼容接口。已经写好的 OpenAI SDK 代码通常改一下 base 地址就能接上；新写的单机脚本用原生接口能拿到更贴近 Ollama 自己的字段。选哪条路的判断标准很简单，看你下游要用什么生态。
| 你的场景 | 建议走的路 | 主要理由 |
|---|---|---|
| 现成 SDK、客户端、编排框架 | 兼容接口 | 改动最小，生态里现成的调用代码基本能直接复用 |
| 单机实验、想看原始返回 | 原生接口 | 字段更完整，调试时信息量大 |
| 既要接工具又想做定制 | 兼容为主、必要处再补原生 | 避免一个项目里两套请求体混着写 |
两套接口的参数命名不完全一样，同一个「温度」「上下文长度」在两个体系里可能叫法不同，混用是最常见的低级错误。建议一个项目里只固定一套请求写法，需要另一套时用适配层隔开，别在业务代码里直接切换。另外，切换端点前先看清 base 地址该不该带版本段、该不该带结尾斜杠。路径拼接错会报出一个看起来像「资源不存在」、实际是地址写歪的错。
请求怎么写，返回怎么读
调用模式上先分两种：一次性返回和流式返回。对话类交互一般要流式，否则用户界面会一直转圈；批处理、离线打标一般要一次性，拿完整结果更方便。选错模式不会报错，但体验会很怪，很多人把这当成「接口慢」，其实是模式用反了。
- 返回体里除了正文，还有结束原因、用量统计等字段，脚本里不要只截取正文，否则后面做限流、上下文裁剪、结果日志时无从下手
- 流式返回要处理分片拼接，注意最后一个分片可能不携带正文，只表示结束，别把它当成空回复丢掉
- 结构化输出、工具调用这类高级能力，不同接口形态的支持程度不一致，接之前先用最小请求试一遍，别等业务代码写完才发现拿不到想要的结构
- 把返回体先原样打一份日志再做字段提取，出问题时这份日志能省掉大量猜测
解析层最容易踩的坑是把「字段缺失」当成「模型没返回」。先确认你用的接口形态在当前服务配置下是否真的会带这个字段，再决定代码里要不要兜底。对接早期保留原始响应日志，比事后复现便宜得多。
连不上时的排查顺序
连不上不要东查一下西改一下。固定一个顺序，每层只验证一件事：进程在不在、端口通不通、地址格式对不对、模型名对不对、参数是否合法。跳步排查最容易越查越乱，尤其是把「服务没起」误判成「鉴权失败」这种。
| 现象 | 先查这一层 | 常见原因 |
|---|---|---|
| 直接连接被拒绝 | 进程与端口 | 服务没起、端口写错 |
| 同网段别的机器连不上 | 监听范围 | 本机监听没放开，未必是防火墙 |
| 容器里连不上 | 地址写法 | 地址用了本机回环，容器里指向了自己 |
| 换了客户端就集中报错 | 统一配置项 | 地址、超时、请求头在不同语言里配置不一致 |
有一个例外情况要说明：如果你的请求经过了反向代理或者网关，上面这张表就不完全适用，故障点会多一层转发配置，这时应该先从网关的访问日志看请求有没有进来，再回到本地服务这层查。反过来，纯本机直连的场景下也不该去折腾代理相关配置，那是给自己加变量。
常用能力对应哪些调用
对话、文本生成、嵌入向量、模型列表、拉取与删除模型，各自是不同的入口。不用一股脑把全部端点背下来，先把你要用的那两三个挑出来，其余等真需要时再查文档。查的时候注意文档结构本身也会变，看到和记忆不一致的地方，去 指南中心（/guides） 找对应版本的说明更稳。
- 对话与生成
- 面向会话式交互和单次文本产出，前者要流式，后者常一次性
- 嵌入向量
- 本地知识库的关键，重点看返回维度是否和向量库对齐
- 模型管理
- 拉取、列出、删除，脚本里做环境初始化时常用
- 兼容层
- 给现成 SDK 用的门面，参数命名和原生那套不同
做本地知识库的重点是嵌入接口的返回维度要和你的向量库对齐，对不上会报维度错，这类问题表面看像模型问题，其实是配置问题。对接编排工具或编程工具的，先确认对方要求的是哪套接口形态，再决定本地要不要再套一层转换服务，能不加这层就别加，多一层就多一处出错的地方。
最后提醒一句：接口文档里会随版本更新的细节（具体端点路径、参数默认值、字段名），以及各中转方案当前的实际可用情况，都建议去 站点库（/sites） 和 价格追踪（/price-watch） 核对当时的数字，别拿旧笔记当准。判断标准给你了，剩下的动作就是按上面那个顺序，一层一层走通。
下一步把本机服务状态、延迟基线、你要用的两三个端点先跑通一遍，再去站内对一遍当时的可用方案和数字，比闷头改代码快得多。→常见问题
Ollama 的 API 文档要去哪看，站内有整理吗？
官方文档是唯一权威来源，站内这块主要给的是口径和排错思路，不复制文档原文。想先把术语对齐，可以去 /ai-dict 和 /ai-dict/category/basics 翻一遍；想量接口延迟和稳定性，用 /tools/speed-test。两者配合看，比只读文档更容易定位问题。
为什么我按照文档写了请求，还是报连接失败？
先别改代码。按「服务有没有起、端口有没有在听、地址格式对不对」三步验一遍，多数连接失败是服务没起或者地址写歪了。容器、虚拟机、另一台机器上调用时，回环地址往往不通，要换成实际的监听地址。详细的逐层排查思路可以对照 /tools/speed-test 的做法先量基线。
下游工具要求 OpenAI 格式，本地模型怎么接？
走 Ollama 的兼容接口形态，把客户端里的 base 地址指向本地服务即可，多数现成 SDK 不用改业务代码。但要注意参数命名差异和部分高级能力支持范围，接完先用最小请求跑一遍对话和结构化输出，确认拿得到的字段再往上叠业务逻辑。
