把 SDK 的 base_url 换成另一个地址，通常可以让最简单的聊天请求跑起来，但这不代表应用已经兼容。不同供应商可能对模型别名、系统消息、工具参数、流式事件、错误结构和 token 限制有不同解释。真正的迁移成本往往在边界条件，而不是第一条成功响应。
先测请求和响应的基本形状
检查鉴权头、组织或项目字段、模型名、消息角色、空内容、图片输入和最大 token 参数。响应侧要记录 id、created、model、choices、finish_reason、usage 和错误字段是否存在，类型是否稳定。不要因为客户端没有报错就认为字段可用，很多业务逻辑会依赖这些字段做计费和状态判断。
流式和工具调用最容易出现差异
流式接口可能使用不同事件类型、结束标记和 usage 位置；有的实现会把工具调用参数拆成增量片段，有的则一次性返回。客户端如果只按文本 delta 拼接，遇到工具事件就可能丢失参数。测试时要覆盖普通文本、并行工具、工具错误、拒答和主动取消。
工具调用还要检查 schema 是否严格执行、未知字段如何处理、工具结果角色是否被接受，以及模型是否会在没有必要时调用工具。兼容接口的“能发出去”不等于“行为相同”，尤其不能把一个供应商的安全策略推断到另一个供应商。
错误与计费也要放进矩阵
至少制造鉴权失败、限流、超时、模型不存在、上下文过长、内容拒答和上游暂时不可用六类错误。记录 HTTP 状态、内部错误码、是否建议重试和是否已经产生费用。对重试策略来说，429 和参数错误的处理完全不同；对账单来说，响应失败也可能已经消耗 token。
在统一入口上，网关可以把供应商差异映射成内部错误分类、模型别名和 usage 结构。使用 top-api.cc 做迁移测试时，建议保留原始响应摘要和映射后的响应，方便判断是上游行为变化还是适配层改写造成的问题。
一份最小兼容矩阵
- 鉴权、组织字段和模型别名；
- 文本、多模态和空内容请求；
- 流式事件、结束原因和 usage；
- 工具 schema、参数增量和工具错误；
- 限流、超时、拒答和上下文超限；
- token 计数、价格字段和账单关联；
- 最大输出、温度、采样和未知参数处理。
兼容性报告最好给出“完全兼容、需要适配、明确不支持”三种结论，并附最小复现请求。这样开发者迁移时知道哪些功能可以直接切换，哪些需要 feature flag 或专用适配器。
参考资料：各供应商的 OpenAI-compatible API 文档、LiteLLM Proxy 和 Portkey Gateway 的适配说明。接口文档会更新，测试结果应标注日期、模型和 SDK 版本。
如果你需要同时管理多个兼容接口和回退策略，可以从 top-api.cc 统一 base_url 开始，但仍要保留自己的兼容矩阵和回归样本。
Leave a Reply