Google AI
用于验证能力差异的 Gemini OpenAI 兼容接口。
协议兼容指南
OpenAI 兼容 API：兼容不等于完全相同
测试 OpenAI 兼容 API 的响应、工具调用、流式输出与错误语义，核对应用所需能力。
On this page
摘要
兼容性有多层
传输、认证、端点路径、JSON 形状、流事件、错误、用量核算与功能行为都可能不同。
测试功能，不测试口号
为 Role、工具、结构化输出、流式、用量、错误、推理控制、图像、文件与音频构建契约测试。
保留供应商出口
当标准化会丢失关键能力时，统一请求应允许供应商特定参数与 Header。
按工作负载迁移
对话 Demo 不能证明智能体、抽取、长流、多模态输入或批处理；应逐负载灰度。
不同供应商类型提供不同兼容保证
OpenAI 原生 API 是参考面；云托管部署、模型市场、托管推理平台、托管网关与自托管代理则实现其中选定部分。有的只提供 Chat Completions，有的还覆盖类似 Responses、Embedding、图像、音频或批处理。
兼容可能是原生、转换或模拟。原生端点也会因模型而异；转换可统一常见字段，但可能重塑错误或流事件；模拟可能接受参数却不保留行为。可靠答案只能来自针对具体模型与端点的版本化一致性测试。
常见 OpenAI-Compatible 供应模式
| 供应模式 | 最适合 | 选择前验证 |
|---|---|---|
| OpenAI 原生 API | 面向原始端点与最新第一方语义的应用。 | 固定端点、模型与 API 行为；即使第一方模型在工具、推理、模态与限制上也不同。 |
| Azure OpenAI | 需要 Azure 身份、网络、区域部署、治理与商业协同的企业。 | 验证 API 版本、Deployment Name、区域模型可用性、限额、内容过滤与错误语义。 |
| OpenRouter | 在统一 OpenAI 风格接口后提供广泛托管模型/供应商选择与路由控制。 | 逐模型/供应商验证端点、参数支持、来源、隐私、用量、错误与计费行为。 |
| LiteLLM 代理 | 跨多供应商的自托管转换，结合网关策略、密钥、预算与路由。 | 承担适配更新，并测试透传、流式、工具、结构化输出、错误、用量与供应商扩展。 |
| Bifrost 网关 | 自托管统一 API 与 Go 技术栈，包含供应商路由、回退与运行控制。 | 测试具体协议端点、模型功能、流事件、治理规则、集群行为与升级节奏。 |
| 托管推理平台 | 直接托管开放或专有模型，通常提供 OpenAI 兼容聊天 路径。 | 检查兼容是否仅覆盖对话，还是还覆盖工具、结构化输出、多模态、Embedding、文件、批处理与错误。 |
| 托管 AI 网关 | 通过一个端点增加路由、预算、可观测性、回退与供应商凭证。 | 区分协议兼容与产品 SDK 兼容，并检查转换和供应商特定出口。 |
八项保真检查覆盖主要迁移风险
Role 与内容
System、Developer、User、Assistant、工具 Message；文本、图像、文件、音频 Part；顺序与截断。
工具调用
工具结构定义限制、Choice 控制、并行调用、参数 JSON、调用 ID、流式 Delta 与结果关联。
结构化输出
JSON Mode 与结构定义强制、未支持关键字、拒绝形状、部分输出与验证错误。
流式
事件类型、顺序、Role Delta、Finish Reason、用量时机、Keepalive、断连与流中错误。
用量与计费
提示词、Completion、Reasoning、缓存、工具 Token；原生/标准化计数；请求 ID 与计价单位。
错误与重试
HTTP Code、错误类型、可重试性、限流 Header、超时、安全拒绝、部分计费与幂等性。
创建供应商一致性测试套件
- 为每个生产端点、模型、功能与故障路径保存 Golden 请求与预期不变量。
- 让同一请求数据通过直连与兼容端点，对比 JSON 字段、流事件、工具调用、错误与用量。
- 测试未知参数、供应商扩展、大型结构定义、长上下文、无效工具、断连与限流。
- 按日期、API 版本、模型修订、供应商端点、区域与网关版本记录结果。
- 关键不变量回归时阻止部署；不得静默丢字段或降级行为。
使用规范契约与显式适配器
定义应用真正需要的最小规范请求与响应。让供应商适配器类型化并版本化，记录转换、不支持字段与默认替换。为原生参数暴露出口，但放在能力标记后；统一标识和证据字段，但不要假设所有模型共享同一语义功能集。
生产规则：接受相同 JSON 形状只是接口兼容；在成功与失败下都保留行为才是生产兼容。
协议兼容不等于能力发现
OpenAI-Compatible API 标准化模型推理访问；QVeris 位于不同边界，让智能体发现、检查并调用外部 API、工具、服务与实时数据。QVeris 能力契约可以使用任意底层协议，同时暴露与任务相关的结构定义与证据。
运行兼容性矩阵，而不是单个 Hello World
端点即使接受 /chat/completions，也可能在工具 Argument、结构化输出、流式 Frame、用量计费、错误或取消方面不兼容。应使用小型可重复测试套件，并为每次结果记录准确端点版本。
最小 HTTP 探针
curl --fail-with-body --max-time 20 "$LLM_BASE_URL/chat/completions" -H "Authorization: Bearer $LLM_API_KEY" -H "Content-Type: application/json" -H "X-Trace-ID: compat-$(date +%s)" -d '{
"model": "'"$LLM_MODEL_ID"'",
"messages": [{"role":"user","content":"Reply COMPAT_OK"}],
"stream": false,
"max_completion_tokens": 16
}'- 为工具、JSON 结构定义、流式、长上下文和无效输入增加独立 Fixture。
- 对照契约比较状态码、错误体、请求 ID、准确模型、Finish Reason 与用量。
- 必需字段消失时阻止发布，即使文本生成仍然成功。
实施参考已根据官方资料核验：OpenAI Chat Completions 参考。
常见问题
OpenAI-Compatible 是什么意思？
通常表示服务接受一个或多个 OpenAI 风格端点或 SDK 模式；支持的功能与行为子集必须有文档并经过测试。
只改基础地址（Base URL）可以吗？
简单对话有时可以；生产迁移还需验证模型 ID、密钥、参数、工具、流、错误、用量与重试行为。
哪个兼容供应商最好？
应按所需模型、区域、功能、数据条款、路由、可靠性、支持与实测保真度选择，而非只看目录大小。
应保留供应商直连客户端吗？
在兼容层证明完整负载保真度前，应为关键原生功能、事故隔离与回滚保留直连客户端。