版本固定是什么
版本固定指生产环境锁定模型版本与 SDK 版本，不依赖会漂移的默认别名，并把模型、提示、参数与评测集版本一起记进发布清单。原因是行为需要可复现：当默认别名指向的模型被更新、SDK 小版本改了默认重试或截断行为时，同样的输入会得到不同输出，而排查时如果没有版本记录，就只能靠猜。
基本信息
| 适用平台 | 所有通过 API 或自建服务调用模型的系统 |
|---|---|
| 记录项 | 模型标识与版本、SDK 版本、温度与 top_p 等参数、提示版本、评测集版本 |
| 升级流程 | 先评测、再灰度，新旧组合各留回退路径 |
| 补充要求 | 服务端侧的默认行为变化（重试、超时、截断）也要记录 |
典型使用场景
- 线上行为突变排查：对照版本记录确认是否发生过模型或 SDK 更新
- 评测复现：按发布清单里的版本组合重跑，还原历史结论
- 灰度对比：新旧模型各跑一部分流量，明确回退路径与观察窗口
- 成本与性能分析：同一提示在不同模型上的成本与延迟差异可归档比较
- 合规留痕：说明某时间点的系统由哪些版本组成
发布清单记录项
发布清单记录项
# model: <provider>/<model-id>@<version> # 固定具体版本，不用默认别名
# sdk: <client-lib>==x.y.z # 锁定客户端库版本
# temperature: 0.2 top_p: 1.0 max_tokens: 1024
# prompt: summarize@1.3.0 # 提示版本号
# eval_set: eval-meeting-v2 # 验证所用评测集版本
# 配置项：超时、重试次数与退避策略（客户端默认值也会随版本变化）
# 记录人：<name> 日期：<date> 关联变更单：<ticket>漂移来源与固定方式
| 漂移来源 | 表现 | 固定方式 |
|---|---|---|
| 模型默认别名 | 指向的版本被更新，输出风格改变 | 固定到具体模型版本标识 |
| SDK 版本 | 重试、超时、截断行为变化 | 锁定版本并记录在清单中 |
| 生成参数 | 温度与上限变化影响稳定性 | 参数写进配置并入库 |
| 提示文件 | 内容被改动，行为随之变化 | 提示即代码，版本号可回滚 |
| 评测集 | 换题后分数不可比 | 评测集版本化，切换时做桥接 |
固定版本会让升级变成一次显式决策：需要评测、灰度与回退准备。这正是不用默认别名的意义——把「意外变化」变成「主动升级」。
只记模型不记 SDK 与参数时，复现常对不上：同样的提示在不同客户端库版本下，超时与重试行为可能不同，长输出场景的差异尤其明显。