迁移准备
先盘点真实请求，不从 SDK 名称推断兼容性
同一个应用可能同时使用普通对话、结构化输出、工具调用和长连接流式响应。迁移前应从生产或预生产样本中整理真实能力清单，并标记哪些行为不能降级。
- 接口与模型记录 endpoint、模型名称、区域、鉴权方式和当前供应渠道。
- 请求结构整理 system 指令、消息内容、附件、工具定义和结构化输出约束。
- 响应行为记录流式事件顺序、停止原因、用量字段、错误类型和重试策略。
- 业务依赖标出应用解析器、超时、幂等、审计和成本统计依赖的字段。
- 回滚入口保留原 endpoint、凭据和配置版本，明确谁可以触发回滚。
协议差异
统一入口不等于所有协议完全相同
LinkyGateway 当前公开的接入范围包括 OpenAI Responses / Chat Completions、Anthropic Messages、Google Interactions / generateContent，以及企业私有模型。每类协议都应以应用真实请求单独验收。
| 检查维度 | 需要核对的行为 | 验收证据 |
|---|---|---|
| 消息 | 角色、内容块、附件和多轮上下文是否保持业务语义 | 同一输入的请求与响应快照 |
| 工具调用 | 工具定义、参数校验、并行调用和结果回传是否完整 | 工具名称、参数与执行结果记录 |
| 流式响应 | 事件顺序、增量内容、首 Token 和结束信号是否可被现有解析器处理 | 完整事件序列与时延记录 |
| 错误处理 | 认证、限流、超时、内容策略和上游故障是否被正确分类 | 错误类型、重试和回退结果 |
| 用量成本 | 输入、输出、缓存和供应商用量字段能否统一归因 | 网关记录与供应商账单抽样核对 |
迁移验证
用固定样本逐层排除差异
- 建立样本选择覆盖普通请求、流式响应、工具调用和已知错误的代表性请求。
- 登记上游在 Gateway 中配置模型资源、凭据、网络和允许的应用身份。
- 逐协议验证分别比较原路径和网关路径的请求语义、结果结构与错误行为。
- 接入观测确认统一请求 ID 能关联应用、策略、路由、上游响应和用量。
- 定义门槛由业务团队设定功能、可靠性、时延、成本和质量的上线条件。
原始请求样本协议与行为对比受控流量 · 持续观测
上线控制
灰度只改变一个变量，回滚保持随时可用
先迁移一条边界清晰的业务链路，保持原应用逻辑和业务指标不变。若协议、错误、时延或结果质量超出团队定义的门槛，应立即回到原 endpoint，并保留失败请求用于修复。
- 流量范围从单应用、单环境或单业务场景开始，不一次迁移全部调用。
- 变更记录记录配置版本、上游、策略、时间窗口和负责人。
- 告警条件围绕错误、超时、成本和质量设置业务可接受门槛。
- 回滚动作恢复原 endpoint 和凭据，确认未完成请求的处理方式。