OpenAI-Compatible API
Compatible Does Not Mean Identical
OpenAI 兼容 API：兼容不等于完全相同
An OpenAI-compatible base URL can reduce client changes, but behavioral compatibility varies by endpoint, model, provider and feature. Treat the request shape as a starting contract and prove the semantics your application actually uses.
OpenAI-Compatible 基础地址（Base URL）可以减少客户端改动，但行为兼容性会因端点、模型、供应商与功能而变化。应把请求形状视为起始契约，并验证应用实际使用的语义。
TL;DR
Transport, authentication, endpoint paths, JSON shape, stream events, errors, usage accounting and feature behavior can each differ.
Create contract tests for roles, tools, structured output, streaming, usage, errors, reasoning controls, images, files and audio.
A normalized request should allow vendor-specific parameters and headers where critical capability would otherwise be lost.
A chat demo is not evidence for agents, extraction, long streams, multimodal input or batch jobs. Canary each workload separately.
传输、认证、端点路径、JSON 形状、流事件、错误、用量核算与功能行为都可能不同。
为 Role、工具、结构化输出、流式、用量、错误、推理控制、图像、文件与音频构建契约测试。
当标准化会丢失关键能力时，统一请求应允许供应商特定参数与 Header。
对话 Demo 不能证明智能体、抽取、长流、多模态输入或批处理；应逐负载灰度。
Provider types offer different compatibility guarantees 不同供应商类型提供不同兼容保证
The original OpenAI API is the reference surface, while cloud-hosted deployments, model marketplaces, hosted inference platforms, managed gateways and self-hosted proxies implement selected parts of that surface. Some expose Chat Completions only; others also implement Responses-like, embeddings, images, audio or batches.
OpenAI 原生 API 是参考面；云托管部署、模型市场、托管推理平台、托管网关与自托管代理则实现其中选定部分。有的只提供 Chat Completions，有的还覆盖类似 Responses、Embedding、图像、音频或批处理。
Compatibility can be native, translated or emulated. Native endpoints still vary by model. Translation can normalize common fields but reshape errors or streams. Emulation may accept a parameter without preserving its behavior. The only reliable answer is a versioned conformance suite against exact models and endpoints.
兼容可能是原生、转换或模拟。原生端点也会因模型而异；转换可统一常见字段，但可能重塑错误或流事件；模拟可能接受参数却不保留行为。可靠答案只能来自针对具体模型与端点的版本化一致性测试。
Common OpenAI-compatible provider patterns 常见 OpenAI-Compatible 供应模式
| Provider pattern 供应模式 | Best fit 最适合 | Verify before choosing 选择前验证 |
|---|---|---|
| OpenAI reference API OpenAI 原生 API | Applications targeting the original endpoint and newest first-party semantics. 面向原始端点与最新第一方语义的应用。 | Pin endpoint, model and API behavior; even first-party models differ in tools, reasoning, modalities and limits. 固定端点、模型与 API 行为；即使第一方模型在工具、推理、模态与限制上也不同。 |
| Azure OpenAI Azure OpenAI | Enterprises needing Azure identity, networking, regional deployment, governance and commercial alignment. 需要 Azure 身份、网络、区域部署、治理与商业协同的企业。 | Validate API versions, deployment names, regional model availability, limits, content filters and error semantics. 验证 API 版本、Deployment Name、区域模型可用性、限额、内容过滤与错误语义。 |
| OpenRouter OpenRouter | Broad hosted model/provider selection behind one OpenAI-style interface with routing controls. 在统一 OpenAI 风格接口后提供广泛托管模型/供应商选择与路由控制。 | Verify each model/provider endpoint, supported parameters, provenance, privacy, usage, error and billing behavior. 逐模型/供应商验证端点、参数支持、来源、隐私、用量、错误与计费行为。 |
| LiteLLM Proxy LiteLLM 代理 | Self-hosted translation across many providers with gateway policy, keys, budgets and routing. 跨多供应商的自托管转换，结合网关策略、密钥、预算与路由。 | Own adapter updates and test pass-through, streaming, tools, structured output, errors, usage and provider extensions. 承担适配更新，并测试透传、流式、工具、结构化输出、错误、用量与供应商扩展。 |
| Bifrost Gateway Bifrost 网关 | Self-hosted unified API and Go stack with provider routing, failover and operational control. 自托管统一 API 与 Go 技术栈，包含供应商路由、回退与运行控制。 | Test exact protocol endpoints, model features, stream events, governance rules, cluster behavior and upgrade cadence. 测试具体协议端点、模型功能、流事件、治理规则、集群行为与升级节奏。 |
| Hosted inference platforms 托管推理平台 | Direct hosted access to open or proprietary models, often with an OpenAI-compatible chat path. 直接托管开放或专有模型，通常提供 OpenAI-Compatible Chat 路径。 | Check whether compatibility covers only chat or also tools, structured output, multimodal, embeddings, files, batches and errors. 检查兼容是否仅覆盖对话，还是还覆盖工具、结构化输出、多模态、Embedding、文件、批处理与错误。 |
| Managed AI gateways 托管 AI 网关 | One endpoint adding routing, budgets, observability, fallbacks and provider credentials. 通过一个端点增加路由、预算、可观测性、回退与供应商凭证。 | Distinguish protocol compatibility from product SDK compatibility; inspect transformations and provider-specific escapes. 区分协议兼容与产品 SDK 兼容，并检查转换和供应商特定出口。 |
Eight fidelity checks catch most migration failures 八项保真检查覆盖主要迁移风险
System, developer, user, assistant and tool messages; text, image, file and audio parts; ordering and truncation.
Tool schema limits, choice controls, parallel calls, argument JSON, call IDs, streaming deltas and tool-result correlation.
JSON mode versus schema enforcement, unsupported keywords, refusal shape, partial output and validation errors.
Event types, ordering, role deltas, finish reasons, usage timing, keepalives, disconnects and mid-stream errors.
Prompt, completion, reasoning, cache and tool tokens; native versus normalized counts; request IDs and price units.
HTTP codes, error types, retryability, rate-limit headers, timeout, safety rejection, partial charge and idempotency.
System、Developer、User、Assistant、工具 Message；文本、图像、文件、音频 Part；顺序与截断。
工具结构定义限制、Choice 控制、并行调用、参数 JSON、调用 ID、流式 Delta 与结果关联。
JSON Mode 与结构定义强制、未支持关键字、拒绝形状、部分输出与验证错误。
事件类型、顺序、Role Delta、Finish Reason、用量时机、Keepalive、断连与流中错误。
提示词、Completion、Reasoning、缓存、工具 Token；原生/标准化计数；请求 ID 与计价单位。
HTTP Code、错误类型、可重试性、限流 Header、超时、安全拒绝、部分计费与幂等性。
Create a provider conformance suite 创建供应商一致性测试套件
- Capture golden requests and expected invariants for every production endpoint, model, feature and failure path.
- Run the same payload through direct and compatible endpoints; diff JSON fields, stream events, tool calls, errors and usage.
- Test unknown parameters, provider extensions, large schemas, long context, invalid tools, disconnects and rate limits.
- Version results by date, API version, model revision, provider endpoint, region and gateway release.
- Fail the deployment when a required invariant regresses; do not silently drop fields or downgrade behavior.
- 为每个生产端点、模型、功能与故障路径保存 Golden 请求与预期不变量。
- 让同一请求数据通过直连与兼容端点，对比 JSON 字段、流事件、工具调用、错误与用量。
- 测试未知参数、供应商扩展、大型结构定义、长上下文、无效工具、断连与限流。
- 按日期、API 版本、模型修订、供应商端点、区域与网关版本记录结果。
- 关键不变量回归时阻止部署；不得静默丢字段或降级行为。
Use a canonical contract with explicit adapters 使用规范契约与显式适配器
Define the smallest canonical request and response your applications truly need. Keep provider adapters typed and versioned. Record transformations, unsupported fields and default substitutions. Expose an escape hatch for native parameters, but isolate it behind capability flags. Normalize identifiers and evidence fields without pretending that every model shares one semantic feature set.
定义应用真正需要的最小规范请求与响应。让供应商适配器类型化并版本化，记录转换、不支持字段与默认替换。为原生参数暴露出口，但放在能力标记后；统一标识和证据字段，但不要假设所有模型共享同一语义功能集。
Production rule: accepting the same JSON shape is interface compatibility; preserving behavior under success and failure is production compatibility.
生产规则：接受相同 JSON 形状只是接口兼容；在成功与失败下都保留行为才是生产兼容。
Protocol compatibility is not capability discovery 协议兼容不等于能力发现
OpenAI-compatible APIs standardize access to model inference. QVeris operates at a different boundary: an agent discovers, inspects and calls external APIs, tools, services and live data. A QVeris capability contract may use any underlying protocol while exposing task-relevant schema and evidence.
OpenAI-Compatible API 标准化模型推理访问；QVeris 位于不同边界，让智能体发现、检查并调用外部 API、工具、服务与实时数据。QVeris 能力契约可以使用任意底层协议，同时暴露与任务相关的结构定义与证据。
Run a compatibility matrix, not a single hello-world 运行兼容性矩阵，而不是单个 Hello World
An endpoint can accept /chat/completions and still diverge on tool arguments, structured output, streaming frames, usage accounting, errors, or cancellation. Use a small repeatable suite and store the exact endpoint version with every result.
端点即使接受 /chat/completions，也可能在工具 Argument、结构化输出、流式 Frame、用量计费、错误或取消方面不兼容。应使用小型可重复测试套件，并为每次结果记录准确端点版本。
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
}'
- Add separate fixtures for tools, JSON schema, streaming, long context, and invalid input.
- Compare status, error body, request ID, exact model, finish reason, and usage against the contract.
- Fail promotion when a required field disappears, even if text generation still works.
- 为工具、JSON 结构定义、流式、长上下文和无效输入增加独立 Fixture。
- 对照契约比较状态码、错误体、请求 ID、准确模型、Finish Reason 与用量。
- 必需字段消失时阻止发布，即使文本生成仍然成功。
Verified implementation reference: OpenAI Chat Completions reference.
实施参考已根据官方资料核验：OpenAI Chat Completions reference。
Define the Production Contract for an OpenAI-compatible API定义OpenAI 兼容 API的生产契约
For OpenAI-Compatible API, protocol similarity lowers integration effort, but it does not guarantee behavioral parity. Put a versioned application contract between product code and the provider path so change remains testable and reversible.
针对“OpenAI-Compatible API”，协议相似可以降低集成工作量，却不能保证行为等价。应在产品代码与供应商路径之间建立版本化应用契约，让变更保持可测试、可回滚。
Document endpoint surface, message roles, streaming event order, JSON schema behavior, tool-call IDs, finish reasons, usage, tokenization, errors, and unsupported native features. Mark each item as required, optional, provider-native, or unsupported, and assign an owner for any transformation that changes its meaning.
记录端点范围、消息角色、流式事件顺序、JSON Schema 行为、工具调用 ID、Finish Reason、用量、Tokenization、错误和不支持的原生能力。把每一项标记为必需、可选、供应商原生或不支持，并为任何改变语义的转换明确负责人。
To validate OpenAI-Compatible API, create fixtures for short and long prompts, Unicode, streaming, JSON schema, parallel tools, refusals, cancellation, malformed input, and rate limits. Check required fields and event order instead of accepting one plausible text answer.
验证“OpenAI-Compatible API”时，为短与长提示词、Unicode、流式、JSON Schema、并行工具、拒绝、取消、畸形输入和限流建立 Fixture，检查必需字段与事件顺序，而不是接受一个看似合理的文本答案。
When operating OpenAI-Compatible API, trace internal request ID, resolved model and provider, model version, transformations, retries, latency, token classes, cost source, policy result, and output validation. Redact secrets without deleting the context needed to reproduce failure.
运营“OpenAI-Compatible API”时，追踪内部请求 ID、解析后的模型与供应商、模型版本、转换、重试、延迟、Token 类别、成本来源、策略结果和输出校验，在脱敏密钥的同时保留复现失败所需上下文。
Before rolling out OpenAI-Compatible API, shadow representative traffic, classify semantic differences, canary by reversible workload, monitor task completion and tail behavior, and keep the previous route available until rollback and return-to-primary have been rehearsed.
上线“OpenAI-Compatible API”前，运行代表性影子流量，分类语义差异，按可逆工作负载进行金丝雀发布，监控任务完成与长尾行为，并在演练回滚和恢复主路径之前保留原有路由。
FAQ
Usually that a service accepts one or more OpenAI-style endpoints or SDK patterns. The supported feature and behavior subset must be documented and tested.
Sometimes for simple chat. Production migrations also need model IDs, keys, parameters, tools, streams, errors, usage and retry behavior validated.
Choose by required models, regions, features, data terms, routing, reliability, support and tested fidelity—not catalog size alone.
Keep them for critical native features, incident isolation and rollback until the compatible layer proves full workload fidelity.
通常表示服务接受一个或多个 OpenAI 风格端点或 SDK 模式；支持的功能与行为子集必须有文档并经过测试。
简单对话有时可以；生产迁移还需验证模型 ID、密钥、参数、工具、流、错误、用量与重试行为。
应按所需模型、区域、功能、数据条款、路由、可靠性、支持与实测保真度选择，而非只看目录大小。
在兼容层证明完整负载保真度前，应为关键原生功能、事故隔离与回滚保留直连客户端。