计算机视觉 / 系统课时

管理模型版本

管理模型版本

模型上线后,真正需要管理的不是一个孤立的权重文件,而是可复现、可审计、可切换的完整版本。本课将建立轻量模型注册表,记录数据、参数、指标与发布时间,并用环境别名完成发布和回滚。

学习目标

  • 明确模型版本、训练记录与线上环境别名的职责边界
  • 为每个版本保存模型文件、数据标识、训练参数、评估指标和哈希
  • 使用不可变版本与可变别名完成发布、追踪和快速回滚

版本管理要解决什么

同一个 YOLOv8 项目可能连续训练几十次,但只有通过验收的产物才应成为模型版本。训练记录用于复现实验,模型版本用于交付,环境别名则说明测试或生产当前加载哪个版本。

对象 主要内容 是否允许覆盖
训练记录 数据集、参数、日志、检查点 不建议覆盖
模型版本 权重、导出文件、指标、哈希、发布时间 不允许覆盖
环境别名 staging、production 指向的版本 允许切换

模型版本注册、发布与回滚流程

设计不可变的版本目录

版本号可以采用 主版本。次版本。修订号,例如 1.2.0。主版本表示输出协议或类别体系不兼容,次版本表示数据或训练方案发生明显升级,修订号用于兼容范围内的修复。已经登记的目录不得原地替换,否则哈希、指标和线上问题将无法对应。

每个版本至少记录模型文件路径与 SHA-256、训练数据集标识、核心参数、离线指标、代码提交号、登记时间和发布时间。数据集标识应指向固定快照或清单哈希,不能只写容易变化的目录名。

用本地注册表完成发布与回滚

下面的完整示例只使用 Python 标准库。它创建两个演示模型版本,将 production 指向较新版本,再通过切换别名回滚到旧版本。实际项目中可把演示文件替换为 best.pt、ONNX 或 TensorRT 引擎。

python
import hashlib
import json
import shutil
from pathlib import Path

ROOT = Path("model_registry")
ARTIFACTS = Path("demo_artifacts")

def sha256(path: Path) -> str:
    digest = hashlib.sha256()
    with path.open("rb") as file:
        for chunk in iter(lambda: file.read(8192), b""):
            digest.update(chunk)
    return digest.hexdigest()

def register(version: str, artifact: Path, dataset: str,
             params: dict, metrics: dict, released_at: str) -> None:
    version_dir = ROOT / "versions" / version
    if version_dir.exists():
        raise FileExistsError(f"版本 {version} 已存在,禁止覆盖")

    version_dir.mkdir(parents=True)
    target = version_dir / artifact.name
    shutil.copy2(artifact, target)

    # manifest 把模型文件与训练上下文绑定为一个可审计版本
    manifest = {
        "version": version,
        "artifact": target.name,
        "sha256": sha256(target),
        "dataset": dataset,
        "params": params,
        "metrics": metrics,
        "releasedAt": released_at,
    }
    (version_dir / "manifest.json").write_text(
        json.dumps(manifest, ensure_ascii=False, indent=2),
        encoding="utf-8",
    )

def point_stage(stage: str, version: str) -> None:
    manifest_path = ROOT / "versions" / version / "manifest.json"
    if not manifest_path.exists():
        raise FileNotFoundError(f"未登记版本 {version}")

    # 发布和回滚只修改环境别名,不改动任何历史版本
    stage_dir = ROOT / "stages"
    stage_dir.mkdir(parents=True, exist_ok=True)
    (stage_dir / f"{stage}.json").write_text(
        json.dumps({"version": version}, indent=2),
        encoding="utf-8",
    )

def read_stage(stage: str) -> dict:
    alias = json.loads(
        (ROOT / "stages" / f"{stage}.json").read_text(encoding="utf-8")
    )
    manifest_path = ROOT / "versions" / alias["version"] / "manifest.json"
    return json.loads(manifest_path.read_text(encoding="utf-8"))

def main() -> None:
    # 清理的仅是本示例创建的目录,便于重复运行
    shutil.rmtree(ROOT, ignore_errors=True)
    shutil.rmtree(ARTIFACTS, ignore_errors=True)
    ARTIFACTS.mkdir()
    (ARTIFACTS / "yolov8-v1.onnx").write_bytes(b"demo-model-v1")
    (ARTIFACTS / "yolov8-v2.onnx").write_bytes(b"demo-model-v2")

    register("1.0.0", ARTIFACTS / "yolov8-v1.onnx", "dataset-2026-07",
             {"imgsz": 640, "epochs": 100}, {"map50": 0.817},
             "2026-08-01T09:00:00+08:00")
    register("1.1.0", ARTIFACTS / "yolov8-v2.onnx", "dataset-2026-08",
             {"imgsz": 640, "epochs": 120}, {"map50": 0.842},
             "2026-08-03T18:00:00+08:00")

    point_stage("production", "1.1.0")
    current = read_stage("production")
    print(f"published production={current['version']} map50={current['metrics']['map50']}")

    point_stage("production", "1.0.0")
    current = read_stage("production")
    print(f"rollback production={current['version']} map50={current['metrics']['map50']}")
    print("manifest=model_registry/versions/1.0.0/manifest.json")

if __name__ == "__main__":
    main()

预期输出

text
published production=1.1.0 map50=0.842
rollback production=1.0.0 map50=0.817
manifest=model_registry/versions/1.0.0/manifest.json

接入推理服务并完成验收

推理服务启动时应先读取环境别名,再读取对应 manifest.json 和模型文件。服务日志、响应头或内部追踪信息中要记录实际版本号,这样线上异常才能反查到数据集、参数和指标。

正式切换前应完成模型文件哈希校验、加载与预热、固定样本冒烟测试、接口兼容性检查和关键指标对比。回滚时只把 production 指回已验证的旧版本,重启或热加载服务后再次执行同一组检查。

Tips:数据库或对象存储可以替代本地目录,但“版本不可变、别名可切换、发布可审计”这三个原则不要改变。

常见错误

不要用 best.pt 作为唯一身份,也不要上传同名文件覆盖旧模型。只保存 mAP 而不记录数据集和类别定义,同样无法解释效果变化。版本号还应与服务代码兼容性分开记录,避免模型可回滚而接口协议无法回滚。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

管理模型版本

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通