接入统一 API 前，建议先做一轮接口兼容性验收
企业已有内部系统或应用需要接入统一 API 时，不能只确认“请求能够发送”。接口路径、鉴权方式、字段定义、流式返回和错误结构中的任一差异，都可能带来调用方改造。
以下检查清单可用于梳理兼容范围，并形成可复测的验收记录。
一、先明确兼容基线
验收前，应固定作为对照的接口规范和调用方范围：
- 当前系统使用哪些接口路径和版本？
- 使用哪种鉴权方式，请求头有哪些固定字段？
- 调用方依赖哪些请求参数、响应字段和错误码？
- 是否包含流式输出、工具调用、多模态输入或结构化输出？
- 哪些现有应用、SDK、脚本和自动化任务需要保持兼容？
“OpenAI 兼容接口”需要进一步拆分到具体端点、字段和行为，不能只依据接口名称判断。
二、核对请求格式
建议使用现有业务请求样本逐项检查：
- API 地址、路径和版本前缀是否一致；
- HTTP 方法及 Content-Type 是否一致；
- 模型名称如何填写，是否需要建立名称映射；
- messages、temperature、max_tokens 等实际使用字段如何处理；
- 未识别字段是忽略、拒绝，还是返回明确错误；
- 可选参数的默认值是否会改变原有调用结果；
- 图片、文件或其他输入的格式与大小边界如何定义。
不要只用最小请求完成验收。应从现有调用日志或测试用例中选取有代表性的请求，但需先移除敏感数据。
三、核对鉴权与连接方式
需要确认调用方当前采用的鉴权格式、凭证传递位置和更新机制，并检查代理、证书、域名解析及网络出口要求。若内部系统依赖固定请求头、IP 策略或特定 TLS 配置，也应纳入验收。
测试材料中应使用专用测试凭证，并按企业安全要求保存和轮换。
四、验证普通返回与流式返回
非流式调用应核对状态码、响应字段、结束原因和用量字段。流式调用则需检查：
- 是否采用调用方能够解析的事件格式；
- 数据分片及结束标记如何表达；
- 连接中断、超时和客户端取消时如何处理；
- 空响应、异常分片和提前结束是否会触发调用方错误；
- 网关、反向代理和客户端的超时配置是否匹配。
流式连接成功不等于解析兼容，建议对完整事件序列进行记录和比对。
五、单独验收扩展能力
如果业务使用工具调用、结构化输出或多模态输入，应分别建立测试用例。重点核对字段层级、参数序列化、返回顺序、结束状态以及异常结构。未在当前业务中使用的能力，可以记录为非本次验收范围，避免将接口规范中的全部能力默认视为部署要求。
六、验证错误处理
兼容性问题经常出现在异常路径。建议至少覆盖：
- 鉴权失败；
- 模型名称无效；
- 参数类型或字段值不符合要求；
- 请求体过大或上下文超出限制；
- 请求超时、连接中断及上游异常；
- 调用频率或配额触发限制。
除 HTTP 状态码外，还要检查错误体字段、错误信息格式，以及现有系统能否正确分类、记录和重试。重试策略需要结合幂等性及业务容错要求单独评估。
七、形成兼容性验收矩阵
验收记录建议包含：调用方、接口端点、测试场景、请求样本编号、预期结果、实际结果、差异说明、改造责任方和复测状态。最终将项目分为“直接兼容”“需要配置映射”“需要调用方改造”和“不在本次范围”，便于评估接入成本。
适用边界
这份清单适用于统一 API 接入前的技术核对，不代表任何具体网关与特定 SDK、模型服务或业务系统天然兼容。实际兼容范围仍需以拟部署版本的接口文档、模型服务规范、网络环境和真实测试结果为准。性能容量、可用性目标和数据合规属于独立评估项，不应由接口格式测试直接推导。
准备接入前，可先整理现有系统的接口格式、鉴权方式、返回结构及调用方清单，再查看部署资料，建立兼容性验收范围。
