第 5 章:本地 API,OpenAI 兼容接口
装好模型只是开始。真正让本地模型有用的是:它能像云 API 一样被代码调用。
学习目标
- 分清 Ollama 的原生接口和 OpenAI 兼容接口,知道各自什么时候用
- 用
curl和 Python 各调通一次本地模型 - 把第 2 层「大模型 API 调用」的代码,只改一个地址就切到本地
- 知道本地服务的鉴权缺口,不在公网上裸奔
5.1 两套接口,一套原生一套兼容
Ollama 同时提供两套 HTTP 接口:
| 原生接口 | OpenAI 兼容接口 | |
|---|---|---|
| 路径 | /api/chat、/api/generate、/api/embed | /v1/chat/completions、/v1/models |
| 报文格式 | Ollama 自己的一套 | 和 OpenAI 完全一致 |
| 流式返回 | 每行一个 JSON(NDJSON) | 标准 SSE,data: ... |
| 适合 | 用 Ollama 专有参数、管理模型 | 复用现成代码、接第三方 SDK |
选哪套的判断很简单:代码已经按 OpenAI 写的,就用兼容接口;要从零写且只用 Ollama,用原生接口。
5.2 先用原生接口问一句
curl http://localhost:11434/api/chat -d '{
"model": "qwen2.5:7b",
"messages": [
{"role": "system", "content": "你是简洁的助手"},
{"role": "user", "content": "什么是 RAG?一句话"}
],
"stream": false
}'返回结构很直白:
{
"model": "qwen2.5:7b",
"message": {"role": "assistant", "content": "RAG 是先从资料里检索相关片段,再让模型基于片段回答。"},
"done": true,
"total_duration": 4821331200,
"eval_count": 38
}total_duration 是纳秒,eval_count 是生成的 token 数——两个数相除就是这一句的实际速度,第 6 章会用到。
管理类接口也顺手记一下:
curl http://localhost:11434/api/tags # 已装模型
curl http://localhost:11434/api/ps # 正在跑的模型5.3 换成 OpenAI 兼容接口
同一件事,换个路径和字段格式:
curl http://localhost:11434/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "qwen2.5:7b",
"messages": [{"role": "user", "content": "什么是 RAG?一句话"}]
}'Python 里用官方 OpenAI SDK:
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:11434/v1", # 只改这一行
api_key="ollama", # SDK 要求非空,Ollama 不校验
)
resp = client.chat.completions.create(
model="qwen2.5:7b",
messages=[{"role": "user", "content": "什么是 RAG?一句话"}],
temperature=0.3,
)
print(resp.choices[0].message.content)这里有个容易踩的坑:api_key 不能省,SDK 会检查它非空。随便填一个字符串就行,Ollama 根本不看这个字段——这也意味着它没有任何鉴权。
5.4 和第 2 层那门课的代码对接
「大模型 API 调用」里写的那个周报生成器,代码结构大概是:
client = OpenAI(base_url="https://api.example.com/v1", api_key=os.environ["API_KEY"])切到本地只动两处:
client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
# 然后把 model 换成 "qwen2.5:7b"messages、temperature、流式读取的写法全都不用变。这就是"OpenAI 兼容"的实际价值:它不是让你多学一套 API,而是让同一套代码能换后端。
反过来也成立:本地调通的代码,把
base_url和api_key换回云端,就能直接上线。第 8 章会讲怎么在两者之间做切换。
5.5 流式的差别要说清
原生 /api/chat | 兼容 /v1/chat/completions | |
|---|---|---|
| 传输格式 | NDJSON,每行一个完整 JSON | SSE,每行 data: {...} |
| 结束标志 | 最后一行 "done": true | data: [DONE] |
| 解析方式 | 逐行 json.loads | 剥掉 data: 前缀再解析 |
用 OpenAI SDK 时不用管这些,stream=True 之后 for chunk in ... 就行。自己写 HTTP 客户端就要注意:别把原生接口当 SSE 解,它没有 data: 前缀。
5.6 一个安全提醒
OLLAMA_HOST 一旦改成 0.0.0.0,同网段任何人访问 11434 都能免费用你的模型、读你的 prompt。它没有 token、没有限流、没有审计。
要在局域网共享,至少做到:
- 只在可信内网开;
- 用 Nginx 之类加一层 Basic Auth;
- 需要对外就套 HTTPS + 独立的 key 校验。
如果只是自己用,保持默认的 127.0.0.1 就够了——这也是最安全的状态。
本章小结
| 要点 | 说明 |
|---|---|
| 两套接口 | 原生 /api/*,兼容 /v1/*,格式不同 |
| 流式差别 | 原生是 NDJSON,兼容是 SSE |
| 切本地 | base_url 换 11434,api_key 随便填 |
| 最大价值 | 同一套代码换后端,不用学两遍 |
| 鉴权现状 | 默认无鉴权,只监听本机 |
| 暴露风险 | 改 0.0.0.0 等于开放接口,必须加一层 |
下一章
接口通了,接下来关心体验:为什么本地模型"想"得比云端慢?为什么同时来两个请求会排队?下一章讲速度、上下文与并发这三件直接影响手感的事。