⚠️ 待更新·2026-08-29核验 · 更新时间待核验 · 本文信息可能已过期，请以官方文档为准
更新时间：2026-08-29 · 核验状态：待更新 · 官方溯源待补
背景
2023 年以后,几乎每家新模型厂商都在自家 API 里复刻 POST /v1/chat/completions 这条 OpenAI 路径:请求体相同、响应体相同、流式 chunk 相同、错误码也尽量对齐。原因不是 OpenAI 设计最优,而是生态效应——SDK、教程、Prompt 库、Agent 框架都围绕这个协议生长。事实标准的力量大于设计标准,统一网关顺势把它作为出口协议。
核心概念
- 请求归一:不论上游是 Claude、Gemini 还是 Llama,网关统一接受
messages / model / temperature / stream / tools 字段。
- 响应归一:把不同家的
usage、finish_reason、tool_calls 字段名映射到 OpenAI 形状,客户端解析逻辑只写一遍。
- 错误归一:Anthropic 的
overloaded_error、Google 的 RESOURCE_EXHAUSTED 都翻译成 HTTP 429 + OpenAI 错误体。
- 能力探测:用
/v1/models 暴露统一别名,客户端可以列出"哪些模型支持 vision / tool_calls / json_mode"。
代码示例
# 网关里把 Anthropic 响应翻译成 OpenAI 形状
def anthropic_to_openai(resp: dict) -> dict:
return {
"id": resp["id"],
"object": "chat.completion",
"model": resp["model"],
"choices": [{
"index": 0,
"message": {"role": "assistant",
"content": resp["content"][0]["text"]},
"finish_reason": "stop",
}],
"usage": {
"prompt_tokens": resp["usage"]["input_tokens"],
"completion_tokens": resp["usage"]["output_tokens"],
"total_tokens": resp["usage"]["input_tokens"]
+ resp["usage"]["output_tokens"],
},
}
版本演进与兼容性梯度
OpenAI 自己也在快速演进协议,response_format 从 json_object 到 json_schema,reasoning_effort 是 o1/o3 系列独有。网关需要设计兼容性梯度:对客户端暴露最高版本协议(如支持 json_schema),但对上游不支持该字段的老模型,网关自动降级为 prompt 注入(在 system message 里说明"请输出符合以下 JSON Schema 的内容")。这种"协议适配器"模式让客户端永远只看一套最高接口,代价是网关需要维护一份"能力矩阵"映射表。
权衡与最佳实践
- 不是所有字段都能映射:Claude 的
thinking、Gemini 的 safety_settings 没有对应 OpenAI 字段,要么放进 extra_body,要么单独留扩展头。
- 版本锁定:OpenAI 自己也在演进协议(
response_format、reasoning_effort),网关要跟住版本,否则会逐渐漂移。
- 永远保留 escape hatch:网关应允许客户端透传
provider_params 直接打上游原生字段,不要硬封死。
- 能力探测后路由:在
/v1/models 里暴露 supports_tools、supports_vision、supports_json_schema 等旗标,客户端按旗标选模型。
兼容 OpenAI 不是终点,而是为了让客户端"今天写的代码明天还能跑"。
⚠️ Pending Update · 2026-08-29 Verification · Content may be outdated, please refer to official docs
Updated: 2026-08-29 · Status: Pending Verification
Background
After 2023, nearly every new model vendor cloned OpenAI's POST /v1/chat/completions path: same request body, same response body, same streaming chunk shape, same effort to align error codes. The reason is not that OpenAI's design is optimal — it is ecosystem gravity. SDKs, tutorials, prompt libraries, and agent frameworks all orbit this protocol. A de facto standard outweighs a designed one, and the unified gateway adopts it as the egress contract.
Core Concepts
- Request normalization: whether the upstream is Claude, Gemini, or Llama, the gateway accepts
messages / model / temperature / stream / tools.
- Response normalization: maps each vendor's
usage, finish_reason, and tool_calls shapes into the OpenAI form, so clients write parsing logic once.
- Error normalization: Anthropic's
overloaded_error and Google's RESOURCE_EXHAUSTED both translate to HTTP 429 with an OpenAI-style error body.
- Capability probing:
/v1/models exposes unified aliases with flags for vision, tool_calls, and json_mode support.
Code Example
# Inside the gateway: translate an Anthropic response into OpenAI shape
def anthropic_to_openai(resp: dict) -> dict:
return {
"id": resp["id"],
"object": "chat.completion",
"model": resp["model"],
"choices": [{
"index": 0,
"message": {"role": "assistant",
"content": resp["content"][0]["text"]},
"finish_reason": "stop",
}],
"usage": {
"prompt_tokens": resp["usage"]["input_tokens"],
"completion_tokens": resp["usage"]["output_tokens"],
"total_tokens": resp["usage"]["input_tokens"]
+ resp["usage"]["output_tokens"],
},
}
Protocol Evolution and Compatibility Tiers
OpenAI itself keeps evolving the protocol fast: response_format went from json_object to json_schema, and reasoning_effort is exclusive to the o1/o3 family. The gateway needs a compatibility tier: it exposes the latest protocol to clients (supporting json_schema), but for older upstream models that lack the field, it auto-degrades to prompt injection (a system message saying "please output JSON conforming to the following schema"). This "protocol adapter" pattern lets clients see only one top-tier interface; the cost is that the gateway maintains a capability matrix.
Trade-offs and Best Practices
- Not every field maps: Claude's
thinking and Gemini's safety_settings have no OpenAI equivalent — funnel them through extra_body or a dedicated extension header.
- Pin the version: OpenAI itself keeps evolving the protocol (
response_format, reasoning_effort); the gateway must track upstream versions or drift apart silently.
- Always keep an escape hatch: let clients pass
provider_params through to native upstream fields instead of hard-closing them.
- Capability-aware routing: expose
supports_tools, supports_vision, supports_json_schema flags in /v1/models so clients can pick by capability.
OpenAI compatibility is not the destination — it is the strategy that lets "code written today still run tomorrow."