迁移单位不是模型名而是完整索引协议
嵌入向量不是可以脱离生成过程理解的通用坐标。模型标识、输出维度、距离算法、向量归一化方式、切片器版本和文本预处理规则共同定义一个索引协议。任何一项改变都可能让相似度分布和召回顺序改变，所以不应在原向量列上就地覆盖。为每份向量保存协议版本，也为查询向量显式选择同版本空间，才能防止新旧数字被无意混合。
迁移清单应固定原索引、目标索引、文档选择条件、切片规则和评测集版本。索引名称不要只写“新版”，而要能从元数据还原某个向量如何生成。如果同时调整切片长度和嵌入模型，需要把变量分开做对照评测，否则召回改善或回归都无法归因。对外提供的检索别名只是流量开关，底层版本信息仍必须保留。
先建立可比的金标问题集
没有金标评测时，影子查询只会产生大量“排名不一样”的日志，却无法判断哪一个更好。从真实搜索、客服工单和无结果查询中抽取代表性问题，为每题标注最小支持证据集、不应出现的过时文档和业务上必须区分的近似项。对型号、否定条款、时间范围和跨语言问法单独分层，避免总体均值遮住业务高损失样本。
对新旧索引分别计算指定截断位的召回率、首个相关结果位置和关键证据遗漏，不直接比较两个模型原始相似分数。分数刻度由各自的表示空间决定，一个空间的高分不代表比另一个空间的低分更可信。使用同一份文档快照、同一查询集和同一重排截断位，并保留逐题差异，才能为切换门槛提供可重放证据。
双索引回填要幂等且可继续
回填任务以稳定文档标识、内容哈希、切片标识和目标协议版本形成唯一键。每个批次只读固定数量的文档，生成向量后以上插方式写入，成功后保存最后处理游标和计数。工作进程在请求超时或重启后可以重放当前批，但不会产生双份有效切片。不要把“已发送嵌入请求”当成回填完成，只有目标索引可查到预期版本才能推进进度。
大规模回填还要约束请求并发、令牌和费用，并对限流与短暂服务故障做有上限的退避。为每批记录输入文档数、生成向量数、字符计费量、失败分类和耗时分位，可以提前发现某种文档或异常切片让成本偏离。完整率应从当前有效文档快照反向核对，而不是只累加任务报告的成功数，否则删除和过期版本会被忽略。
在回填期间维持增删改一致
如果回填需要数小时或数天，文档库一定会继续变化。在开始时记录一个可重放的源数据水位，先对快照做全量回填，同时将水位之后的创建、更新和删除事件写入新旧两个索引。全量阶段结束后再对增量流做对账，直到落后量为零。若数据源不支持可靠增量序列，至少要通过更新时间和内容哈希定期扫描差异，并承认其一致性窗口。
删除路径比新增更容易遗漏。删除事件应携带文档标识和已知切片版本，对两个索引都执行，且在迁移完整率中将多余切片视为错误。文档更新时先写入新版本切片，再以文档当前版本标识过滤读取，最后延迟清理旧版本，可避免短暂空窗。缓存键也必须带上索引协议版本，否则切换后仍会命中旧排名并让影子比较失真。
影子查询应比较结果而不影响用户
在新索引达到基本完整率后，生产查询可以异步复制到它，但用户响应仍由旧索引提供。影子路径使用独立超时和并发预算，不让新索引的延迟或错误拖慢主请求。日志保留查询指纹、评测分层、两边的文档标识顺序、缺失证据和耗时，而不长期复制敏感原始问句或文档正文。
排名差异需要按原因分类：新索引缺片、切片边界改变、相同证据顺序互换、旧文档被正确降权，以及真正的关键召回回归。只看前十结果的集合重合率会把等价顺序变动与严重遗漏混在一起。对金标问题自动计算指标，对非标注的真实查询只做差异分类和抽样复核，不把无标签的“变了”直接当成坏了。
切流量用可回滚别名而不是复制删除
达到切换条件后，先让少量读请求通过版本化别名进入新索引，继续保留查询版本、错误率、尾延迟、无结果率和引用覆盖率。流量比例与索引别名变更要有审计记录，并能在不重新生成向量的情况下立即回到旧版。应用层不应将新向量同时查询旧索引作为降级，因为维度和距离协议可能根本不兼容。
切换门槛应同时要求数据完整、金标质量、生产性能和成本预算达标。重点查询零遗漏可以是硬门槛，总体指标则应与基线及置信区间比较，避免样本波动被误认为提升。如果新模型让某些问题更好、另一些高风险问题更差，可以保持双版路由作为明确策略，但不要为了完成迁移而用平均分数消除业务差异。
旧索引退役前需要完成反向对账
全量切流不代表旧索引可以立即删除。在回滚窗口内继续对新旧两边双写增删改，定期从有效文档快照生成应有切片清单，分别找出新索引的缺失、重复、过时和孤立项。同时检查所有应用实例、后台任务和缓存仍有没有读取旧别名。只有读流量归零且反向对账持续稳定，才能开始退役。
退役应先禁止旧索引的写入并保留只读快照，等待经过完整业务重试窗口后再删除。快照不必无限期保存，但应记录模型与切片配置、文档水位、评测报告和删除时间，让之后的质量调查能知道历史响应来自哪个空间。验收矩阵还要演练回填中断、双写部分失败、别名切换后超时和回滚，证明每个阶段都能保持版本纯度。
分批成本与限流也是迁移正确性
新嵌入模型的请求大小、限流和计费方式可能与旧模型不同，所以不能照搬旧回填并发。先用真实切片长度分布计算单批输入上限、预估费用与最长耗时，再通过动态并发控制使吞吐稳定在服务配额内。对限流使用有抖动的退避，但对输入过长和参数错误立即标记不可重试，避免一份异常文档反复消耗整个迁移预算。
成本报表按数据集、切片版本和批次记录请求量、输入字符、成功向量、重试次数和废弃输出。如果调整切片规则导致向量数翻倍，完整率可能看起来正常，但存储和查询成本会长期上升。切换门槛因此要包含单文档平均向量数、索引体积和影子查询尾延迟，不能只看召回质量和回填任务是否结束。
迁移后仍要持续监测分布漂移
索引切换完成后，新文档类型、查询语言和用户习惯仍会改变，一次性金标通过不能保证长期表现。持续记录无结果率、低置信度查询、用户后续改写和引用打开率，按内容类型与语言分组查看，避免总体流量增长遮住某个小类的严重回归。新的失败工单要回流到金标集，但要保留独立验证集，不让调参只适应已知样本。
监测不应长期记录完整查询和召回正文。可以使用查询指纹、长度、语言、结果标识、排名与点击事件做聚合诊断，对经授权的短期采样单独设置访问权限和自动删除。当指标异常时，先区分文档源更新、切片管线错误、索引缺失和嵌入表示问题，然后选择重建局部文档、回滚别名或更新评测，不把所有波动都归因于模型。
一份可执行的迁移验收矩阵
数据层验收要检查每份当前有效文档在新索引中的切片数、内容哈希和协议版本，同时确认删除、过时和孤立切片为零。在回填、双写、增量追平、切流和退役各阶段中断工作进程，证明任务可幂等继续。修改和删除事件在全量扫描期间并发发生，两边最终都只保留同一有效版本，才算证明一致性设计成立。
质量层对每个金标问题保存新旧前若干结果和最小证据集，断言高损失证据无遗漏，并按问题类型比较召回、首个相关位置和引用覆盖。运行层验证影子查询不影响用户延迟，逐步切流能立即回滚，缓存键不混用版本。最后演练新索引短暂不可用、别名配置错误和旧索引回滚，保证团队不需临时重算所有向量就能恢复服务。
实现片段
const namespace = `${embeddingModel}:${chunkerVersion}`
评论 · 0