OpenAI 兼容接口到底兼容什么?为什么能调用不代表完全兼容?
OpenAI 兼容接口沿用 OpenAI 的路径和格式,SDK 能直接调用,但只保证基础请求能对上,参数、工具调用、流式、Usage、错误码和模型能力都可能与原生接口不同。文章从 12 个兼容点逐项列出差异,并附了原生与兼容端点的对比表、切换前的 10 项检查清单和三段示例代码。结论是:快速比较模型时用兼容接口,Agent、工具调用、复杂多模态或依赖供应商特有能力时,优先原生协议,并且切换前要实测。
OpenAI 兼容接口(OpenAI-compatible API)指第三方服务沿用 OpenAI 的路径、请求和响应格式,让 OpenAI SDK 能直接调用。它保证基础格式能对上,不保证参数、工具调用、流式事件、Usage、错误码和模型能力与原生接口一致。调通一次文本请求,只说明基础 HTTP 和 JSON 能对得上。
一、OpenAI 兼容接口是什么
OpenAI 兼容接口是事实上的约定,不是标准规范。vLLM、LiteLLM、New API 等项目把模型暴露成同样的格式,调用方只需改 base_url 和 api_key。
兼容分四层:SDK 兼容指能发请求并解析返回;协议兼容指 URL、请求体、响应体和 SSE 格式能解析;功能兼容指参数、工具调用和结构化输出行为一致;模型能力兼容指推理、视觉与原模型相当。前两层容易做到,后两层取决于上游模型。OpenAI-compatible 也不等于官方服务,账单、数据路径和限流由提供方决定。
术语:Base URL 是请求路径前缀,Endpoint 是具体端点,Token 是计量单位,Usage 是用量统计,SSE(Server-Sent Events)是分块推送的流式协议,Tool Calling 即早期的 Function Calling,Structured Output 指按 JSON Schema 输出。
二、OpenAI 兼容到底兼容哪些东西
按请求顺序列出。
1. Base URL 与 Endpoint。 原生 SDK 默认 base_url 为 https://api.openai.com/v1,SDK 在后面追加 chat/completions。本文模拟服务中,去掉 /v1 或写成 /v1/v1 都返回 404(openai 3.49.0 源码)。
2. 鉴权。 OpenAI 用 Authorization: Bearer,Anthropic 用 x-api-key,SDK 自动处理。key 能否跨协议、跨模型使用,由网关的分组规则决定。
3. 请求体。 Chat 用 messages,Responses 用 input 和 instructions。只实现 Chat 的服务不接受 Responses 请求体。
4. 角色。 Chat 的 role 含 developer、system、tool,兼容层对 developer 的映射各异。
5. 参数。 max_completion_tokens 是 openai 3.49.0 推荐的输出上限,max_tokens 标为 deprecated。LiteLLM 文档说明,不支持的参数默认报错,开启 drop_params 后则丢弃。
6. 响应字段。 兼容实现可能缺 usage 或返回 null。LiteLLM Issue #45586(2026-10-09,open)报告,上游无 usage 时返回 prompt_tokens=0,与真实的 0 无法区分。
7. SSE 流式。 Chat 的增量在 choices[].delta 中,以 data: [DONE] 结束。兼容层可能不一致:python-genai Issue #2868(2026-08-17 创建,open)报告,同一请求流式返回 stop,非流式返回 tool_calls。
8. Tool Calling。 原生用 tools 声明函数,结果用同一 id 的 tool 消息回传。差异在 tool_choice 和流式增量:vLLM Issue #64433(2026-10-29,已关闭)报告 none 时两个前端行为不同;LiteLLM Issue #44029(2026-10-01,已关闭)报告经 /v1/messages 流式调用时并行工具调用被合并。
9. 结构化输出。 Chat 用 response_format,Responses 用 text.format,Anthropic 用 output_config.format。LiteLLM PR #49696(2026-11-02,已关闭)修复的是 Bedrock 上 json_schema 与 Claude thinking 同时设置时的处理。
10. 多模态。 Chat 有 image_url、input_audio,Responses 有 input_image,Anthropic 用 image、document 块。音视频取决于上游模型。
11. Usage。 Chat 用 prompt_tokens,Responses 用 input_tokens,Anthropic 另有缓存字段。LiteLLM Issue #33688(2026-07-17 创建,已关闭)报告,非流式 /v1/responses 的日志缺少 token 字段。
12. 错误。 openai 3.49.0 按状态码映射异常类,如 400 为 BadRequestError。兼容服务的错误体可能不同,同为 400 可能是字段、模型名或分组问题,要记录 message 原文。
三、为什么接口能调用,功能却不一定正常
1. 参数不支持。 LiteLLM PR #43982(2026-10-01)让部分 gpt-5.6、gpt-6 通道改发 max_completion_tokens,PR #36857(2026-08-14)为 Azure gpt-5-chat 部署改了参数名。参数名随模型和通道变化。
2. 字段映射。 LiteLLM Issue #21193(2026-02-14,已关闭)报告,经 Responses 桥接访问 ChatGPT Codex 时,user、temperature 等参数被原样传给上游并报错。
3. 工具调用。 LiteLLM 的 PR #50467(2026-11-06,open)为接受 Responses 的扁平 allowed_tools,修改了 Chat 的 tool_choice 校验,需用多轮工具调用测试。
4. 流式与模型能力。 流式问题见第二部分第 7 项。模型的推理、上下文和视觉能力因模型而异,需按模型实测。
四、OpenAI 兼容接口与原生 API 有什么区别
Responses API 与 Chat Completions 是两个端点,请求结构和流式事件都不同。"OpenAI 兼容接口"通常指 Chat 格式。"未核实"表示本次没有可靠依据。
| 维度 | OpenAI Responses | OpenAI Chat | Anthropic Messages | Gemini 原生 | OpenAI 兼容层 |
|---|---|---|---|---|---|
| Endpoint | /v1/responses | /v1/chat/completions | /v1/messages | /v1beta/models/{model}:generateContent | 多为 /chat/completions |
| 鉴权 | Bearer | Bearer | x-api-key | x-goog-api-key(未核实) | 多为 Bearer |
| 请求 | input、instructions | messages | 顶层 system,max_tokens 必填 | contents、parts | 随实现 |
| 响应 | output_text | choices[].message | content 内容块 | candidates(未核实) | 常为 choices |
| Streaming | response.* 事件 | data: 与 [DONE] | message_start 等事件 | 未核实 | usage 位置不一 |
| Tool Calling | 顶层 tools | tools、tool_calls | input_schema、tool_use | 未核实 | 映射为 tool_calls |
| Structured Output | text.format | response_format | output_config.format | 未核实 | 取决于 schema 子集 |
| 多模态 | input_image | image_url | image、document 块 | responseModalities(某中转网关文档示例) | 图片较常见 |
| Usage | input_tokens | prompt_tokens | 含缓存字段 | usageMetadata(同上) | 可能缺失或为 0 |
| 特有功能 | store、previous_response_id | n、logprobs | thinking、cache_control | 未核实 | 取决于实现 |
OpenAI 与 Anthropic 的字段名来自各自 SDK 的类型定义。Gemini 端点来自某中转网关文档与 New API README。
五、切换 API 时应检查哪 10 项
文档核查只说明供应商声称支持什么;代码静态检查只看代码和配置;真实请求验证才是实测,要记录日期、模型和样本数。
| 检查项 | 方法 | 预期 | 风险 | 核查 |
|---|---|---|---|---|
| 1. Endpoint | 核对路径与版本前缀 | 与文档一致 | 404,或请求到错误服务 | 文档、静态 |
| 2. 鉴权 | 用最小请求测试 key 与分组 | 返回 200 | 401、403,或模型不可用 | 文档、真实 |
| 3. Model ID | 对照供应商模型列表 | 完全一致 | 静默路由到其他模型 | 文档、真实 |
| 4. 请求字段 | 逐字段测试 | 报错,或可见地丢弃 | 静默丢弃改变行为 | 静态、真实 |
| 5. 参数语义 | 核对 max_tokens、temperature 取值 | 长度与随机性符合预期 | 输出被截断 | 文档、真实 |
| 6. 普通文本 | 固定问题多次请求 | 字段齐全 | 空响应被当作成功 | 真实 |
| 7. Streaming | 流式与非流式各测一次 | 结束原因和文本一致 | 解析器提前结束 | 真实 |
| 8. Tool Calling | 多轮调用,检查 id 与并行调用 | id 对应,参数为合法 JSON | 工具被跳过或重复 | 真实 |
| 9. JSON 与多模态 | 真实 schema、图片、文件各测一次 | 通过校验,图片被识别 | 模态被丢弃 | 真实 |
| 10. Usage 与错误 | 对照账单,按状态码分类 | 用量可对账 | 账单对不上,重试放大成本 | 文档、真实 |
"文档"指文档核查,"静态"指代码静态检查,"真实"指真实请求。
三组示例代码
示例一调用原生 Responses API,示例二调用第三方 OpenAI-compatible 端点(model 填供应商文档中的 ID,不一定与 OpenAI 模型名相同),示例三调用 Anthropic 原生 SDK。依赖为 pip install openai anthropic(验证版本 openai 3.49.0、anthropic 2.7.0),运行需要真实环境变量。本地模拟服务验证:三段代码能运行;示例二的 base_url 缺 /v1 或重复 /v1 时返回 404。
示例一:OpenAI SDK 调用原生 Responses API
import os
from openai import OpenAI
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
resp = client.responses.create(model=os.environ["OPENAI_MODEL"], input="一句话解释 SSE。")
print(resp.output_text, resp.usage.input_tokens, resp.usage.output_tokens)
示例二:OpenAI SDK 调用第三方 OpenAI-compatible 端点
import os
from openai import OpenAI
# base_url 含版本前缀,SDK 在其后追加 chat/completions
client = OpenAI(base_url=os.environ["LLM_BASE_URL"], api_key=os.environ["LLM_API_KEY"])
r = client.chat.completions.create(
model=os.environ["LLM_MODEL"],
messages=[{"role": "user", "content": "一句话解释 SSE。"}],
max_completion_tokens=256,
)
print(r.choices[0].finish_reason, r.choices[0].message.content, r.usage) # usage 可能为 None
示例三:Anthropic 原生 SDK 调用 Messages API
import os
from anthropic import Anthropic
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
msg = client.messages.create(
model=os.environ["ANTHROPIC_MODEL"],
max_tokens=512, # 必填
messages=[{"role": "user", "content": "一句话解释 SSE。"}],
)
print(msg.stop_reason, msg.content[0].text, msg.usage.input_tokens, msg.usage.output_tokens)
六、什么时候用兼容接口,什么时候用原生协议
| 场景 | 建议 | 理由 |
|---|---|---|
| 快速对比多个模型 | 兼容接口 | 同一 SDK 切换模型,先排除工具调用和流式差异 |
| 已有 OpenAI SDK 应用迁移 | 兼容接口先跑通,再逐项核对 | 改动最小,流式、usage、错误处理要单测 |
| AI Agent 与工具调用 | 原生协议优先 | tool id、并行调用和流式增量最易出错 |
| 复杂多模态应用 | 原生协议优先 | 内容块和异步任务接口更完整 |
| 依赖供应商特有能力 | 原生协议 | 如 thinking、缓存控制,兼容层常不映射 |
| 企业多模型统一接入 | 统一入口,关键业务保留原生协议用例 | 减少 SDK 维护,能力表需按模型维护 |
七、多协议接入怎么看
一个网关和一套密钥能覆盖多种 SDK,少维护多份接入代码。要同时调用 Claude、GPT 和 Gemini 原生接口,可先看 灵眸 AI 接入协议文档(2026-11-10 核对)。文档写明,同一把 sk- 密钥可用于三种入站协议,能调用的模型由密钥所在分组决定。
多协议网关的边界与前文一致:映射深度因网关而异,接入前要逐项测试。上游在海外时,请求经海外通道转发,合规团队要评估哪些数据能经 API 发送。国内站与国际站的模型范围也可能不同。
八、常见问题
OpenAI 兼容接口是什么意思? 沿用 OpenAI 接口格式、SDK 能直接调用的第三方接口,功能未必相同。
OpenAI Compatible API 就是 OpenAI API 吗? 不是。账单、数据路径和模型范围由服务方决定。
Claude API 可以使用 OpenAI SDK 吗? 取决于服务端是否提供 OpenAI 格式端点,兼容页本次未能核实。
Gemini API 支持 OpenAI 兼容接口吗? 本次未能打开 Google 官方页面,兼容入口未核实。社区 Issue #2868 显示兼容层结果不一致。
OpenAI 兼容接口能直接使用 Function Calling 吗? 基础调用多能跑通,tool_choice 和并行调用要单测。
为什么修改 Base URL 后仍然返回 400? 400 多来自请求体或分组权限,地址拼错时路径不存在,网关常返回 404。
不同服务商的 OpenAI 兼容接口一样吗? 不一样,字段名相同但默认值和支持范围可能不同。
OpenAI 兼容接口是否支持图片输入? 多数支持,但取决于上游模型的视觉能力。
使用兼容接口会损失模型原生能力吗? 可能,兼容层通常只映射常用字段。
企业接入多个大模型应该选兼容接口还是原生协议? 统一入口接入,关键路径保留原生协议测试。
参考资料
官方技术文档与 SDK
- openai 3.49.0、anthropic 2.7.0、google-genai 3.0.0(2026-11-10 核对)
- Anthropic 文档索引(OpenAI SDK 兼容页未能打开)
开源项目文档
- LiteLLM:Drop Unsupported Params(2026-11-09 更新)
- New API README(2026-11-10 读取)
开发者社区案例
- 第二、三部分引用的 10 条 GitHub Issue 与 PR,只说明存在该类问题,不能推断普遍比例。