回滚与版本管理

• Embedding 升级的索引重建与切换
• 旧索引保留期与切换闸门
• 新旧向量混合查询与快速回退

Embedding 模型升级会改变向量空间，旧索引与新向量不兼容，需重建索引。切换闸门：用新旧 embedding 在评测集上对比检索质量（recall@K、MRR），达标才切换；切换采用"双索引"过渡——新索引并行构建，构建完成后在灰度期双索引并存，按流量比例或按用户分桶分配新旧索引。灰度期混合查询：新旧向量空间不同，需在查询时按请求所属版本选择对应索引，避免用新 query 查旧索引（维度/语义不一致）。旧索引保留期：设定保留窗口（如 30 天）供回退，保留期内不清理。质量退化时快速回退：把流量切回旧索引即可（旧索引仍在），无需重建。关键是要维持"query 版本与索引版本匹配"。

Embedding 升级的核心是"新向量空间与旧索引不兼容"。双索引并存、按版本匹配查询、旧索引保留期，保证升级可验证、可回退。

• Prompt 版本化（就像代码版本）
• 回滚机制
• 可审计（历史、变更、责任人）

Prompt 应像代码一样版本化管理：用版本控制系统（Git）或配置中心存储每个 Prompt 版本，版本带唯一 ID、变更记录、作者、时间、变更说明；发布时记录"当前生效版本"。回滚：只需把生效版本切回旧版本（无需改代码），支持一键回滚到任一历史版本。可审计：完整记录每次变更（谁、何时、为什么改、diff），以及每个请求实际命中的 Prompt 版本（请求日志带版本号），便于事后追溯某个输出对应的 Prompt 版本。配合 code review 与 CI 校验，让 Prompt 变更像代码变更一样受控。

Prompt 版本化的本质是"把 Prompt 当一等公民的代码资产"。版本化+回滚+审计+请求级版本追踪，使其可追溯、可回退、可归责。

• 模型版本快速回退
• 回退链路（网关、推理、缓存）
• 保留旧模型

模型升级失败需快速回退链路。设计：推理服务保留旧模型（多版本并存，按路由切换），网关层维护"模型别名→版本"映射，回退只需把别名指回旧版本，无需重部署；回退前保证旧模型在可用状态（不被热卸载）；回退链路要覆盖缓存（新版本缓存需清理，避免污染）、会话（新版本产生的上下文与旧版本兼容）、以及依赖新模型的检索/工具。回退目标时间要短（分钟级），需演练回退链路。关键是"模型版本可寻址、网关可路由、旧版本始终可用"。

快速回退的本质是"模型版本可寻址 + 网关路由 + 旧版本常驻"。别名切换让回退秒级生效，配合缓存与会话处理保证链路完整。

• 多区域异步回滚的一致性问题
• 最终一致 vs 部分生效
• 一致性机制（版本同步、回滚编排）

多区域异步回滚的难点是各区域回滚速度不同，可能部分区域已回滚、部分仍在新版本，造成"部分生效"。解决：用回滚编排器统一协调各区域，记录回滚状态；采用版本声明 + 区域同步——先下发"目标版本"声明，各区域异步执行，但对外通过网关统一读取"当前应生效版本"，未完成回滚的区域不对外放行新请求或标记为回滚中；用监控校验各区域是否都达到目标版本，全部达成才算回滚完成（最终一致）。对用户侧，跨区域请求要路由到已回滚区域，避免同一用户拿到不一致结果。关键是不把"部分生效"当成功，用状态机保证收敛。

多区域回滚的一致性是"最终一致"而非"同时生效"。回滚编排+版本声明+完成校验，保证各区域收敛到同一目标版本。

• 三者的版本依赖关系
• 版本组合（release）的统一管理
• 一致性发布

Prompt、模型、检索（embedding/索引/rerank）三者相互依赖：换模型可能要换 Prompt 格式、换 embedding 要重建索引。版本耦合治理的核心是"版本组合（release）"概念：把三者绑定为一个可整体发布的"版本组合"，每个组合有唯一 ID，包含 Prompt 版本、模型版本、检索版本。发布/回滚以组合为单位，保证三者一致（不会只升级模型而留下旧 Prompt 导致不匹配）。工程上做"版本矩阵"表记录各组合的兼容性，发布时校验组合合法性，回滚时整体回滚。避免"只回滚一部分导致状态不一致"。

版本耦合治理的本质是"把多个可独立变更的组件绑定为可原子发布的组合"。组合级发布与回滚杜绝了三者错配导致的系统不一致。

• 配置即代码（版本化、可评审、可审计）
• 配置变更的发布
• 回滚自动化

配置即代码把 AI 应用的配置（Prompt、参数、路由、模型选择）作为代码管理：存进 Git、走 code review、CI 校验、可版本化。这样配置变更像代码变更一样受控、可审计、可回滚。回滚自动化：配置发布后如果触发了指标异常，自动把配置回滚到上一版本（配置版本记录 + 自动检测 + 自动切换）；配置回滚通过配置中心热更新下发，无需重启；回滚记录保留供复盘。关键是把"配置作为版本化资产"与"自动化检测-回滚"结合，减少人工干预。

Config as Code 的本质是"把配置纳入代码生命周期的治理"。版本化+评审+自动化回滚，让配置变更既受控又可快速恢复。

• 回滚事件的根因提取
• 沉淀为评测样本
• 防回归机制

每次回滚都是宝贵的"失败样本"。复盘时提取根因（是 Prompt 漂移、模型退化、检索问题还是数据变化），把触发回滚的典型问题转化为评测样本加入防回归评测集（regression set）。流程：回滚后保留现场样本与根因；抽象出"该问题场景+期望正确行为"；把样本加入评测集；后续发布新版本时必跑该评测集，若新版本在旧问题样本上重新失败则阻塞发布。这样把"一次性的回滚教训"变成"永久的质量防线"，防止同类问题复发。

回滚复盘沉淀评测集的本质是"把失败经验转化为可重复检验的资产"。防回归集让每次回滚的系统性教训在未来版本上持续生效。

• 知识库快照（内容版本化）
• 按时间点回滚
• 答案基线管理

RAG 知识库内容（文档增删改）需要版本化，才能按时间点回滚。做法：知识库内容变更时做快照（每次变更生成一个内容版本，记录变更时间、内容集、embedding 索引）；文档删除用软删除（保留历史版本），索引与内容版本绑定；支持按时间点恢复——把内容集回滚到指定版本，并重建/切换对应索引。这样答案基线可恢复到历史版本（某次问答用的是哪个版本的知识，可复现）。工程上用"内容版本 + 索引版本"联动，查询时绑定版本，回滚时切换版本并重建索引。

知识库回滚的本质是"内容与索引版本化、可快照、可恢复"。版本绑定 + 索引重建 + 软删除，让答案基线的历史可复现、可回退。

• 检索参数变更的影子评测
• 防回归
• 前后效果差异的量化与留档

检索/Rerank 参数变更（如 Top-K、Rerank 模型、权重、阈值）影响检索质量，需影子评测：用真实/离线查询集同时跑新旧参数，对比检索质量（recall@K、MRR、命中率），避免影响生产。防回归：把参数变更纳入评测，跑防回归集，若关键指标退化则阻止发布。效果差异量化：用同一评测集对比新旧参数在召回率、精度、下游答案质量上的差异，计算差异幅度与显著性，并留档（参数版本、评测结果、结论）便于追溯。关键是把"参数版本"与"评测结果"绑定记录。

检索参数变更的治理核心是"影子评测 + 防回归 + 量化留档"。用同评测集对比新旧参数，量化差异并留档，让参数调整可衡量、可追溯。

• 回滚导致的结果不一致
• 用户感知处理（透明、解释、缓存）
• 一致性策略

回滚后旧版本生成的回答会与新版本不同，用户可能察觉（同一问题前后答案变了）。处理：对能感知的变更做透明沟通（如提示"版本更新"）；对关键、可缓存的结果在回滚时保留缓存或做一致性处理，避免同一会话内前后矛盾；区分"可接受的自然差异"与"需要一致性的场景"（如金融、法律结论需严格一致）；对重要结论可做版本标注，让用户知道结果基于哪个版本。核心是避免"同一用户在同一会话内看到矛盾答案"，并诚实告知变更。

用户感知处理的核心是"诚实的透明 + 关键场景的一致性"。回滚引起的差异需要被管理，不能让用户困惑于前后矛盾。

• 回滚演练的目的
• AI 应用回滚的特殊性
• 演练的价值

回滚演练（Game Day）在 AI 应用中极有必要，因为回滚链路本身可能失效（网关路由、缓存、会话、多区域协调），平时不演练，真到故障时才发现回滚不可靠。AI 回滚的特殊性：要处理缓存污染、会话上下文、版本兼容、多区域最终一致，这些只在演练中才能暴露。演练价值：验证回滚能在目标时间内完成；验证缓存/会话/下游依赖处理正确；验证自动回滚触发逻辑；培养团队回滚能力；发现并修复回滚链路的薄弱点。演练应定期进行并纳入发布流程。

回滚演练的本质是"把回滚能力当作可验证的系统能力"。AI 回滚链路复杂，演练是发现设计缺陷、保障快速回退可靠性的必要手段。

• 偶发波动与持续趋势的区分
• 统计方法（连续窗口、趋势检测）
• 决策依据

灰度期间指标波动时，要区分偶发（随机波动、单点异常）与趋势（持续退化）。方法：用连续时间窗口聚合（连续 N 个窗口均超阈值才是趋势，单窗口波动是偶发）；用趋势检测（移动平均、斜率、累积和控制图 CUSUM、Sen's slope）判断是否持续恶化；结合样本量与置信区间（退化幅度是否显著）。偶发波动应观察不轻易回滚，趋势性退化应立即熔断。还可结合根因（是不是某类输入导致的定向退化）判断。核心是"以统计的稳定性而非单点数值做决策"。

偶发与趋势区分的本质是"用统计与连续窗口过滤噪声"。短期波动走观察、持续退化走熔断，避免误判与漏判。

• 不可变版本（版本不可变）
• 别名策略（stable/canary 等）
• 回滚机制

模型版本管理设计：不可变版本——每个模型版本创建后不可修改（权重、配置固定），用唯一版本 ID 标识，保证可复现、可追溯；别名策略——用语义别名（如 stable、canary、latest）指向具体版本，业务引用别名而非具体 ID，切换时只需移动别名指向，无需改业务代码；回滚机制——把别名指回旧版本即可回退，别名+版本解耦让回滚秒级生效。同时保留旧版本（不可立即删除），支持按版本回溯。关键是把"稳定引用（别名）"与"具体实现（版本）"分离。

模型版本管理的核心是"不可变版本 + 别名解耦"。不可变保证可复现，别名保证切换/回滚灵活，两者结合实现安全、快速的版本管理。

• 自动触发（指标异常熔断）
• 人工审批（高风险、无法自动判断）
• 边界划分原则

回滚触发分自动与人工。自动触发适用：可量化、明确的指标异常（错误率、延迟、成本、质量硬指标连续超阈值），无争议、需要快速响应，自动熔断能避免故障扩大。人工审批适用：指标模糊、需要判断（如主观质量下降、业务影响未知）、高风险变更（涉及大客户/合规）、以及自动判定不可靠的情形。边界划分原则：可自动判断且风险明确的，走自动；需要人工判断或影响面重大/难以自动判定的，走人工审批。可设"自动熔断为主，人工复核兜底"——自动先切流量，人工后确认根因。

边界划分的核心是"风险与可判定性"。自动求快、人工求稳，用"自动熔断+人工复核"的组合兼顾响应速度与正确性。

• 三类版本（embedding/知识库/参数）的关联
• 关联回滚
• 状态一致性

Embedding、知识库、参数三类版本相互依赖（embedding 决定索引、知识库决定内容、参数决定检索行为），只回滚一类会导致状态不一致（如换了 embedding 但索引没重建、改了参数但没配对应 embedding）。关联管理做法：把三类版本绑定为"版本组合/快照"，发布与回滚都以组合为单位；建立版本兼容矩阵，记录各类版本的兼容关系（某 embedding 配某知识库版本、某参数可行）；回滚时按组合整体回滚，若必须部分回滚则校验兼容性并做一致性补偿（如回滚 embedding 同时重建索引）。核心是"版本组合原子化，禁止片面回滚"。

关联管理的本质是"把互为依赖的版本当作原子单元"。组合回滚+兼容矩阵，防止只回滚一部分造成的不一致状态。

• Prompt/参数/模型三者的联动
• 联动发布
• 联动回滚

Prompt、参数与模型版本联动发布与回滚，因为三者组合决定生成行为。联动发布：把三者打包成"发布组合"（版本基元），一次发布同时更新 Prompt、参数与模型，保证一致性（换模型同时换配套 Prompt）；配置中心记录组合的版本矩阵。联动回滚：回滚时以组合为单位整体回滚（回到上一组合），避免只回滚模型而留下新 Prompt 导致不匹配。工程上按"组合版本号"管理，请求日志记录组合版本，支持按组合审计与回溯。核心技术是"三者绑定为可原子发布的组合"。

联动发布/回滚的本质是"组合原子化"。Prompt/参数/模型作为一个组合整体演进，避免三者错配导致行为不可控。

• 回滚的缓存影响（失效与清理）
• 会话上下文影响
• 下游依赖影响

回滚需做影响分析，重点处理三类：缓存失效——新版本产生的缓存（响应缓存、语义缓存）在回滚后可能污染旧版本，需按版本键清理/隔离，避免旧版本命中新版本缓存；会话上下文——回滚后用户会话上下文要与旧版本兼容，必要时迁移或提示用户；下游依赖——回滚可能影响依赖该模型的下游系统（如依赖输出 schema 的服务），需检查 schema/格式兼容，必要时联动下游。处理原则：回滚前识别影响面，回滚时按"缓存清理→会话迁移→下游兼容验证"顺序执行，并用监控确认回滚后系统正常。

回滚影响分析的本质是"识别版本切换的连带影响"。缓存、会话、下游三类依赖处理到位，回滚才能真正干净、不产生次生故障。