跳到主要内容
Zubnet AI › 学习 › Wiki › OpenAI 兼容 API
基础设施

OpenAI 兼容 API

别名:OpenAI-Compatible API、OpenAI 兼容接口、OpenAI 兼容端点、Chat Completions API
一种照搬 OpenAI Chat Completions 端点请求和响应格式的 API,让现有的 OpenAI 客户端代码只需更换 base URL 就能用于其他模型。

为什么重要

兼容性消除了切换的大部分成本。为 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”,这是一个短期内不会消失的最大公约数。

← 所有术语
ESC