Ollama 的 OpenAI 兼容接口怎么用

把本地模型接进现有 OpenAI 技术栈，最容易的一条路是 Ollama 的 OpenAI 兼容层：官方 SDK 不用改，base_url 换个地址就完事。Ollama 支持的是 OpenAI API 的一个子集，哪些能用、哪些不能用，这篇按端点过一遍 ^[1]。

两种入口

兼容层有云端和本地两种打开方式。云端入口连 Ollama 官方托管服务，机器上连 Ollama 都不用装，API key 设进 OLLAMA_API_KEY、pip 装 openai 客户端即可，base_url 指向 https://ollama.com/v1 ^[1]：

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://ollama.com/v1",
    api_key=os.environ["OLLAMA_API_KEY"],
)

response = client.chat.completions.create(
    model="gemma4:31b",
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
)
print(response.choices[0].message.content)

同一个客户端也支持无状态的 Responses 请求 ^[1]：

response = client.responses.create(
    model="gemma4:31b",
    input="Say hello in one sentence.",
)
print(response.output_text)

云端能力有边界：不支持有状态的 Responses、不支持经 /v1/responses 的内置网页搜索、不支持自定义工具调用的重放 ^[1]。

本地入口则是熟悉的 localhost:11434。有个反直觉的细节：客户端必须要填 api_key 参数，但 Ollama 根本不看这个值——随便填个字符串就行；要经本地服务器用云端模型，得先登录 Ollama 账号 ^[1]。

OpenAI 协议能成为事实标准不是偶然：聊天消息结构、流式增量、工具调用描述这三样覆盖了绝大多数应用形态，把接口收敛到这套格式后，框架层和应用层的代码可以完全复用。兼容层的价值正在于此——本地模型获得了与云端服务同等的接入待遇，切换供应商只需改一个环境变量。工程上常见做法是配置里存多个 base_url，开发用本地、生产按成本和隐私要求选云端或自建。

三种语言，一个协议

Python、JavaScript、curl 三种写法贴在一起看，差异只在客户端构造上 ^[1]：

from openai import OpenAI

client = OpenAI(
    base_url='http://localhost:11434/v1/',
    api_key='ollama',  # required but ignored
)

chat_completion = client.chat.completions.create(
    messages=[
        {
            'role': 'user',
            'content': 'Say this is a test',
        }
    ],
    model='gpt-oss:20b',
)
print(chat_completion.choices[0].message.content)

import OpenAI from "openai";

const openai = new OpenAI({
  baseURL: "http://localhost:11434/v1/",
  apiKey: "ollama", // required but ignored
});

const chatCompletion = await openai.chat.completions.create({
  messages: [{ role: "user", content: "Say this is a test" }],
  model: "gpt-oss:20b",
});

console.log(chatCompletion.choices[0].message.content);

curl -X POST http://localhost:11434/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
  "model": "gpt-oss:20b",
  "messages": [{ "role": "user", "content": "Say this is a test" }]
}'

Responses 端点的本地调用更简单，input 直接是字符串 ^[1]：

from openai import OpenAI

client = OpenAI(
    base_url='http://localhost:11434/v1/',
    api_key='ollama',  # required but ignored
)

responses_result = client.responses.create(
  model='qwen3:8b',
  input='Write a short poem about the color blue',
)
print(responses_result.output_text)

图片走 base64 是本地部署的务实选择：不依赖外网可达性，本地文件直接编码传过去；代价是请求体膨胀，几张高分辨率图就能把请求推到几 MB 量级，超长对话里反复传图时要注意带宽和解析开销。更稳妥的模式是首轮传图、后续轮次用文字引用结论，避免把同一张图反复塞进历史。

端点能力清单

/v1/chat/completions 支持聊天、流式、JSON 模式、可复现输出、视觉、工具调用和思考模型的推理控制；logprobs 不支持 ^[1]。请求字段上要注意三处：消息里的图片只认 base64 编码，不认图片 URL；tool_choice、logit_bias、user、n 都不在支持列表里 ^[1]。

思考控制有两套字段——reasoning_effort 和 reasoning.effort——具体取值因模型而异，用 /api/show 查每个模型支持什么。解析规则也分层：带元数据的模型按名字精确匹配，匹配不到落到默认值；只支持开关的模型把可识别的档位映射成 true、none 映射成 false；没有元数据的模型保留兼容别名，minimal 对 low、xhigh 和 ultra 对 max；GPT-OSS 特殊，minimal 转 low、xhigh 和 ultra 转 high，因为它的思考关不掉 ^[1]。

/v1/completions 支持流式、JSON 模式和可复现输出，字段里多了个 suffix；prompt 目前只接受字符串；best_of、echo 同样不支持 ^[1]。/v1/models 的 created 对应模型最后修改时间，owned_by 是 Ollama 用户名，默认 library ^[1]。/v1/embeddings 收字符串和字符串数组，token 数组不收，dimensions 可以指定 ^[1]。

音频端点是近年新增的：/v1/audio/speech（v0.40.8）用语音模型生成音频，边生成边流式返回，输入上限 4096 字符，输出格式只有 wav（默认）和 pcm，不支持的格式直接返回 400 而不是默默忽略，音频规格是 16-bit 单声道 24kHz ^[1]。/v1/audio/transcriptions 收 WAV 文件，上限 384kHz、512MB、2 小时，超过模型单次处理时长（目前 30 秒）的音频会在停顿处切开逐段转写 ^[1]。/v1/audio/translations（v0.40.12）做语音翻译，to_language 是 Ollama 的扩展字段，默认输出英文 ^[1]。

Responses API（v0.13.3 起支持）只实现无状态形态——previous_response_id 和 conversation 都不支持；字段里有 Ollama 的 think 扩展，接受布尔值、模型自定义字符串或 null ^[1]。

音频端点把 Ollama 的能力面从文本扩展到了语音闭环：speech 生成语音、transcriptions 语音转文字、translations 跨语言转写，三件套覆盖了语音助手和会议记录类应用的基础需求。受限于本地硬件，语音模型的效果与云端服务仍有差距，但隐私敏感场景——医疗、法务、内部会议——本地转写是刚需，这套端点正好补位。

两个适配点

本地推理要先拉模型，云端请求不用——直接用 ollama.com/api/tags 里的标识符，经登录的本地服务器则选 gemma4:cloud 这类云模型 ^[1]：

ollama pull llama3.2

依赖 OpenAI 默认模型名的工具链（写死 gpt-3.5-turbo 的那些）可以用 ollama cp 做个临时别名，零代码改造 ^[1]：

ollama cp llama3.2 gpt-3.5-turbo

curl http://localhost:11434/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "gpt-3.5-turbo",
        "messages": [
            {
                "role": "user",
                "content": "Hello!"
            }
        ]
    }'

另一个绕不开的是上下文长度：OpenAI 协议里没有设置上下文窗口的字段，Ollama 的解法是建一个 Modelfile 写上 num_ctx 参数，再用 ollama create 生成新模型名 ^[1]：

FROM <some model>
PARAMETER num_ctx <context size>

curl http://localhost:11434/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "mymodel",
        "messages": [
            {
                "role": "user",
                "content": "Hello!"
            }
        ]
    }'

这两招覆盖了兼容层最常见的适配需求。剩余的差异——图片 URL、tool_choice、多候选 n——遇到时要么改调用方，要么退回 Ollama 原生 API，选型前对照端点清单核对一遍能省掉后面的大部分排错时间。

本文改编自 Ollama 官方文档的 OpenAI compatibility 一节^[1]，原文以 MIT 许可证发布。