大模型统一接口的 API 兼容性，不能只用“请求能够返回结果”来判断。对于部署方，更可执行的做法是建立验收矩阵，将协议、鉴权、参数、错误处理、流式响应和稳定性要求拆成可重复测试的项目，并保留请求、响应与版本记录。
一、先明确验收范围
验收前建议确认以下信息：
- 部署形态：本地、专有云、公有云或混合环境。
- 调用对象：业务系统、智能体平台、开发工具或内部服务。
- 接口范围：文本生成、多轮对话、向量化、模型列表及其他实际需要的接口。
- 调用规模：日常调用量、并发峰值、请求与响应长度。
- 权限要求：租户、项目、应用、用户等隔离层级。
- 稳定性要求：超时、重试、降级、日志留存和故障定位方式。
二、API 兼容性验收矩阵
【1. 协议与基础连接】
验收项：HTTP 方法、请求路径、Content-Type、字符编码、TLS、代理与超时设置。
检查方法：分别执行正常请求、缺少请求头、路径错误、超时和连接中断测试。
通过依据：实际行为与已确认的接口文档一致；异常请求能够返回可识别的状态和信息。
建议留档：接口版本、请求样例、响应样例、网关及客户端日志。
【2. 鉴权与权限边界】
验收项：访问凭证格式、请求头位置、凭证失效、租户或项目隔离、模型访问权限。
检查方法：测试有效凭证、无凭证、失效凭证、无模型权限及跨权限范围调用。
通过依据：合法请求按权限执行；非法或越权请求被拒绝，并返回明确、稳定的错误信息。
建议留档：权限配置、测试角色、错误响应和审计记录。
【3. 请求参数兼容性】
验收项：模型标识、消息结构、采样参数、最大输出长度、停止条件及可选参数。
检查方法：覆盖必填参数缺失、类型错误、边界值、未知字段和不同参数组合。
通过依据：受支持参数按文档生效；不受支持或格式错误的参数有明确处理结果。
建议留档：参数清单、边界值、请求体和实际响应。
【4. 响应结构兼容性】
验收项：响应字段、内容结构、结束原因、用量字段、请求标识和时间字段。
检查方法：比较非流式响应与调用方解析逻辑，并测试空内容、长内容和异常终止场景。
通过依据：调用方能够稳定解析必需字段；字段缺失或结构变化时有可观测的处理机制。
建议留档：字段映射表、解析结果和兼容性差异。
【5. 错误码与异常语义】
验收项：鉴权失败、参数错误、模型不可用、限流、超时及服务异常。
检查方法：构造对应异常，记录 HTTP 状态、业务错误标识、错误信息和是否适合重试。
通过依据：同类异常的返回结构保持一致；调用方可以区分需修正请求、可重试和需人工介入的情况。
建议留档：错误码映射、重试策略、告警规则和样例响应。
【6. 流式响应】
验收项：分片格式、事件边界、增量内容、结束标识、中途断开和客户端取消。
检查方法：验证首个分片、连续分片、正常结束、网络中断、服务端异常和主动取消。
通过依据：客户端能够按顺序解析增量内容，正确识别结束与异常状态，并释放连接资源。
建议留档：完整数据流、客户端日志、断开位置和最终状态。
【7. 超时、重试与幂等处理】
验收项：连接超时、读取超时、整体超时、重试次数、退避策略及重复请求影响。
检查方法：模拟慢响应、短时不可用和连接中断，检查调用方是否按约定重试。
通过依据：超时边界清晰；重试不会形成持续放大；重复调用的业务影响已经评估。
建议留档：超时配置、重试条件、测试时间线和请求标识。
【8. 模型切换与路由】
验收项：模型名称映射、不可用模型处理、路由规则及切换后的字段差异。
检查方法：使用部署范围内计划接入的模型逐项执行相同测试集。
通过依据：模型选择结果可确认；差异项有明确记录，调用方不会因未处理的字段差异直接失败。
建议留档：模型清单、映射关系、差异说明和测试结果。
【9. 可观测性与问题定位】
验收项：请求标识、调用日志、耗时、错误分类、模型路由结果和审计信息。
检查方法：从一次业务请求反查网关及相关服务记录，并验证敏感字段处理方式。
通过依据：部署方能够定位请求路径和失败环节；日志范围应符合企业内部的安全、权限和留存要求。
建议留档：日志字段表、查询方式、权限范围和留存策略。
三、建议的验收结果格式
每个测试项至少记录：用例编号、前置条件、请求样例、预期结果、实际结果、是否通过、差异说明、证据位置、执行人和执行时间。对于尚未确认的兼容项，应标记为“待验证”，不宜直接视为支持。
四、适用边界
这份矩阵适用于部署方在统一 API 平台选型、联调和上线前组织兼容性检查，但不代表任何具体平台已经支持矩阵中的全部能力。实际验收范围应以部署版本、接口文档、目标模型、网络环境和调用方实现为准。模型输出质量、安全策略、数据合规和业务效果需要另设评估项，不能由接口兼容性测试替代。
如需结合部署场景形成具体测试范围，可提交需求，并补充部署场景、调用量、权限层级和稳定性要求，用于开展企业模型网关部署评估。