ollama 的 api 端点

用 Ollama 跑通了模型，想写代码接进去时通常会卡在几个地方：默认端口是多少、原生接口和 OpenAI 兼容接口该用哪个、base_url 要不要带 /v1、想调自家或第三方的模型服务时 Key 往哪塞。这篇把接口地址、可用调用方式和排查顺序列成清单，照着对一遍就能跑通最小调用。

用 Ollama 把模型跑通不难，难的是写代码接进去那一脚：默认端口是多少、路径要不要带版本段、原生接口和兼容接口选哪个、换到别家云服务时 Key 塞在哪。这篇文章把接口地址、调用方式和排查顺序列成清单，你照着对一遍就能跑通最小调用。

先声明适用边界：下面讲的是本机常驻服务的调用方式，适合本地开发、内网联调、单机小规模实验。如果要做多用户并发、要暴露到公网、要按量计费结算，思路不一样，那种场景更该去看托管平台的接入文档，而不是直接拿本地服务的地址当生产入口。

先把接口地址和端口列清楚

默认服务地址

服务起来后监听在本地回环地址加一个固定端口，路径以斜杠开头，不带路径前缀就能访问根路由

原生接口

按功能划路径，生成、对话、模型列表、拉取模型、删除模型各自一个入口，返回结构是 Ollama 自己的格式

OpenAI 兼容接口

在原地址后多一层版本前缀，请求与返回尽量贴近主流客户端的约定，主要提供对话与向量等常用能力

base_url

客户端里填的根地址。用兼容接口时要带上那层版本前缀，用原生接口时不带

• 根路由能返回响应，只说明服务活着，不代表兼容层可用，两件事分开验。
• 改了监听地址或端口后，要同时确认服务绑定的是回环还是对外地址，绑回环则局域网内其他机器连不上。
• 跑在容器里时，容器内外的端口映射要对齐，映射漏了会出现「本机通、别机不通」。
• 服务端口被别的程序占用或被顶掉时，进程看着在跑，请求却走不通，先确认监听是否成功。

Python 调用的两条路：官方库与 OpenAI 客户端

第一条路是用官方 Python 库，默认就连本地服务，换机器只改一个 host 参数，适合把 Ollama 当本地推理后端用。第二条路是继续用你熟悉的 OpenAI 风格客户端，把 base_url 指向兼容层，api_key 在本地服务场景下填个占位串即可，本地服务不校验它。

1. 先确认服务可用用最简请求打一次根地址，确认有正常响应体再往下写。
2. 选调用方式要 Ollama 特有参数就用官方库；已有 OpenAI 代码就改 base_url 走兼容层。
3. 配好地址与模型名地址、模型名、超时都抽成环境变量，换模型和换机器时不动代码。
4. 跑最小对话先发一句短提示拿到完整回复，确认链路通，再开流式输出。
5. 加超时与重试长回答别用默认超时，按任务把超时调大，重试次数设小一点避免重复计费式的浪费。

# 思路示意，路径与参数以站内接口页为准
# 兼容层客户端：base_url 记得带版本前缀
from openai import OpenAI
client = OpenAI(base_url="http://本地地址:端口/v1", api_key="本地占位串")
resp = client.chat.completions.create(model="你的模型名", messages=[{"role":"user","content":"你好"}])
print(resp.choices[0].message.content)

# 官方库：默认连本地服务，换机器改 host
# from ollama import Client
# cli = Client(host="http://本地地址:端口")
# print(cli.chat(model="你的模型名", messages=[{"role":"user","content":"你好"}]))

流式输出这块，两个客户端都支持边生成边返回，做聊天界面时基本都得开。注意开了流式之后，超时判断要按「多久没收到下一个片段」来算，而不是按整个请求的总耗时算，否则长回答会被误判成超时。

接第三方模型与 Key：先分清在哪一层配

这里最容易绕晕。本地服务负责的是本机推理，它不托管别家云上的模型，所以「给 Ollama 设某家 API Key」这个说法本身就容易指错对象。真实需求通常有两种：一种是想让代码既能打本地模型又能打云端模型；另一种是想让本地这层做个统一入口，按模型名把请求分发出去。

• 真要用云端模型，Key 放环境变量或本地不入库的配置文件，别写进代码仓库。
• 如果团队多人共用，别把同一个 Key 散在各自机器上，收口到一处方便轮换和停用。
• 用第三方平台的兼容入口时，先确认它支持的请求字段与本地兼容层是否一致，不一致的部分要单独处理。
• 本地模型和云端模型混用，价格与额度的口径不一样，具体数字到站内价格页面核对当时的情况。
• 别把本地服务的地址配上云端 Key 就当成「Ollama 接了大模型」，这是两件不同的事。

连不上时的排查顺序

按下面这个顺序走，基本能覆盖绝大多数连不上的情况。别一上来就怀疑模型或者 Key，多数问题出在进程、路径前缀和网络这三层。

1. 确认服务在跑看进程是否存在，直接打根地址看有没有响应体。没响应先解决服务本身。
2. 确认端口没被占查监听状态，确认是本服务占着端口，启动日志里如果有绑定失败的提示要处理掉。
3. 确认路径前缀兼容层要带版本前缀，原生接口不带。多一段或少一段版本段是最常见的报错来源。
4. 确认模型存在列一遍本地已有模型，确认你写的模型名和列表里的一致，拼写差一个字符都会报找不到。
5. 确认网络层容器内外映射、局域网跨机、本机代理设置这三处逐个排除；代理有时会把本地请求也拦走。

补充一条容易忽略的：如果你是在同步代码里调异步接口，或者反过来，报错信息往往看起来像服务不可用，其实是客户端用法问题。先拿官方示例原样跑一遍，能区分是环境问题还是自己的代码问题。