文档
Ollama 的 OpenAI 兼容 API
Ollama 为本地模型提供 OpenAI 兼容 API。以下介绍如何使用 OpenAI SDK 调用它,以及如何只更改 base_url 和 model,让同一段代码调用托管的 Claude 和 GPT。
Ollama 可在你自己的机器上运行开放模型,并通过 OpenAI 兼容 API 在 http://localhost:11434/v1 提供服务。由于其通信格式与 OpenAI 一致,官方 OpenAI SDK 无需修改即可用于 Ollama;只需更改基础 URL,同一段代码即可调用托管的前沿模型。
http://localhost:11434/v1。将 OpenAI 客户端的 base_url 设置为该地址,并传入任意占位 api_key。若要改用托管的 Claude/GPT,请将 base_url 改为 https://api.kunavo.com/v1,并更改模型标识——其他内容都不变。Ollama 的 OpenAI 兼容 API 是什么
Ollama 是一个独立的开源项目,可在本地运行 Llama、Qwen 和 Mistral 等模型。除了原生 API,它还提供 OpenAI 兼容接口,因此为 OpenAI 构建的工具无需重写即可使用。它实现了大多数应用会用到的端点:
| 端点 | 用途 |
|---|---|
POST /v1/ | 聊天 — 大多数应用使用的端点 |
POST /v1/ | 旧版文本补全 |
POST /v1/ | 本地模型的嵌入 |
GET /v1/models | 列出本地已拉取的模型 |
它支持聊天、补全和嵌入(以及多模态本地模型的视觉输入),但不生成图像、视频或音频。Kunavo 实现了相同的 /v1/chat/completions 契约——该参考文档说明了每个参数、流式增量的格式以及 usage 对象,并附有与 Ollama v1 接口逐行对照的兼容性表。
使用 OpenAI SDK 调用 Ollama
将 base_url 指向 http://localhost:11434/v1。SDK 要求提供 api_key,但本地 Ollama 会忽略其值——传入任意字符串即可。将 model 设置为已拉取的模型(例如 ollama pull llama3.2)。
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:11434/v1", # Ollama's OpenAI-compatible API
api_key="ollama", # required by the SDK, ignored by local Ollama
)
resp = client.chat.completions.create(
model="llama3.2",
messages=[{"role": "user", "content": "Explain quicksort in one paragraph."}],
)
print(resp.choices[0].message.content)也可以使用 curl:
curl http://localhost:11434/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "llama3.2",
"messages": [{"role": "user", "content": "Hello, Ollama"}]
}'同一段代码,调用托管的前沿模型
Ollama 非常适合离线开发和对隐私敏感的工作,但在复杂推理、编程和长上下文方面,本地模型仍落后于前沿模型。由于 Kunavo 也兼容 OpenAI,将调用切换到托管模型只需改两处——base_url 和模型标识:
from openai import OpenAI
client = OpenAI(
base_url="https://api.kunavo.com/v1", # only this line changes
api_key="sk-kn-...", # a real key now
)
resp = client.chat.completions.create(
model="claude-sonnet-5", # a hosted frontier model
messages=[{"role": "user", "content": "Explain quicksort in one paragraph."}],
)
print(resp.choices[0].message.content)| Ollama(本地) | Kunavo(托管) | |
|---|---|---|
| 基础 URL | localhost: | api. |
| 运行位置 | 你的机器 | 托管 API |
| 模型 | 本地开放模型 | Claude、GPT、Veo、Suno |
| 模态 | 文本 + 嵌入 | 文本、图像、视频、音频 |
| 成本 | 你的硬件 / 电力 | 按 token 计费,低于标价 |
| 适用场景 | 离线开发、隐私保护 | 适用于生产环境的前沿模型质量 |
通过环境变量切换
一种常见做法是本地开发时使用 Ollama,生产环境中使用托管模型,并通过环境变量选择。客户端和请求代码完全相同——只有 base_url 和模型不同:
import os
from openai import OpenAI
# One client, switched by environment. Local for dev, hosted for prod.
if os.getenv("APP_ENV") == "production":
client = OpenAI(base_url="https://api.kunavo.com/v1",
api_key=os.environ["KUNAVO_API_KEY"])
MODEL = "claude-haiku-4-5"
else:
client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
MODEL = "llama3.2"
resp = client.chat.completions.create(
model=MODEL,
messages=[{"role": "user", "content": "ping"}],
)
print(resp.choices[0].message.content)常见问题
Ollama 有 OpenAI 兼容 API 吗?
有。Ollama 在 http://localhost:11434/v1 提供 OpenAI 兼容的 REST API,支持 /chat/completions、/completions、/embeddings 和 /models。将官方 OpenAI SDK 的 base_url 指向该地址,api_key 可填写任意字符串(Ollama 在本地会忽略它),并将 model 设为已拉取的模型,例如 llama3.2。请求和响应格式与 OpenAI 一致。
Ollama 的 OpenAI API 使用什么基础 URL?
http://localhost:11434/v1 by default. Set the OpenAI client base_url to that value. If Ollama runs on another host or port, substitute it — the /v1 suffix stays.
如何从 Ollama 切换到托管模型?
两者都兼容 OpenAI,因此只需更改 base_url 和 model。将 http://localhost:11434/v1 替换为 https://api.kunavo.com/v1,使用真实的 sk-kn- 密钥,并将 model 设置为托管模型标识,例如 claude-sonnet-5 或 claude-haiku-4-5。无需更改其他代码。
Ollama 的 OpenAI API 支持图像或视频吗?
Ollama 的 OpenAI 兼容接口支持聊天、补全和嵌入,以及多模态本地模型的视觉输入。它不生成图像、视频或音频。若要通过同一 OpenAI 风格的 API 使用托管图像、视频和音频生成,请使用 Kunavo 的 /v1/images、/v1/video 和 /v1/audio 端点。