三层模型体系
这个概念解决什么问题
训练产出的 .pt 文件其实只是一个权重快照，离真正拿去推理还差好几步。同一个架构会反复训练多次（修正数据后再训、调超参后再训），每次训练又可能导出 ONNX、TensorRT 等不同推理格式。如果没有清晰的组织方式，很快就会陷入一堆名字差不多的文件里，根本找不到该用哪个。
VortLab 用三层结构把这件事理顺：Model 系列 → ModelVersion 版本 → ModelArtifact 制品。检测、主动学习、标注这些消费方都绑定到具体制品，不直接绑模型本身。这一页解释三层各自的角色和它们如何协作。
为什么是三层
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
Model（模型系列） | 层级 | 可选 | — | 项目内「同一架构 + 同一任务类型」的容器。例如 Yolov26n-Det 是一个 Model，多次训练累积在它下面。模型是「系列」概念，名称稳定不变。 |
ModelVersion（版本） | 层级 | 可选 | — | 一次训练或上传产出的不可变快照。版本一旦发布，训练超参、数据集版本、汇总指标全部冻结，谁也改不动。 |
ModelArtifact（制品） | 层级 | 可选 | — | 版本下的可执行产物。best.pt 是训练格式，model.onnx 是 ONNX 推理格式，model.engine 是 TensorRT 格式。同版本下可以挂多个不同格式的 Artifact。 |
- Model 名称可以改（用户自定义）。
- Version 一旦发布：训练超参、数据集版本、汇总指标全部冻结。
- Artifact 一旦创建：格式和文件内容固定，导出后不能改。
三层关系示意
Model (系列) 例如：Yolov26n-Det
│
├── ModelVersion v1 (训练快照 #1)
│ ├── ModelArtifact: best.pt (Ultralytics 训练格式)
│ ├── ModelArtifact: model.onnx (ONNX Runtime 推理格式)
│ └── ModelArtifact: model.engine (TensorRT 推理格式)
│
├── ModelVersion v2 (修正数据后重新训练)
│ └── ModelArtifact: best.pt (暂未导出 ONNX/Engine)
│
└── ModelVersion v3 (微调超参后再训)
├── ModelArtifact: best.pt
└── ModelArtifact: model.onnx
- 横向看：同一个 Model 下可以有 N 个 Version，对应 N 次训练。
- 纵向看：同一个 Version 下可以有 N 个 Artifact，对应同一次训练的不同导出格式。
- 同一架构同一任务类型在同一个项目里只会有一个 Model，不会每次训练都新建系列。
发布版本（default_version）
一个 Model 下可能有多个 Version，但运行时消费方需要一个稳定的「当前默认指向」。这就是发布版本。
- 任一时刻每个 Model 有且仅有 1 个发布版本（
default_version_id）+ 0 到 N 个归档版本。 - 在模型详情页通过「设为发布版本」操作切换。
- 设新发布版本时，系统会自动归档旧的发布版本，不需要手动操作。
- 前端 UI 文案称「发布版本」，不叫「默认版本」，避免和「默认值」混淆。
消费者绑定 Artifact，不是 Version
这是三层模型最容易踩坑的点。
检测、主动学习、批量标注这些自动化流程，绑定的都是 ModelArtifact（具体可执行文件），不是 Version 或 Model。
也就是说，如果你要在生产环境跑一个 ONNX 模型，系统会去找版本里那个 format=onnx 的 Artifact 来跑，而不是泛泛地「用 v2 这个版本」。同一个 Version 里如果没有 ONNX Artifact，这个流程就跑不起来。
模型制品有个 source 字段标记来源。普通训练或上传的制品是 training / upload，可以被自动化流程消费。还有两种特殊来源：
draft_test：未发布的训练 draft 测试用，只在交互式检测页能跑，自动化流程会拒绝。active_learning：主动学习内部创建的制品，只服务 AL 流程，不暴露给普通检测。
设计目的是避免未发布或临时的模型意外进入生产环境。
训练自动注册与 draft 状态
训练任务完成后，产物先进入「待发布」状态（completed_pending_registration）。需要你在训练详情面板里点「发布」按钮，把它注册为某个 Model 下的新 Version，才会出现在模型管理列表里。
完整流程是：训练完成 → 待发布 → 用户点「发布」→ 已发布（completed_registered）。
训练跑完还没决定要不要发布？想先看看效果？在训练详情面板里点「测试此 draft」，系统会创建一个 source=draft_test 的临时 Artifact，让你在交互式检测页直接跑这个未发布的权重。满意再回去点「发布」。
draft_test 制品不会出现在模型管理列表里，也不会被任何自动化流程选中，纯粹是给你试水的。
上传模型：立即发布
手动在模型管理页上传一个已经训练好的 .pt 文件，等同于立即发布，没有 draft 阶段。适合拿外部训练好的权重直接接入平台。
上传后这个文件会作为新 Version 注册到对应架构的 Model 下，并自动设为发布版本。
归档不删文件
归档一个 Version 只把它的状态置为 archived，对应的 .pt 权重和导出文件全部保留在存储里。
这是为了让归档版本可以随时恢复（重新设为发布版本），也方便事后对照不同版本的表现。如果你想真的释放存储空间，需要走「删除」而不是「归档」。
- 归档：状态置为 archived，文件保留，可恢复，不出现在训练 / 推理候选列表。
- 删除：物理清除数据库记录和 S3 文件，不可恢复。删除前会列出全部关联（版本数、训练任务关联），确认后才执行。
命名规则
训练自动注册的模型名格式是 {架构}-{任务类型}，例如：
Yolov26n-Det（YOLOv26n 检测模型）Yolov8s-Seg（YOLOv8s 分割模型）Yolo11m-Pose（YOLO11m 姿态模型）Yolov8n-OBB（YOLOv8n 旋转框模型）
任务类型缩写：Det / Seg / Pose / OBB。名称不再追加训练任务名和 _best 后缀。
在模型详情头部 hover 模型名，出现铅笔图标后点一下进入 inline 编辑。回车保存，Esc 取消。改完同步到所有展示位置。