为什么要锁版本
embedding 模型一旦变化，向量空间就随之改变：用新模型编码的查询去检索旧模型生成的向量，相似度没有意义。因此模型必须锁到具体版本，自建模型还要锁到权重 revision；升级时必须全量重算文档向量并重建索引，再用评测集对比新旧版本的效果，确认后再切流量。
基本信息
| 锁定对象 | 模型名称与版本，自建模型锁定到 revision 提交号 |
|---|---|
| 根本原因 | 向量空间变化后新旧向量不可混用 |
| 升级代价 | 全量重算文档向量并重建索引，属于计划内停机或双跑 |
| 记录要求 | 模型名与版本写入索引元数据，便于事后排错 |
典型使用场景
- 依赖固定：容器镜像与依赖重装时防止模型文件被静默替换
- 索引溯源：排查召回异常时确认索引由哪个模型版本生成
- 升级演练：先建新集合灌数据，评测通过再切流量
- 多环境一致：开发、测试与生产使用同一 revision，避免结果不一致
- 合规审计：能说明某次回答由哪个模型版本产生
按 revision 锁定权重
按 revision 锁定权重
from sentence_transformers import SentenceTransformer
# revision 填具体的提交哈希或版本标签，不要留空取最新
model = SentenceTransformer("BAAI/bge-large-zh-v1.5",
revision="<commit-hash>")
# 把模型名与 revision 一起写入索引元数据，便于事后核对
版本管理要点
| 环节 | 做法 | 缺失后果 |
|---|---|---|
| 模型加载 | 指定 revision 而非默认最新 | 重装依赖时权重被静默替换 |
| 索引元数据 | 记录模型名与版本 | 排错时无法确认索引由谁生成 |
| 升级流程 | 双索引并行、评测后切流量 | 新旧向量混存导致检索退化 |
| 缓存键 | 包含模型版本标识 | 命中旧模型向量，结果错乱 |
把模型名与 revision 写进索引元数据，排错时能确认索引由哪个版本生成；同时把索引构建参数一起存档，复现历史结果才不费力。
本地缓存目录也要纳入管理：模型下载后缓存在磁盘上，多机部署时需确认各节点加载的是同一份权重文件。