AIMLAPI
用于检查 Schema、流式响应与工具调用的 OpenAI 兼容端点。
兼容契约详解
OpenAI 兼容端点：逐项验证功能
验证 OpenAI 兼容端点的模型、请求格式、流式事件和错误行为，再决定是否接入生产流量。
On this page
摘要
兼容是一层表面
熟悉的路径与 JSON 形状描述传输，不代表行为完全一致。
能力仍由端点决定
工具、严格结构定义、模态、流、上下文、默认值与限制可能不同。
保留原生证据
把供应商请求 ID、错误字段、用量单位与转换记录同标准化数据并存。
测试生产负载
Golden 测试、双轨、灰度与回滚把兼容声明变成可测结论。
OpenAI 兼容通常覆盖什么
兼容服务至少会暴露熟悉的路径、Bearer 认证以及部分请求或响应字段。有些只实现 Chat Completions 的一部分，另一些还覆盖 Embedding、图像、音频、文件、Batch、Realtime 或 Responses API。OpenAI 当前参考文档把 Responses 作为主要接口，并拥有独立的 Item、Conversation、Tool、流式事件与生命周期操作，因此“支持 OpenAI”已不能用简单的是或否来概括。
应建立面向工作负载的兼容性 Manifest。针对每个端点家族，列出所需模型、输入模态、结构化输出、Tool Choice、并行调用、流式事件类型、状态处理、文件或图像输入、取消、用量字段、Request ID、Rate Limit Header、错误与保留要求。同一个服务可能足以兼容文本聊天，却不兼容有状态、会调用工具的 Agent。
兼容适配器可能重命名字段、转换工具 Schema、封装流、标准化错误并映射用量。每次转换都是语义决策。默认值和被忽略字段尤其危险：请求可能返回 HTTP 200，却改变 Temperature、Reasoning、截断、工具行为或输出结构。不支持的必需字段应明确失败，而不能静默消失。
需要验证的兼容层
| 契约层 | 最适合 | 选择前验证 |
|---|---|---|
| 传输 | 稳定的基础地址（Base URL）、认证、路径、Header 与超时。 | 检查生产使用的每个端点家族与流协议。 |
| 请求语义 | Message、工具、结构定义、采样与供应商扩展。 | 测试默认值、被忽略字段、严格度、并行调用与 Tokenization。 |
| 响应语义 | 输出、结束原因、工具参数与流事件。 | 验证顺序、分段事件、结束、截断与异常情况。 |
| 错误与重试 | 可预测的应用错误模型。 | 映射原生状态、可重试性、配额信号与供应商 ID，且不丢细节。 |
| 用量与策略 | 可比较的运营证据。 | 保留原生单位、计费维度、数据条款、区域与生命周期规则。 |
定义可移植核心与显式扩展
必需不变量
列出负载保持正确所必需的字段与行为。
能力发现
发送请求前解析支持的功能，而不是生产失败后才发现。
类型化出口
为供应商特定功能建立命名空间，并配套测试与回滚。
证据封装
返回标准化输出以及路由、转换、原生 ID、用量与错误。
切换前证明兼容
不要只用一个短 Prompt 测试成功路径。应从生产 Trace 构建 Golden Request，并先脱敏。测试集要覆盖普通文本、长上下文、结构化输出、单个与并行工具、错误工具参数、图像或文件输入、流式中断、取消、超时、配额耗尽、不支持参数、内容策略拒绝与上游故障。
- 盘点每个端点、模型、功能、Provider 扩展、SDK 假设与运营依赖。
- 为输出、事件、Finish Reason、工具参数、错误、用量和 Header 建立 Golden Request 与预期不变量。
- 双轨运行当前与兼容端点，同时对比结构与含义；对非确定字段使用任务级验收检查。
- 验证原生 Provider ID 与 请求标识 在转换后仍被保留，便于支持、对账与事故复盘。
- 按工作负载和租户灰度，在必需不变量回归时阻断，并监控重试率、延迟、Schema 失败和有效输出质量。
- 保留原端点、配置与凭证，确保回滚经过测试且不会丢失 Conversation 或 Job 状态。
在适配器前执行能力检查
客户端发送包含模型别名、Message、所需能力、超时与调用链上下文的规范封装。版本化目录先解析合格端点，类型化适配器随后转换请求。响应同时携带规范字段与原生证据，让可观测与事故复盘可以还原执行过程。
生产规则：绝不能把一次成功的 HTTP 响应当作必需语义已被保留的证明。
兼容层覆盖模型，QVeris 覆盖能力
OpenAI 兼容端点标准化推理访问；QVeris 以 Discover → Inspect → 调用补充外部 API、工具、服务与实时数据能力。两层共享调用链上下文，使模型决策与随后真实世界动作保持关联。
把端点契约定义为可执行 Fixture
用一个 Manifest 声明应用真正需要的行为。预检 Runner 随后可对直连供应商、网关、Staging 与 Production 执行相同 Fixture，而无需重写测试计划。
兼容性 Manifest
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- 对 Manifest 做版本管理，并像 API 契约一样审查变更。
- 部署前运行，并定期用非敏感提示词检查生产环境。
- 保存脱敏结果 Artifact，使回归问题可追溯。
实施参考已根据官方资料核验：OpenAI API 参考。
常见问题
兼容只需更换基础地址（Base URL）吗？
简单调用有时可以；生产兼容仍需功能与故障路径测试。
是否包含所有 OpenAI 端点？
不会。覆盖范围因服务、版本、模型与端点家族而异。
应丢弃原生 ID 吗？
不应。请为支持、核对、调试与审计证据保留它们。