cmvr_edge_ai/models/detection/README.md

Detection 模型资产

本目录集中管理 cmvr-edge-ai 已注册的目标检测模型。Pipeline 仍统一使用 detection.model@1 节点；节点的 with.model 选择注册 ID， with.model_options.weights 选择本目录中的具体权重。

当前模型

注册模型 ID	版本目录	Backend	标签数	标签语义
construction-ppe-yolov8@1	construction-ppe-yolov8/v1	ultralytics-yolo	19	PPE、PPE 缺失违规及部分现场设备
ppe-6classes-yolov8n@1	ppe-6classes-yolov8n/v1	ultralytics-yolo	6	画面中实际出现的六类 PPE

可通过以下命令查看运行时注册信息及有序标签：

uv run --no-sync cmvr-edge-ai models

配置规则

相对权重路径按启动进程的当前工作目录解析。本文档中的示例假定命令从仓库根目录执行：

nodes:
  detector:
    uses: detection.model@1
    with:
      model: construction-ppe-yolov8@1
      model_options:
        weights: models/detection/construction-ppe-yolov8/v1/best.pt

模型加载时会严格比较 checkpoint 的类别名称和顺序与注册信息。权重不匹配时节点会停止 启动，不能通过只修改 detect_labels 绕过类别校验。

新增版本

新增 Detection 模型或模型版本时：

1. 新建独立的 <model-name>/v<version>/ 目录；
2. 放入 Git LFS 管理的权重并编写完整模型卡；
3. 使用 SHA256 校验权重来源和复制结果；
4. 在 DetectionModelRegistry 中注册唯一的 <model-name>@<version>；
5. 保证 supported_labels 与 checkpoint 类别编号严格同序；
6. 更新部署 YAML，并先执行 cmvr-edge-ai models 和 cmvr-edge-ai validate。

数据集压缩包、训练集和训练过程缓存不属于部署资产，不应放入本目录。