文档

文档

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,同一段代码即可调用托管的前沿模型。

简要说明 — Ollama 的 OpenAI API 位于 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/chat/completions聊天 — 大多数应用使用的端点
POST /v1/completions旧版文本补全
POST /v1/embeddings本地模型的嵌入
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(托管)
基础 URLlocalhost:11434/v1api.kunavo.com/v1
运行位置你的机器托管 API
模型本地开放模型Claude、GPT、Veo、Suno
模态文本 + 嵌入文本、图像、视频、音频
成本你的硬件 / 电力按 token 计费,低于标价
适用场景离线开发、隐私保护适用于生产环境的前沿模型质量
在 Kunavo 上使用一把密钥即可访问所有托管模型,费用统一从一个预付余额中扣除——首次调用请参阅快速入门。

通过环境变量切换

一种常见做法是本地开发时使用 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 端点。

接下来