📚 课程目录第4章模型文件管理与版本控制

4. 模型文件管理与版本控制：MLflow 与 DVC 实战

在风控评分模型的 Serving 部署中，模型文件的管理绝非简单的“存文件”。随着模型迭代、回滚、A/B 测试以及监管审计的需求，必须建立一套严谨的版本控制与元数据管理体系。本章将深入讲解如何利用 MLflow 和 DVC 两大工具，实现模型版本的生命周期管理、注册表设计以及元数据存储。

4.1 模型版本控制工具选型：MLflow vs DVC

MLflow 和 DVC 在模型管理侧重点上有所不同，实际生产中常组合使用。下表对比了二者的核心差异：

维度	MLflow	DVC
核心定位	机器学习生命周期管理平台	数据与模型版本控制（基于 Git）
模型存储	内置 Model Registry，支持 Stage 管理	通过 Git 跟踪文件哈希，实际存储于远程存储（S3/GCS）
元数据	自动记录参数、指标、标签、环境依赖	需手动配置或结合 DVC 实验跟踪
回滚粒度	按模型版本 + Stage 回滚	按 Git commit + DVC 文件版本回滚
适用场景	模型训练、部署、A/B 测试全流程	大数据集、大模型文件的 Git 友好管理

生产建议：推荐使用 DVC 管理模型文件存储（避免 Git 仓库臃肿），同时使用 MLflow Model Registry 管理模型版本与 Stage（Staging / Production / Archived），二者通过模型文件路径或哈希值关联。

4.2 MLflow Model Registry 设计与实战

MLflow 的 Model Registry 提供了模型版本、阶段（Stage）和元数据的集中管理。以下是风控评分模型注册表的核心设计：

4.2.1 模型注册与版本提升

以下代码展示了如何将训练好的风控模型注册到 MLflow Registry，并设置阶段：

import mlflow
from mlflow.tracking import MlflowClient

# 设置 MLflow 跟踪 URI（生产环境指向共享数据库）
mlflow.set_tracking_uri("http://mlflow-server:5000")

# 假设已有 run_id 和模型路径
run_id = "abc123def456"
model_uri = f"runs:/{run_id}/risk_score_model"

# 注册模型（首次注册创建新模型名）
result = mlflow.register_model(
    model_uri=model_uri,
    name="credit_risk_scorecard_v2"
)

# 使用 Client 提升版本到 Staging
client = MlflowClient()
client.transition_model_version_stage(
    name="credit_risk_scorecard_v2",
    version=result.version,
    stage="Staging"
)

# 记录元数据：训练时间、AUC、特征列表
client.set_model_version_tag(
    name="credit_risk_scorecard_v2",
    version=result.version,
    key="training_time",
    value="2025-03-15T10:30:00Z"
)
client.set_model_version_tag(
    name="credit_risk_scorecard_v2",
    version=result.version,
    key="auc",
    value="0.832"
)
client.set_model_version_tag(
    name="credit_risk_scorecard_v2",
    version=result.version,
    key="feature_list",
    value="age,income,credit_history,debt_ratio,employment_years"
)

4.3 DVC 模型文件版本控制实战

对于风控模型文件（通常为 .pkl、.onnx 或 .joblib 格式，大小可达数百 MB），直接存入 Git 会导致仓库膨胀。DVC 通过 Git 跟踪文件哈希，实际文件存储于远程存储（如 S3、MinIO）。

4.3.1 DVC 初始化与模型跟踪

# 初始化 DVC（项目根目录执行）
dvc init

# 添加远程存储（以 MinIO 为例）
dvc remote add -d minio_remote s3://mlflow-bucket/models
dvc remote modify minio_remote endpointurl http://minio:9000
dvc remote modify minio_remote access_key_id YOUR_ACCESS_KEY
dvc remote modify minio_remote secret_access_key YOUR_SECRET_KEY

# 跟踪模型文件
dvc add models/credit_risk_scorecard_v2.pkl

# 推送至远程存储
dvc push

# 生成 .dvc 文件（包含文件哈希），提交至 Git
git add models/credit_risk_scorecard_v2.pkl.dvc .dvc/config
git commit -m "Add credit risk model v2.0.1"

4.3.2 模型回滚与版本切换

当需要回滚到旧版本模型时，只需切换 Git 分支或 commit，然后执行 dvc checkout：

# 切换到历史 commit（包含旧模型 .dvc 文件）
git checkout <old_commit_hash>

# 从远程存储拉取对应哈希的模型文件
dvc checkout

# 此时 models/credit_risk_scorecard_v2.pkl 已恢复为旧版本

关键注意：DVC 只跟踪文件内容（通过 MD5/SHA256 哈希），不跟踪文件名或目录结构。因此，模型文件重命名或移动后，DVC 会视为新文件。建议在 MLflow 元数据中记录 DVC 文件哈希，实现双向关联。

4.4 模型元数据存储设计

元数据是模型审计和追溯的核心。以下表格展示了风控评分模型元数据的标准存储结构：

元数据字段	类型	示例值	存储位置
模型名称	string	credit_risk_scorecard_v2	MLflow Registry
版本号	int	3	MLflow Registry
训练时间	datetime	2025-03-15T10:30:00Z	MLflow Tag
AUC	float	0.832	MLflow Tag / Metric
KS 统计量	float	0.45	MLflow Tag
特征列表	string (JSON)	["age","income","credit_history"]	MLflow Tag
DVC 文件哈希	string	d41d8cd98f00b204e9800998ecf8427e	MLflow Tag
训练数据版本	string	v2025Q1	MLflow Tag
模型文件路径	string	s3://mlflow-bucket/models/.../model.pkl	MLflow Model Source

4.5 模型注册表与 Serving 集成

在 Serving 部署时，通过 MLflow Client 获取指定 Stage 的模型版本，并加载模型文件：

from mlflow.tracking import MlflowClient

client = MlflowClient()

# 获取 Production 阶段的最新模型版本
production_model = client.get_latest_versions(
    name="credit_risk_scorecard_v2",
    stages=["Production"]
)[0]

# 获取模型 URI（指向 DVC 管理的文件）
model_uri = production_model.source

# 加载模型（MLflow 自动处理环境依赖）
import mlflow.pyfunc
model = mlflow.pyfunc.load_model(model_uri)

# 进行预测
features = [[35, 50000, 720, 0.3, 5]]
prediction = model.predict(features)
print(f"Prediction: {prediction}")

  生产级增强：在 CI/CD 流水线中，可自动执行以下步骤：

训练完成后，使用 MLflow 注册模型并提升至 Staging。

在 Staging 环境进行离线验证（如 PSI、AUC 衰减测试）。

验证通过后，通过 API 将模型版本从 Staging 提升至 Production。

触发 Serving 服务热加载新版本模型，实现零停机部署。

4.6 版本控制最佳实践与避坑指南

命名规范：模型名称应包含业务线+模型类型+版本号，如 credit_risk_scorecard_v2，避免使用“最终版”、“v2_final”等模糊命名。
Stage 流转：严格遵循 None → Staging → Production → Archived 的流转路径，禁止跳过 Staging 直接上线。
元数据完整性：每次注册模型时，必须记录训练时间、AUC、特征列表、训练数据版本，否则 CI 流水线应拒绝注册。
DVC 与 MLflow 关联：在 MLflow 的模型版本 Tag 中存储 DVC 文件哈希，便于审计时快速定位实际模型文件。
回滚测试：定期演练模型回滚流程，确保 DVC checkout + MLflow Stage 切换能在 5 分钟内完成。