4. 模型版本管理：模型注册中心设计、版本号语义化规范、模型热加载与回滚机制

在风控网关的模型服务工程中，模型版本管理是保障线上推理稳定性的核心基础设施。本章围绕模型注册中心的设计原则、版本号语义化规范以及热加载与回滚机制展开，帮助构建可追溯、可回退、可灰度验证的模型治理体系。

4.1 模型注册中心设计

模型注册中心是风控网关中所有模型元数据的集中存储与发现服务。它负责管理模型的生命周期状态、部署路径、输入输出签名以及运行时配置。

4.1.1 核心功能模块

4.1.2 注册中心架构

下图展示了模型注册中心在风控网关中的位置及其与周边组件的交互关系：

4.2 版本号语义化规范

模型版本号采用 语义化版本 2.0.0 规范，格式为 MAJOR.MINOR.PATCH，并扩展了预发布与构建元数据字段，以支持风控场景下的灰度验证与紧急修复。

4.2.1 版本号格式

MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD_METADATA]

示例：
1.0.0              # 正式发布版本
1.1.0-beta.1       # 灰度测试版本
1.1.0-rc.2         # 候选发布版本
1.1.0+20250315     # 带构建日期的正式版本
2.0.0-hotfix.001   # 紧急热修复版本

4.2.2 版本号递增规则

4.2.3 版本生命周期状态机

4.3 模型热加载与回滚机制

风控网关要求模型更新时不影响正在处理的推理请求，因此必须实现无中断的热加载机制，并配套快速回滚能力以应对模型效果下降或异常情况。

4.3.1 热加载流程

1. 版本探测：网关定期轮询注册中心，获取当前路由绑定的最新模型版本号。
2. 文件校验：下载模型文件前，比对注册中心记录的 MD5 值与本地缓存是否一致，避免重复下载。
3. 影子加载：在独立内存区域加载新模型，加载期间不切换流量，加载完成后执行签名校验。
4. 健康检查：对影子模型发送 3~5 条探针请求，验证推理结果是否符合预期。
5. 原子切换：通过指针交换或读写锁，将流量从旧模型实例切换到新模型实例。
6. 旧模型保留：旧模型实例保留 30 秒（可配置），用于快速回滚。

4.3.2 回滚触发条件

4.3.3 热加载与回滚状态机

4.3.4 关键代码示例：原子切换

// 使用读写锁实现模型实例的原子切换
public class ModelRouter {
    private volatile ModelInstance currentInstance;
    private final ReadWriteLock lock = new ReentrantReadWriteLock();

    public ModelInstance getInstance() {
        // 读操作不加锁，利用 volatile 保证可见性
        return currentInstance;
    }

    public boolean hotSwap(ModelInstance newInstance) {
        lock.writeLock().lock();
        try {
            // 1. 执行健康检查
            if (!newInstance.healthCheck()) {
                return false;
            }
            // 2. 保留旧实例用于回滚
            ModelInstance oldInstance = this.currentInstance;
            // 3. 原子切换
            this.currentInstance = newInstance;
            // 4. 延迟销毁旧实例（30秒后）
            scheduleDestroy(oldInstance, 30_000);
            return true;
        } finally {
            lock.writeLock().unlock();
        }
    }

    public void rollback(ModelInstance fallbackInstance) {
        lock.writeLock().lock();
        try {
            this.currentInstance = fallbackInstance;
            log.warn("模型已回滚至版本: {}", fallbackInstance.getVersion());
        } finally {
            lock.writeLock().unlock();
        }
    }
}