OpenAI-Compatible Endpoint
Same Shape, Different Semantics
OpenAI 兼容端点：请求形状相同，执行语义仍需验证
An OpenAI-compatible endpoint accepts a familiar client contract. It can reduce integration work, but compatibility must be proven feature by feature instead of inferred from a base URL swap.
OpenAI 兼容端点接受熟悉的客户端契约，能够降低集成工作量；但兼容性必须逐项验证，不能仅凭更换基础地址（Base URL）推断。
TL;DR
A familiar path and JSON shape describe transport, not complete behavioral parity.
Tools, strict schemas, modalities, streams, context, defaults and limits can vary.
Keep provider request IDs, error fields, usage units and transformations beside normalized data.
Golden tests, dual runs, canaries and rollback turn claimed compatibility into measured compatibility.
熟悉的路径与 JSON 形状描述传输，不代表行为完全一致。
工具、严格结构定义、模态、流、上下文、默认值与限制可能不同。
把供应商请求 ID、错误字段、用量单位与转换记录同标准化数据并存。
Golden 测试、双轨、灰度与回滚把兼容声明变成可测结论。
What OpenAI compatibility usually covers OpenAI 兼容通常覆盖什么
At minimum, a compatible service exposes familiar paths, authentication and request or response fields. Some services implement only chat completions; others also cover embeddings, images, audio, files, batches or the Responses API. The supported surface must be read from the endpoint's current documentation.
兼容服务至少会暴露熟悉的路径、认证以及请求或响应字段。有些只实现 Chat Completions，另一些还覆盖 Embedding、图像、音频、文件、批处理或 Responses API。支持范围必须以当前端点文档为准。
Compatibility adapters may rename fields, translate tool schemas, frame streams, normalize errors and map usage. Each transformation is a semantic decision. Unsupported required fields should fail clearly rather than disappear silently.
兼容适配器可能重命名字段、转换工具结构定义、封装流、标准化错误并映射用量。每次转换都是语义决策；不支持的必需字段应明确失败，而不能静默消失。
Compatibility layers to verify 需要验证的兼容层
| Contract layer 契约层 | Best fit 最适合 | Verify before choosing 选择前验证 |
|---|---|---|
| Transport 传输 | Stable base URL, auth, paths, headers and timeouts. 稳定的基础地址（Base URL）、认证、路径、Header 与超时。 | Check every endpoint family and streaming protocol used in production. 检查生产使用的每个端点家族与流协议。 |
| Request semantics 请求语义 | Messages, tools, schemas, sampling and provider extensions. Message、工具、结构定义、采样与供应商扩展。 | Test defaults, ignored fields, strictness, parallel calls and tokenization. 测试默认值、被忽略字段、严格度、并行调用与 Tokenization。 |
| Response semantics 响应语义 | Outputs, finish reasons, tool arguments and stream events. 输出、结束原因、工具参数与流事件。 | Verify ordering, partial events, finalization, truncation and malformed cases. 验证顺序、分段事件、结束、截断与异常情况。 |
| Errors and retries 错误与重试 | A predictable application error model. 可预测的应用错误模型。 | Map native status, retryability, quota signals and provider IDs without losing detail. 映射原生状态、可重试性、配额信号与供应商 ID，且不丢细节。 |
| Usage and policy 用量与策略 | Comparable operational evidence. 可比较的运营证据。 | Retain native units, billing dimensions, data terms, regions and lifecycle rules. 保留原生单位、计费维度、数据条款、区域与生命周期规则。 |
Define a portable core and explicit extensions 定义可移植核心与显式扩展
List fields and behaviors that must remain identical for a workload to be correct.
Resolve supported features before sending a request, not after a production failure.
Namespace provider-specific features and cover each one with tests and rollback.
Return normalized output plus route, transformations, native IDs, usage and errors.
列出负载保持正确所必需的字段与行为。
发送请求前解析支持的功能，而不是生产失败后才发现。
为供应商特定功能建立命名空间，并配套测试与回滚。
返回标准化输出以及路由、转换、原生 ID、用量与错误。
Prove compatibility before cutover 切换前证明兼容
- Inventory every endpoint, model, feature, extension and operational dependency.
- Create golden requests for simple, streaming, tool, schema and failure paths.
- Dual-run the current and compatible endpoints and diff structure plus semantics.
- Canary by workload and block on required-invariant regressions.
- Keep the original endpoint and credentials ready for tested rollback.
- 盘点每个端点、模型、功能、扩展与运营依赖。
- 为简单、流式、工具、结构定义与故障路径建立 Golden 请求。
- 双轨运行当前与兼容端点，对比结构与语义。
- 按工作负载灰度，并在必需不变量回归时阻断。
- 保留原端点与凭证，确保已验证回滚。
Put capability checks before the adapter 在适配器前执行能力检查
The client sends a canonical envelope with model alias, messages, required capabilities, timeout and trace context. A versioned catalog resolves an eligible endpoint. Only then does a typed adapter translate the request. The response carries canonical fields plus native evidence, so observability and incident review can reconstruct what happened.
客户端发送包含模型别名、Message、所需能力、超时与调用链上下文的规范封装。版本化目录先解析合格端点，类型化适配器随后转换请求。响应同时携带规范字段与原生证据，让可观测与事故复盘可以还原执行过程。
Production rule: never treat a successful HTTP response as proof that required semantics were preserved.
生产规则：绝不能把一次成功的 HTTP 响应当作必需语义已被保留的证明。
Compatibility covers models; QVeris covers capabilities 兼容层覆盖模型，QVeris 覆盖能力
An OpenAI-compatible endpoint standardizes access to inference. QVeris complements it with Discover → Inspect → Call for external APIs, tools, services and live data. Keep shared trace context across both layers so a model decision and the resulting real-world action remain connected.
OpenAI 兼容端点标准化推理访问；QVeris 以 Discover → Inspect → 调用补充外部 API、工具、服务与实时数据能力。两层共享调用链上下文，使模型决策与随后真实世界动作保持关联。
Define the endpoint contract as executable fixtures 把端点契约定义为可执行 Fixture
Use one manifest to declare the behavior the application requires. The preflight runner can then execute the same fixtures against direct providers, gateways, staging, and production without rewriting the test plan.
用一个 Manifest 声明应用真正需要的行为。预检 Runner 随后可对直连供应商、网关、Staging 与 Production 执行相同 Fixture，而无需重写测试计划。
version: 1
endpoint_env: LLM_BASE_URL
model_env: LLM_MODEL_ID
required:
chat: true
streaming: true
tool_calls: true
json_schema: true
usage: [input_tokens, output_tokens]
errors: [401, 404, 429, 500]
limits:
connect_timeout_ms: 3000
request_timeout_ms: 30000
evidence:
- request_id
- native_model_id
- provider
- finish_reason
- usage
- Version the manifest and review changes like an API contract.
- Run it before deployment and periodically against production with non-sensitive prompts.
- Store a redacted result artifact so regressions are attributable.
- 对 Manifest 做版本管理，并像 API 契约一样审查变更。
- 部署前运行，并定期用非敏感提示词检查生产环境。
- 保存脱敏结果 Artifact，使回归问题可追溯。
Verified implementation reference: OpenAI API reference.
实施参考已根据官方资料核验：OpenAI API reference。
Define the Production Contract for an OpenAI-compatible endpoint定义OpenAI 兼容端点的生产契约
For OpenAI-Compatible Endpoint, 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 兼容端点”，协议相似可以降低集成工作量，却不能保证行为等价。应在产品代码与供应商路径之间建立版本化应用契约，让变更保持可测试、可回滚。
Document base path, authentication, model aliases, request fields, server-sent events, structured responses, tools, usage fields, status codes, and cancellation. Mark each item as required, optional, provider-native, or unsupported, and assign an owner for any transformation that changes its meaning.
记录基础路径、认证、模型别名、请求字段、Server-Sent Events、结构化响应、工具、用量字段、状态码和取消。把每一项标记为必需、可选、供应商原生或不支持，并为任何改变语义的转换明确负责人。
To validate OpenAI-Compatible Endpoint, 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 兼容端点”时，为短与长提示词、Unicode、流式、JSON Schema、并行工具、拒绝、取消、畸形输入和限流建立 Fixture，检查必需字段与事件顺序，而不是接受一个看似合理的文本答案。
When operating OpenAI-Compatible Endpoint, 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 兼容端点”时，追踪内部请求 ID、解析后的模型与供应商、模型版本、转换、重试、延迟、Token 类别、成本来源、策略结果和输出校验，在脱敏密钥的同时保留复现失败所需上下文。
Before rolling out OpenAI-Compatible Endpoint, 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 兼容端点”前，运行代表性影子流量，分类语义差异，按可逆工作负载进行金丝雀发布，监控任务完成与长尾行为，并在演练回滚和恢复主路径之前保留原有路由。
FAQ
Sometimes for simple calls. Production compatibility still requires feature and failure-path tests.
No. Coverage varies by service, version, model and endpoint family.
No. Preserve them for support, reconciliation, debugging and audit evidence.
简单调用有时可以；生产兼容仍需功能与故障路径测试。
不会。覆盖范围因服务、版本、模型与端点家族而异。
不应。请为支持、核对、调试与审计证据保留它们。