计算机视觉 / 系统课时
管理模型版本
管理模型版本
模型上线后,真正需要管理的不是一个孤立的权重文件,而是可复现、可审计、可切换的完整版本。本课将建立轻量模型注册表,记录数据、参数、指标与发布时间,并用环境别名完成发布和回滚。
学习目标
- 明确模型版本、训练记录与线上环境别名的职责边界
- 为每个版本保存模型文件、数据标识、训练参数、评估指标和哈希
- 使用不可变版本与可变别名完成发布、追踪和快速回滚
版本管理要解决什么
同一个 YOLOv8 项目可能连续训练几十次,但只有通过验收的产物才应成为模型版本。训练记录用于复现实验,模型版本用于交付,环境别名则说明测试或生产当前加载哪个版本。
| 对象 | 主要内容 | 是否允许覆盖 |
|---|---|---|
| 训练记录 | 数据集、参数、日志、检查点 | 不建议覆盖 |
| 模型版本 | 权重、导出文件、指标、哈希、发布时间 | 不允许覆盖 |
| 环境别名 | staging、production 指向的版本 |
允许切换 |

设计不可变的版本目录
版本号可以采用 主版本。次版本。修订号,例如 1.2.0。主版本表示输出协议或类别体系不兼容,次版本表示数据或训练方案发生明显升级,修订号用于兼容范围内的修复。已经登记的目录不得原地替换,否则哈希、指标和线上问题将无法对应。
每个版本至少记录模型文件路径与 SHA-256、训练数据集标识、核心参数、离线指标、代码提交号、登记时间和发布时间。数据集标识应指向固定快照或清单哈希,不能只写容易变化的目录名。
用本地注册表完成发布与回滚
下面的完整示例只使用 Python 标准库。它创建两个演示模型版本,将 production 指向较新版本,再通过切换别名回滚到旧版本。实际项目中可把演示文件替换为 best.pt、ONNX 或 TensorRT 引擎。
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()预期输出
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 而不记录数据集和类别定义,同样无法解释效果变化。版本号还应与服务代码兼容性分开记录,避免模型可回滚而接口协议无法回滚。