OpenAI 兼容 API
为什么重要
兼容性消除了切换的大部分成本。为 OpenAI 写的应用、智能体框架或编辑器插件,不用重写代码就能指向本地模型、更便宜的服务商或自托管的服务器。这让比较模型、避免厂商锁定、把工作负载搬到性价比最好的地方都变得容易。
这也是本地工具能与那么多软件开箱即用的原因。任何带有“自定义 OpenAI 端点”设置的应用,都能和 Ollama、LM Studio 或 vLLM 对话。
深度解析
OpenAI 在 2023 年发布 Chat Completions API 之后,它的格式很快成了大多数开发者和工具所面向的格式:向 /v1/chat/completions 发一个 POST 请求,带上模型名称和一个 messages 列表,其中每条消息都有 role(system、user 或 assistant)和 content。其他服务商和开源服务器发现,赢得采用的最简单办法就是接受同样的格式。
结果就形成了一个事实标准。一个“OpenAI 兼容”的服务器说的是这套协议,哪怕背后的模型和 OpenAI 毫无关系。要切换,你只需改客户端里的两项设置:base URL 和 API key。
长什么样
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:11434/v1", # Ollama, or any compatible server
api_key="not-needed-locally",
)
response = client.chat.completions.create(
model="llama3.2",
messages=[{"role": "user", "content": "Explain KV caching in one sentence."}],
)
print(response.choices[0].message.content)
只要改 base_url 和 model,同样的代码就能用在另一台服务器上。
谁支持它
- 本地和自托管服务器:vLLM、Ollama(
localhost:11434/v1)、LM Studio(localhost:1234/v1)、llama.cpp 的服务器和 SGLang。 - 推理服务商:Together AI、Fireworks AI、Groq、Cerebras、DeepSeek、Mistral、xAI 等很多家。
- 聚合平台和网关:OpenRouter 和 LiteLLM 通过一个兼容端点提供数百个模型。
- 其他大型实验室:Google 为 Gemini 提供了 OpenAI 兼容端点,Anthropic 也提供了一个主要用于测试的兼容层。
兼容性在哪里失效
“兼容”通常意味着基础功能可用:消息进、文本出、流式传输。除此之外,要做好有差异的准备。
- 工具调用:格式大体相同,但可靠性、并行调用以及工具参数的流式传输因服务器和模型而异。
- 结构化输出:带 JSON schema 的
response_format,有些服务器支持,有些部分支持,少数直接忽略。 - 推理:思考 token 没有约定的字段。各家服务商把它们放在不同的位置返回,或者干脆不返回。
- 服务商特有功能:提示缓存控制、引用和内置网页搜索往往无法对应到 OpenAI 格式,所以兼容端点暴露的功能比服务商的原生 API 少。
- 参数和错误:不支持的参数可能被悄悄丢弃,token 用量的报告方式可能不同,错误码也不统一。
经验法则:普通聊天可以信任兼容性。任何高级功能,都要针对具体的服务器测试具体的功能;需要某家服务商的全部能力时,就用原生 API。
一个变动中的标准
OpenAI 自己已经往前走了。2025 年,它推出 Responses API 作为推荐接口,带有内置工具和服务器端的会话状态,同时继续支持 Chat Completions。生态里的大部分仍然面向 Chat Completions,不过一些服务器已经开始加入对 Responses 的支持。与此同时,Anthropic 的 Messages API 成了第二种常见格式,一些服务商现在也提供 Anthropic 兼容端点,主要是为了让编程智能体能跑在它们的模型上。
所以,“OpenAI 兼容”最好理解为“会说 Chat Completions”,这是一个短期内不会消失的最大公约数。