模型迭代最怕的不是版本多，而是版本之间没有关系：目录里堆着 model_final.pkl、model_final_v2.pkl 和 model_really_final.pkl，却没人能迅速回答“改了什么”“当前使用哪一版”“出了问题怎么退回去”。
qModel 算法模型平台开源版 v1.4.2 增加了模型版本管理与版本对比能力，并在模型详情页提供独立的版本管理入口。新版本可以基于现有版本创建，也可以与任意历史版本横向比较；多个版本能够并存、切换，并在需要时回滚。这让模型管理从简单保存文件，向可追踪的版本治理迈进了一步。
版本不只是文件名，而是一条演进链
传统做法经常用目录名或文件名表达版本：
models/
├── fraud_model_v1.pkl
├── fraud_model_v2.pkl
├── fraud_model_v2_new.pkl
└── fraud_model_final.pkl
这种结构能保存文件，却保存不了决策过程。团队仍然不知道：
v2是从哪个版本训练出来的；- 特征、参数、数据集或评估指标发生了什么变化；
- 哪个版本正在使用；
final是否真的比v1更好；- 回滚时应该恢复模型文件，还是连同推理配置一起恢复。
基于现有版本创建新版本，关键价值就在于建立父子关系。每次迭代不再是孤立副本，而是演进链中的一个节点。例如：
信用风险模型
└── v1.0：初始基线
├── v1.1：调整特征集合
│ └── v1.2：修改分类阈值
└── v2.0：更换训练数据窗口
当实验方向出现分叉时，多版本并存也比覆盖旧文件安全。团队可以保留稳定基线，同时验证新数据、新特征或新算法，而不必牺牲可追溯性。
横向对比应该回答哪些问题
qModel v1.4.2 支持任意两个版本横向对比。实际使用时，不要只比较版本号或模型文件大小，最好围绕四类信息检查差异：
| 对比维度 | 典型内容 | 需要回答的问题 |
|---|---|---|
| 训练来源 | 数据集、时间窗口、样本过滤条件 | 指标变化是否来自数据变化？ |
| 模型配置 | 算法、超参数、随机种子 | 是否可以复现实验？ |
| 评估结果 | Accuracy、F1、AUC、延迟 | 新版本是否在目标指标上更好？ |
| 运行约束 | 输入字段、依赖版本、硬件要求 | 切换后是否会破坏现有服务？ |
版本对比的目的不是证明“新版本一定更好”，而是让差异足够明确。例如，AUC 从 0.91 提升到 0.92，但推理延迟从 30 毫秒增加到 120 毫秒，这可能并不适合在线风控；反过来，离线批处理任务则可能愿意接受这项成本。
因此，团队在创建版本时应固定记录最小元数据：
version: v1.2.0
parent_version: v1.1.0
artifact: model.bin
training_dataset: risk_train_2025_01
algorithm: xgboost
parameters:
max_depth: 8
learning_rate: 0.05
metrics:
auc: 0.923
f1: 0.847
runtime:
python: '3.11'
inference_latency_ms: 42
change_note: 增加近30天交易频率特征
这份 YAML 是一种可以采用的治理方式，并不代表 qModel 要求使用这一固定字段结构。重点是让每个版本同时具备产物、来源、指标和变更说明。
可以这样实践：在接入平台前整理版本元数据
如果团队目前还在共享目录中管理模型，可以先用一个小脚本建立“创建、对比、激活”的基本习惯，再把相同规则迁移到 qModel 的版本管理流程中。下面的示例只依赖 Python 标准库，是一个本地演示，并非 qModel 的官方 API。
将以下内容保存为 model_registry.py：
import argparse
import difflib
import json
import shutil
from pathlib import Path
ROOT = Path('model_registry')
def version_dir(version):
return ROOT / 'versions' / version
def load_manifest(version):
path = version_dir(version) / 'manifest.json'
if not path.exists():
raise SystemExit(f'版本不存在: {version}')
return json.loads(path.read_text(encoding='utf-8'))
def create(args):
target = version_dir(args.version)
if target.exists():
raise SystemExit(f'版本已存在: {args.version}')
if args.parent:
load_manifest(args.parent)
source = Path(args.artifact)
if not source.is_file():
raise SystemExit(f'模型文件不存在: {source}')
target.mkdir(parents=True)
shutil.copy2(source, target / source.name)
manifest = {
'version': args.version,
'parent_version': args.parent,
'artifact': source.name,
'metric': {'name': args.metric_name, 'value': args.metric_value},
'change_note': args.note,
}
(target / 'manifest.json').write_text(
json.dumps(manifest, ensure_ascii=False, indent=2),
encoding='utf-8',
)
print(f'已创建 {args.version}')
def compare(args):
left = json.dumps(load_manifest(args.left), ensure_ascii=False, indent=2).splitlines()
right = json.dumps(load_manifest(args.right), ensure_ascii=False, indent=2).splitlines()
print('\n'.join(difflib.unified_diff(
left,
right,
fromfile=args.left,
tofile=args.right,
lineterm='',
)))
def activate(args):
load_manifest(args.version)
ROOT.mkdir(exist_ok=True)
(ROOT / 'ACTIVE_VERSION').write_text(args.version + '\n', encoding='utf-8')
print(f'当前版本已切换为 {args.version}')
parser = argparse.ArgumentParser(description='最小模型版本登记示例')
subparsers = parser.add_subparsers(required=True)
create_parser = subparsers.add_parser('create')
create_parser.add_argument('version')
create_parser.add_argument('--parent')
create_parser.add_argument('--artifact', required=True)
create_parser.add_argument('--metric-name', default='auc')
create_parser.add_argument('--metric-value', type=float, required=True)
create_parser.add_argument('--note', required=True)
create_parser.set_defaults(func=create)
compare_parser = subparsers.add_parser('compare')
compare_parser.add_argument('left')
compare_parser.add_argument('right')
compare_parser.set_defaults(func=compare)
activate_parser = subparsers.add_parser('activate')
activate_parser.add_argument('version')
activate_parser.set_defaults(func=activate)
args = parser.parse_args()
args.func(args)
准备两个示例模型文件并执行：
mkdir -p artifacts
printf 'baseline-model' > artifacts/model-v1.bin
printf 'candidate-model' > artifacts/model-v2.bin
python model_registry.py create v1.0.0 \
--artifact artifacts/model-v1.bin \
--metric-value 0.901 \
--note '初始基线'
python model_registry.py create v1.1.0 \
--parent v1.0.0 \
--artifact artifacts/model-v2.bin \
--metric-value 0.923 \
--note '增加近30天交易频率特征'
python model_registry.py compare v1.0.0 v1.1.0
python model_registry.py activate v1.1.0
# 出现异常时切回历史版本
python model_registry.py activate v1.0.0
cat model_registry/ACTIVE_VERSION
这个示例故意保持简单，但已经体现了三个重要约束：版本不可静默覆盖、新版本记录父版本、切换动作留下明确的当前版本指针。迁移到平台后，可以把人工目录操作替换为 qModel 中的创建版本、版本对比、切换与回滚流程。
回滚不等于模型文件换回去
版本回滚很实用，但需要先确认平台中的“回滚”覆盖哪些对象。模型线上运行通常还依赖以下内容：
- 特征处理代码与字段顺序；
- Tokenizer、标签字典或归一化参数；
- Python 与推理框架版本；
- 服务配置、流量策略和资源规格；
- 数据库结构或上下游接口。
如果只回滚模型文件，却保留新版本的预处理逻辑，旧模型仍可能无法工作。更稳妥的做法是把模型版本与运行环境版本关联起来，并在正式切换前执行冒烟测试。
可以为每次切换设置一份最小检查单：
- [ ] 新版本的父版本、变更说明和负责人清晰；
- [ ] 关键指标与当前版本完成横向比较；
- [ ] 输入输出结构保持兼容，或已有配套改造；
- [ ] 模型产物经过校验，依赖与环境可复现；
- [ ] 切换前保存当前稳定版本；
- [ ] 回滚步骤经过测试，而不是只写在文档里；
- [ ] 切换后持续观察错误率、延迟和业务指标。
qModel v1.4.2 补齐的是模型持续迭代中的关键管理环节。真正发挥价值，还需要团队统一版本命名、元数据记录、比较标准和回滚边界。做到这些之后，模型版本才不再是一批散落的文件，而会成为一条可以检查、讨论和恢复的工程链路。