本机 ollama serve 跑起来了，但除了在终端敲 ollama run，你还想用代码、curl 或现成客户端去调它，这时候最容易卡在两件事上：不知道有哪些接口、不知道请求体该长什么样。这篇按用途把接口分成几组，给一份能照着敲的调用清单，顺带说清哪些情况不该用它。
本机 ollama serve 跑起来了，但除了在终端敲 ollama run，你还想用代码、curl 或现成客户端去调它，这时候最容易卡在两件事上：不知道它到底暴露了哪些接口，以及请求体里那几个字段该写什么。把这两件事分开解决，先认路径再认 body，会顺很多。
这篇按用途把接口分成几组，给一份能照着敲的调用清单，顺带说清哪些情况下本地服务其实不该硬扛。文里不写死任何模型名、参数默认值和数字，凡是会随版本变的东西，都建议你到站内页面核对当时的实际情况。
先确认服务跑起来、端口在哪
调不通十次里有六次是服务压根没在你要的地址上监听。ollama serve 默认只绑本机回环地址，环境变量 OLLAMA_HOST 改的是监听这一层，而不是客户端要连的那一层，这两个概念混了就会一直连 localhost 连不上远程机。
- 服务是否在跑：用进程列表或服务管理命令确认，别只看终端里上一次 run 有没有关掉；
- 监听地址与端口：先看默认回环地址，确认没有被 OLLAMA_HOST 覆盖过；
- 探活方式：挑一个不需要模型、只确认服务在的轻量请求，先排除网络层问题；
- 远程访问：想从别的机器连，要显式把监听地址放开，同时想清楚谁能访问到这台机器；
- 日志位置：不同系统上服务是常驻还是随命令拉起，日志落在哪，先找到它再排错
接口按用途分四组，先记分组再记路径
Ollama 的本地接口路径数量不多，但硬背容易混。按用途分成四组记，每组里再分「读」和「写」，回忆成本会低很多。具体路径拼写和字段名，建议到站内模型资料库里对着当时的文档核一遍，接口偶尔会增补。
| 分组 | 典型用途 | 关心什么 |
|---|---|---|
| 模型管理组 | 列出本地已有模型、查看某个模型的详情参数 | 返回里哪些字段能反映量化方式和上下文能力 |
| 生成组 | 一次性返回的生成接口与逐块返回的对话接口 | 请求体结构差别、stream 字段取值 |
| 嵌入组 | 把文本转成向量 | 输入是单条还是批量、返回维度怎么读 |
| 运维组 | 拉取、删除、复制模型 | 与命令行子命令的对应关系，别在脚本里重复实现 |
判断标准很简单：如果你要的是「把一段话变成结果」，看生成组；要的是「把一段话变成向量拿去检索」，看嵌入组；要的是「管理本地有哪些模型」，看管理和运维组。分错组会让请求体怎么改都不对。
三种常见调用方式与最小请求体
最小请求体的核心就几件事：用哪个模型、给什么输入、要不要流式。先用非流式把链路跑通，再改流式，能避免把读取代码的 bug 误判成服务问题。
- curl 先打一发带 Content-Type 发 JSON，body 里只填模型名和输入，stream 先设成关闭。看返回是不是一整段 JSON，能返回就说明服务和模型都认了。
- Python 再打一发用 requests 发同样的 body，把状态码和响应文本打出来。这一步只验证网络与序列化，不碰流式解析。
- 切到流式把 stream 打开，逐行读响应体并拼接，注意每块是独立 JSON 行而不是整体。读完再判断内容是否完整。
- 换 OpenAI 兼容路径如果你用的是现成的 OpenAI 客户端，base_url 要填到兼容层那一段，模型名填本地模型名。本地模型名和云端模型名不通用，别直接拿云端名字套。
# 非流式最小请求示意，把模型名和输入换成你自己的\ncurl http://127.0.0.1:11434/api/generate \\\n -H 'Content-Type: application/json' \\\n -d '{"model":"你的本地模型名","prompt":"说一句你好","stream":false}'哪些情况不适用：如果你要的是多轮对话带会话状态、工具调用或结构化输出，原生生成接口能做的有限，得看兼容层或换客户端；如果只是本地脚本跑批处理，反而原生接口更省事，不必为了统一而套兼容层。
超时、并发与参数：本地服务最容易忽略的几项
本机推理吃的是显存和内存，不是网络带宽。并发上来之后，表现通常是延迟一路升高、请求排在队里，而不是直接报错，所以超时和并发要一起看。
- 并发：同时发几个生成请求要自己压着数，超过机器承受量只是排队，不会给你明确报错；
- 超时：连接超时和读取超时要分开设，长文本生成的读取超时要单独放大，否则会被截断；
- 上下文：输入超出模型能力时的表现各版本不同，要么报错要么静默截断，先在小输入上验证再放大；
- 输出长度：在请求参数里限制输出上限，比事后截字符串更省算力；
- 采样参数：温度这类参数别全局写死，问答、摘要、抽取对它的需求不一样，分任务配
判断标准：如果单请求能通、并发上去就慢，是排队不是接口坏；如果单请求就超时，先查模型是否已经加载进内存，冷启动第一次本来就慢。
调不通时的排查顺序
按「连不上 → 连上但模型不在 → 模型在但字段不对 → 字段对但结果不对」这个顺序走，每一步只改一个变量，别跳步。跳步的结果是你以为修好了，其实只是换了个错。
- 分层定位先看是连接被拒、还是返回模型不存在、还是返回参数校验失败。三种错对应三个方向，不要混着改。
- 最小非流式复现关掉 stream，用最短输入复现一次。能通说明问题在流式读取代码，不通才继续查服务侧。
- curl 与代码对照同一台机器上各试一次。curl 通、代码不通就是环境和依赖问题；都不通就是服务或参数问题。
- 换端口换机器还失败就换端口或换一台机器再试，仍然失败时回头看服务日志，而不是继续调请求体。
常见问题
Ollama 的接口和 OpenAI 的接口是不是一套？
不是一套，但 Ollama 提供了 OpenAI 兼容路径，所以现成客户端大多能直连。原生路径请求体和响应字段自成一套，功能上更贴本地服务；兼容路径胜在生态通用。两者混用时，最容易出问题的就是 base_url 该不该带版本段，建议先各跑通一个最小请求再决定走哪条。
调用本地接口要不要配 API Key？
默认监听本机时通常不用。一旦把服务监听地址放开到局域网或公网，就不该再裸奔，前面要加一层鉴权或反向代理。判断标准很简单：只有你自己这台机器访问，可以省；任何其他人或另一台机器能访问，就必须补上。
本地接口响应慢，是接口写法有问题吗？
多数时候不是，是模型和硬件决定的。先看首字延迟和吐字速度分别多少，再判断是加载模型慢、还是生成慢、还是请求排队。如果同一模型在命令行里也慢，说明瓶颈在推理而不是接口调用层，优化方向应该放到模型规格、量化档位和并发控制上。
