OpenAI-Compatible Endpoint
Same Shape, Different SemanticsOpenAI 兼容端点：请求形状相同，执行语义仍需验证
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 coversOpenAI 兼容通常覆盖什么
At minimum, a compatible service exposes familiar paths, bearer authentication, and selected request or response fields. Some services implement only part of Chat Completions; others also cover embeddings, images, audio, files, batches, Realtime, or the Responses API. OpenAI's current reference treats Responses as a primary surface with its own items, conversations, tools, streaming events, and lifecycle operations, so “supports OpenAI” is no longer a useful yes-or-no claim.
兼容服务至少会暴露熟悉的路径、Bearer 认证以及部分请求或响应字段。有些只实现 Chat Completions 的一部分，另一些还覆盖 Embedding、图像、音频、文件、Batch、Realtime 或 Responses API。OpenAI 当前参考文档把 Responses 作为主要接口，并拥有独立的 Item、Conversation、Tool、流式事件与生命周期操作，因此“支持 OpenAI”已不能用简单的是或否来概括。
Write a workload-specific compatibility manifest. For each endpoint family, list required models, input modalities, structured output, tool choice, parallel calls, streaming event types, state handling, file or image inputs, cancellation, usage fields, request IDs, rate-limit headers, errors, and retention requirements. A service can be compatible for a text chatbot and incompatible for a stateful tool-using agent at the same time.
应建立面向工作负载的兼容性 Manifest。针对每个端点家族，列出所需模型、输入模态、结构化输出、Tool Choice、并行调用、流式事件类型、状态处理、文件或图像输入、取消、用量字段、Request ID、Rate Limit Header、错误与保留要求。同一个服务可能足以兼容文本聊天，却不兼容有状态、会调用工具的 Agent。
Compatibility adapters may rename fields, translate tool schemas, frame streams, normalize errors and map usage. Each transformation is a semantic decision. Defaults and ignored fields are especially dangerous because the request can return HTTP 200 while changing temperature, reasoning, truncation, tool behavior, or output structure. Unsupported required fields should fail clearly rather than disappear silently.
兼容适配器可能重命名字段、转换工具 Schema、封装流、标准化错误并映射用量。每次转换都是语义决策。默认值和被忽略字段尤其危险：请求可能返回 HTTP 200，却改变 Temperature、Reasoning、截断、工具行为或输出结构。不支持的必需字段应明确失败，而不能静默消失。
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切换前证明兼容
Do not test only the happy path with one short prompt. Build golden requests from production traces and redact sensitive content. Include ordinary text, long context, structured output, single and parallel tools, malformed tool arguments, image or file input, streaming interruption, cancellation, timeout, quota exhaustion, unsupported parameters, content-policy rejection, and upstream failure.
不要只用一个短 Prompt 测试成功路径。应从生产 Trace 构建 Golden Request，并先脱敏。测试集要覆盖普通文本、长上下文、结构化输出、单个与并行工具、错误工具参数、图像或文件输入、流式中断、取消、超时、配额耗尽、不支持参数、内容策略拒绝与上游故障。
- Inventory every endpoint, model, feature, provider extension, SDK assumption, and operational dependency.
- Create golden requests and expected invariants for outputs, events, finish reasons, tool arguments, errors, usage, and headers.
- Dual-run the current and compatible endpoints and diff both structure and meaning; review nondeterministic fields with task-level acceptance checks.
- Verify that native provider and request IDs survive translation for support, reconciliation, and incident review.
- Canary by workload and tenant, block on required-invariant regressions, and monitor retry rate, latency, schema failures, and accepted-output quality.
- Keep the original endpoint, configuration, and credentials ready for a tested rollback that does not lose conversation or job state.
- 盘点每个端点、模型、功能、Provider 扩展、SDK 假设与运营依赖。
- 为输出、事件、Finish Reason、工具参数、错误、用量和 Header 建立 Golden Request 与预期不变量。
- 双轨运行当前与兼容端点，同时对比结构与含义；对非确定字段使用任务级验收检查。
- 验证原生 Provider ID 与 Request ID 在转换后仍被保留，便于支持、对账与事故复盘。
- 按工作负载和租户灰度，在必需不变量回归时阻断，并监控重试率、延迟、Schema 失败和有效输出质量。
- 保留原端点、配置与凭证，确保回滚经过测试且不会丢失 Conversation 或 Job 状态。
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。
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.
简单调用有时可以；生产兼容仍需功能与故障路径测试。
不会。覆盖范围因服务、版本、模型与端点家族而异。
不应。请为支持、核对、调试与审计证据保留它们。