Skip to content

第 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,用原生接口。

你的代码requests / openaiHTTP 127.0.0.1Ollama 服务:11434无鉴权,只听本机加载权重模型进程qwen2.5:7b q4GPU 显存里磁盘4.7 GB 权重首次加载整条链路都在这台机器上:没有 DNS、没有 TLS,也就没有网络抖动。代价是首字延迟取决于"模型在不在显存里"——第一次加载要几秒到几十秒。

5.2 先用原生接口问一句 ​

bash
curl http://localhost:11434/api/chat -d '{
  "model": "qwen2.5:7b",
  "messages": [
    {"role": "system", "content": "你是简洁的助手"},
    {"role": "user", "content": "什么是 RAG?一句话"}
  ],
  "stream": false
}'

返回结构很直白:

json
{
  "model": "qwen2.5:7b",
  "message": {"role": "assistant", "content": "RAG 是先从资料里检索相关片段,再让模型基于片段回答。"},
  "done": true,
  "total_duration": 4821331200,
  "eval_count": 38
}

total_duration 是纳秒,eval_count 是生成的 token 数——两个数相除就是这一句的实际速度,第 6 章会用到。

管理类接口也顺手记一下:

bash
curl http://localhost:11434/api/tags   # 已装模型
curl http://localhost:11434/api/ps     # 正在跑的模型

5.3 换成 OpenAI 兼容接口 ​

同一件事,换个路径和字段格式:

bash
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:

python
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 调用」里写的那个周报生成器,代码结构大概是:

python
client = OpenAI(base_url="https://api.example.com/v1", api_key=os.environ["API_KEY"])

切到本地只动两处:

python
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,每行一个完整 JSONSSE,每行 data: {...}
结束标志最后一行 "done": truedata: [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 等于开放接口,必须加一层

下一章 ​

接口通了,接下来关心体验:为什么本地模型"想"得比云端慢?为什么同时来两个请求会排队?下一章讲速度、上下文与并发这三件直接影响手感的事。

本文阅读--次|全站访问--次|访客--人