别名会漂移
多数接口对外暴露的是模型别名，别名背后的权重会随厂商更新而替换，请求格式不变但行为会变。版本锁定就是让「跑的是哪个版本」这件事可知可控：尽量请求具体的版本标识，把响应中携带的版本字段写进日志，对同一批请求保存行为快照，再用灰度路由与契约测试拦截变化。锁定的目的是及时发现变化，而不是假设变化不会发生。
基本信息
| 锁定手段 | 请求具体版本标识、固定 SDK 版本、固定提示词与采样参数 |
|---|---|
| 可观测字段 | 响应中的模型与版本标识、用量字段、结束原因 |
| 拦截手段 | 契约测试、灰度路由、按比例对比新旧版本 |
| 回滚前提 | 旧版本仍在服务期内且路由可切换 |
| 记录要求 | 版本标识、切换时间、结论写入变更台账 |
| 命名差异 | 是否提供固定版本标识与稳定期承诺，以官方文档为准 |
典型使用场景
- 生产稳定性：让线上行为变化可归因、可回滚
- 回归验证：新旧版本按比例同时跑，用同一套题对比
- 合规留痕：审计时能说明某次输出由哪个版本产生
- 成本控制：避免新版本输出风格变化导致 token 用量上升
- 多方协作：前端、后端与数据团队以同一版本标识对齐预期
- 故障复盘：把行为变化与部署时间轴对齐，排除模型侧影响
锁定手段与局限
| 手段 | 做法 | 局限 |
|---|---|---|
| 具体版本标识 | 请求时指定版本而非别名 | 厂商可能只提供有限的服务期 |
| SDK 版本固定 | 锁定依赖版本与镜像 | 旧 SDK 后续可能不再获支持 |
| 参数固化 | 温度、采样上限等写入配置并纳入代码评审 | 厂商默认值变更仍会绕过你的配置 |
| 行为快照 | 固定输入重复运行记录统计量 | 只覆盖已被采样到的行为面 |
| 灰度路由 | 按比例分流新旧版本并对比指标 | 需要护栏指标与自动回滚能力 |
| 契约测试 | 对响应结构、字段与格式做断言 | 对语义变化不敏感，需配合评测集 |
网关路由与灰度
网关路由与灰度
# 目标：生产固定版本，新版本按小比例试跑并自动对比
routes:
- name: chat-default
model: 供应商/模型别名
pinned_version: 固定版本标识 # 以厂商官方文档提供的写法为准
params:
temperature: 0.2
top_p: 1
max_tokens: 2048
fallback: 备用版本标识
canary:
enabled: true
percent: 5 # 从低比例开始，避免影响主体流量
shadow_suite: core-v3 # 影子评测集版本
guardrails:
parse_error_rate: 超过阈值即回滚 # 契约类护栏
pass_rate_drop: 超过阈值即回滚 # 质量类护栏
log_fields: [model, version, usage, finish_reason]版本锁定解决的是「看得见变化」，不能阻止变化。真正让升级可控的是灰度与回滚能力：小比例先跑、护栏指标自动判定、异常时路由秒级切回，这比任何书面承诺都可靠。
把版本标识写进日志与调用链路追踪，配合每次行为的评测结论，就能在用户反馈变差时快速回答「是模型变了、SDK 变了，还是我们改了提示词」。具体字段名与是否提供，以对应厂商官方文档为准。
锁定版本不等于永久可用：厂商有生命周期政策与下线权利，旧版本可能在某些地区或套餐下先被停用。锁定应作为过渡措施，同时保留迁移计划与备用版本路由。