4、模型注册与存储：模型仓库设计、存储格式、版本命名规范

模型训练完成只是起点，真正让模型在团队中可复用、可追溯、可回滚，依赖一套严谨的模型注册与存储机制。本章聚焦模型仓库的物理与逻辑设计、存储格式选型，以及版本命名规范——这三者共同决定了模型资产的“可管理性”。

4.1 模型仓库的分层设计

企业级模型仓库不能只是一个文件服务器，它需要同时支撑开发迭代、生产部署和审计追溯三类诉求。推荐采用“三区分离”的仓库结构：

开发区（Dev Registry）：存放实验阶段的模型产物，允许频繁覆盖，保留最近N个版本，通常与训练任务绑定。
预发区（Staging Registry）：存放通过离线评估的候选模型，用于联调测试、影子部署，版本不可变但可标记为“废弃”。
生产区（Prod Registry）：存放已上线或可回滚的模型，版本只读不可变，任何修改必须生成新版本。

三个区域共享同一套元数据服务，但权限策略、保留周期、变更流程完全不同。生产区建议启用双人审批才能发布新版本。

核心原则：开发区追求“快”，生产区追求“稳”。模型从开发区晋升到生产区，必须经过完整的版本登记、校验、审批流程，而不是简单复制文件。

4.2 存储格式选型：从单文件到目录包

模型存储格式直接影响加载速度、跨框架兼容性和增量更新能力。当前企业实践中，目录包（Model Directory）已成为主流，取代了早期单一的 .h5 或 .pb 文件。

一个标准模型目录包应包含以下内容：

model_repository/
└── churn_prediction/
    ├── 1/                     # 版本号目录（正整数递增）
    │   ├── model.pkl          # 序列化模型主体（或 .pt/.onnx）
    │   ├── config.json        # 模型超参数、输入输出签名
    │   ├── preprocessor.pkl   # 特征预处理管道
    │   ├── metrics.json       # 评估指标（AUC、准确率等）
    │   └── metadata.yaml      # 训练数据指纹、框架版本、git commit
    └── 2/                     # 下一个版本
        └── ...

这种结构天然支持多版本共存，推理服务可以通过版本号直接加载指定模型，无需移动文件。对于深度学习模型，推荐使用 ONNX 或 TorchScript 作为中间表示，避免框架版本升级导致模型不可加载。

存储格式	适用场景	优点	缺点
单文件（.pkl/.h5）	快速原型、小模型	简单、易传输	无法附带预处理逻辑，跨框架困难
目录包（推荐）	生产级模型服务	自包含、可扩展、支持多版本	需要规范目录结构
容器镜像（.img）	端侧部署、离线环境	环境完全一致	体积大、构建慢、不适合频繁迭代

4.3 版本命名规范：语义化与不可变性

版本号是模型仓库的“主键”，命名规范必须同时满足人可读和机器可排序。推荐采用三段式语义化版本：

MAJOR.MINOR.PATCH[-预发布标识]

示例：
1.0.0          # 首个生产版本
1.1.0          # 新增特征或模型结构变化
1.1.1          # 仅重训练，结构不变
2.0.0          # 模型架构重构，不兼容旧版
1.2.0-rc.1     # 候选版本，用于预发验证

MAJOR：不兼容的架构变更、输入输出签名变化、算法范式替换（如LR→GBDT）。
MINOR：向后兼容的功能增强，如新增特征、调整损失函数。
PATCH：相同配置下的数据增量重训、超参数微调、Bug修复。

除了版本号，每个模型版本必须绑定不可变的元数据，包括：训练数据集版本、代码Git提交哈希、训练开始/结束时间、评估指标快照、模型文件SHA256校验和。这些信息写入 metadata.yaml，一旦发布即禁止修改。

常见误区：使用“日期+时间”作为版本号（如 20250614_v3）虽然直观，但无法表达兼容性关系，且排序依赖字符串解析，容易出错。更严重的是，如果允许覆盖同名版本，将导致生产环境无法精确回滚到某个历史状态。

4.4 模型注册流程与状态机

模型从训练完成到可回滚，需要经过明确的状态流转。每个状态都由仓库系统强制校验，不允许跳转。

训练完成 → 待注册 → 已注册(dev) → 评估中 → 已通过(staging) → 已发布(prod)
                ↓            ↓              ↓
             校验失败     评估失败      上线后发现问题
                ↓            ↓              ↓
             已拒绝       已拒绝         已回滚(指向旧版本)

注册动作本身是一个原子操作：上传模型文件、写入元数据、计算校验和、分配版本号，四步必须全部成功。任何一步失败，整个注册回滚，不留下半成品版本。

生产发布时，系统自动执行健康检查：加载模型、跑通一条样本、比对输出维度。检查通过后，更新路由指向新版本，同时保留旧版本至少30天作为回滚目标。

4.5 案例：金融风控模型仓库落地

某消费金融公司部署了信贷审批模型，模型仓库设计如下：

开发区保留最近20个实验版本，超过自动清理；
预发区存放通过离线AUC≥0.85的候选模型，进行7天影子对比；
生产区仅保留当前版本和最近2个历史版本，用于快速回滚；
每次发布自动记录审批人、发布时间、上线决策依据。

某次新版本上线后，线上坏账率上升0.3个百分点。运维团队通过仓库元数据定位到当前版本为 3.2.1，上一稳定版本为 3.1.0，执行一条回滚命令：

model-registry rollback --model=credit_approval --to=3.1.0 --reason="坏账率异常上升"

系统自动将路由切回 3.1.0，并冻结 3.2.1 版本禁止再次发布。整个过程耗时不到2分钟，且所有操作留痕可审计。

4.6 误区与复盘

误区一：把模型文件直接存在共享网盘。没有版本控制、没有元数据、没有权限管理，一旦文件被覆盖，历史版本永久丢失，无法回滚。

误区二：版本号与训练任务ID混用。训练任务ID是过程标识，模型版本是产物标识。一个训练任务可能产出多个候选模型，一个模型版本也可能由多次训练迭代产生。两者必须解耦。

误区三：忽略存储格式的兼容性。使用 pickle 保存sklearn模型时，如果Python或sklearn版本升级，旧模型可能无法加载。建议在元数据中记录框架版本，并在发布前做加载验证。

复盘结论：模型仓库的核心价值不在于“存文件”，而在于建立版本之间的可追溯关系和可回滚的安全边界。存储格式决定了模型能否被正确加载，版本命名决定了能否快速定位目标版本，而注册流程决定了整个体系的可靠性。三者缺一不可，共同构成企业级模型资产管理的基础设施。