📚 课程目录第4章模型版本管理

模型版本管理：版本控制方法、模型仓库与版本回退策略

核心原理：模型版本管理的本质

在AI模型灰度发布与回滚的实战中，模型版本管理是支撑整个流程的“地基”。没有清晰的版本控制，灰度发布无法精确指定“哪个模型在哪个流量范围内生效”，回滚也无法快速定位“上一个稳定版本是谁”。模型版本管理的核心目标可以归纳为三点：可追溯（每个模型产物都能对应到代码、数据、超参数和训练环境）、可比较（不同版本之间能进行指标对比和差异分析）、可恢复（任何时刻都能快速切回历史稳定版本）。

与软件代码版本管理（如Git）不同，模型版本管理面临三个独特挑战：一是模型文件通常很大（数百MB到数GB），不适合直接存入Git仓库；二是模型不仅包含权重文件，还包含预处理逻辑、特征工程代码和推理依赖环境，这些“元信息”必须与模型文件一同管理；三是模型版本之间存在“血缘关系”，即某个版本是由哪份数据集、哪个训练脚本、哪组超参数产生的，这种血缘关系对问题排查至关重要。

关键认知：模型版本管理不是简单的“文件备份”，而是对模型制品（Model Artifact）及其全部元数据（Metadata）的完整生命周期管理。一个“版本”应当是一个不可变的快照，包含模型文件、模型签名（输入输出格式）、依赖环境、评估指标和血缘信息。

模型版本控制方法：从文件命名到注册中心

模型版本控制方法经历了三个演进阶段。最原始的方式是文件命名约定，例如将模型保存为 model_20250115_v2_acc0.923.h5，这种方式简单但极易出错——文件名无法承载完整的元信息，且多人协作时容易覆盖。第二阶段是基于Git LFS（Large File Storage）的版本控制，将模型文件托管在Git LFS中，利用Git的分支和标签能力管理模型版本，但Git LFS对大型二进制文件的支持仍然笨重，且无法表达模型之间的血缘关系。

当前推荐的做法是使用专用模型注册中心（Model Registry）。以MLflow Model Registry为例，它将模型版本视为“注册实体”，每个版本自动关联训练时的运行记录（Run），包括超参数、指标和数据集快照。注册中心提供版本列表、阶段转换（Staging → Production → Archived）和API调用接口，使得灰度发布系统可以通过API精确获取指定版本的模型。

# MLflow 注册模型版本示例
import mlflow

# 注册新模型版本
mlflow.register_model(
    model_uri="runs:/d2a2f1e5c6b84a2f9a3c8e7b6d5f4a3e/model",
    name="fraud_detection_model"
)

# 查询模型版本详情
client = mlflow.tracking.MlflowClient()
versions = client.get_latest_versions("fraud_detection_model", stages=["Production"])
for v in versions:
    print(f"版本: {v.version}, 阶段: {v.current_stage}, 指标: {v.metrics}")

模型仓库的使用：MLflow与DVC的定位差异

MLflow和DVC（Data Version Control）是当前最主流的两个模型仓库工具，但它们的定位有本质区别。MLflow是一个模型生命周期管理平台，侧重于模型注册、阶段管理和推理服务集成；而DVC是一个数据与模型文件版本控制工具，侧重于利用Git管理大文件的版本，底层依赖对象存储（如S3、OSS）。在实际项目中，两者常常配合使用：DVC负责模型文件和数据集的版本化存储，MLflow负责模型元数据、指标和阶段流转的管理。

对比维度	MLflow Model Registry	DVC
核心定位	模型生命周期与元数据管理	数据/模型文件版本控制
版本粒度	模型注册版本（v1, v2...）	文件级版本（基于Git提交）
阶段管理	内置 Staging / Production / Archived	无阶段概念，需自行约定
存储方式	可对接S3、OSS、NFS等	对象存储 + 本地缓存
典型使用场景	模型上线、A/B测试、回滚决策	训练数据版本回溯、模型文件备份

实践建议：在灰度发布场景中，MLflow的“阶段”概念非常有用。可以将灰度中的模型标记为 Staging，将已验证的模型标记为 Production，将回滚后的旧模型标记为 Archived。这样，发布系统只需查询 Production 阶段的模型即可获得当前应服务的版本。

版本回退策略：从“一键回滚”到“渐进恢复”

版本回退并非简单的“切回旧版本”，而是一个需要谨慎设计的策略过程。常见的回退策略有三种：全量回退（立即将所有流量切回旧版本）、渐进回退（按比例逐步切回，观察旧版本是否仍然正常）、灰度保留（保留少量异常版本流量用于问题诊断）。选择哪种策略取决于故障的严重程度和可诊断性。

一个标准的回退流程应当包含以下步骤：首先，通过监控系统确认模型指标异常（如准确率下降、延迟升高）；其次，从模型注册中心查询当前生产版本的上一个稳定版本；然后，执行回退操作——在Kubernetes或推理服务框架中更新模型路由配置；最后，验证回退效果并记录回退原因。整个过程应当自动化，避免人工操作带来的二次风险。

# 基于MLflow阶段转换的回退操作
from mlflow.tracking import MlflowClient

client = MlflowClient()

# 1. 将当前异常版本 v2.1 转为 Archived
client.transition_model_version_stage(
    name="fraud_detection_model",
    version=3,  # v2.1
    stage="Archived"
)

# 2. 将目标回退版本 v2.0 转为 Production
client.transition_model_version_stage(
    name="fraud_detection_model",
    version=2,  # v2.0
    stage="Production"
)

# 3. 推理服务自动拉取新的 Production 版本

案例场景：推荐模型灰度发布中的版本回退

某电商平台的推荐模型团队使用MLflow管理模型版本。某次灰度发布中，新模型v3.2在5%流量下运行30分钟后，监控系统发现点击率（CTR）下降12%，同时推理延迟从35ms上升到80ms。团队立即启动回退流程：

确认异常：通过Grafana监控面板确认CTR和延迟指标均超过告警阈值，且与v3.2的离线评估指标严重不符。
定位版本：在MLflow中查询当前Production阶段为v3.2，上一个稳定版本为v3.1（在Archived阶段）。
执行回退：通过自动化脚本将v3.1转为Production，将v3.2转为Archived。推理服务在30秒内完成新版本拉取。
验证恢复：回退后15分钟，CTR恢复到正常水平，延迟回落到38ms。
事后复盘：分析发现v3.2的特征拼接逻辑存在bug，导致部分请求使用了错误的特征顺序。

常见误区：许多团队在回退时只关注“切换版本”，却忽略了回退后的数据一致性。例如，如果新版本在灰度期间产生了一些缓存数据或日志格式变化，回退后旧版本可能无法正确读取这些数据。因此，回退策略必须包含“数据兼容性检查”环节，必要时需要同时回退数据处理管道。

误区与复盘：版本管理的五个典型错误

在模型版本管理的实际落地中，以下五个错误最为常见：

只存模型文件，不存元数据：导致无法追溯模型对应的训练数据和超参数，问题排查时无从下手。
版本命名混乱：使用“final_final_v2”这类命名，缺乏语义化版本规范（如语义化版本号 + 时间戳）。
忽略模型签名校验：新版本模型的输入特征顺序或类型发生变化，导致线上推理报错。
回退时未通知下游系统：模型版本变更会影响特征平台、监控告警等下游依赖，需要同步通知。
没有定期清理旧版本：模型仓库中堆积大量无用版本，增加存储成本并造成选择困难。

复盘总结：一个健康的模型版本管理体系应当像“航空黑匣子”一样，记录每一次模型变更的完整上下文。当灰度发布出现问题时，团队能够在5分钟内定位到具体版本、理解变更内容、执行回退并验证恢复。这需要版本控制工具、自动化流程和团队规范的共同支撑，三者缺一不可。