Ollama OpenAI 兼容

Ollama 实现了一个子集的 OpenAI API。这意味着现成的 OpenAI SDK 和客户端通常能直接改个 base_url 就跑起来，但也意味着不是所有 OpenAI 功能都可用。

版本基线 v0.40.12，官方 docs.ollama.com/api/openai-compatibility。

一、Base URL

二、最快跑通（云端）

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 请求：

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

云端限制：不支持有状态 Responses、不支持通过 /v1/responses 的内置联网搜索、不支持自定义/自由格式的 tool-call replay。

三、本地跑通

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)

api_key 这个字段必填但没有意义——OpenAI SDK 内部的校验要求它非空，Ollama 直接忽略。填 ollama 只是便于识别。

四、支持的端点

/v1/chat/completions 能力

支持：对话、流式、JSON 模式、可复现输出（seed）、视觉、工具调用、思考控制、logprobs。

支持的请求字段：model、messages（文本/图片/内容数组）、frequency_penalty、presence_penalty、response_format、seed、stop、stream、stream_options.include_usage、temperature、top_p、max_tokens、tools、tool_choice、reasoning_effort、reasoning.effort、logit_bias、user、n。

关于思考控制

reasoning_effort 和 reasoning.effort 控制模型的思考输出。取值因模型而异——用 /api/show 查某个模型支持哪些命名档位和默认值。

• 使用元数据解析档位的模型：支持的名称精确生效，不支持的名称回落到模型默认
• 仅支持布尔开关的模型：识别到兼容档位就映射为 true，"none" 请求 false
• 没有元数据的模型：沿用兼容别名，"minimal" → "low"，"xhigh"/"ultra" → "max"
• GPT-OSS 保持它自己的 OpenAI 兼容转换："minimal" 用 "low"，"xhigh"/"ultra" 用 "high"，"none" 不输出思考

/v1/completions 注意点

prompt 目前只接受字符串，不支持数组。这是个不小的限制——老代码里传 token 数组的会失败。

/v1/models 注意点

• created 字段对应的是模型最后修改时间
• owned_by 对应 Ollama 用户名，默认是 "library"

五、两个常见适配需求

客户端写死了 gpt-3.5-turbo 这类名字

用 ollama cp 把现有模型复制成那个名字：

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 API 没有设置上下文大小的字段——这是协议本身的缺口。解决办法是改 Modelfile：

FROM <某个模型>
PARAMETER num_ctx <上下文大小>

ollama create mymodel

然后用 mymodel 这个名字调用即可。

六、兼容边界

动手试

## ① 确认 /v1 端点活着
curl http://localhost:11434/v1/models

## ② 用 OpenAI 形态调一次
curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"gemma4","messages":[{"role":"user","content":"hi"}]}'

第二条返回结构里有 choices 数组，就说明走的是 OpenAI 兼容层而非原生 API。