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
people-talking-yolov8x@1	people-talking-yolov8x/v1	ultralytics-yolo	2	上游通用 label 类及 talking on phone 行为类
yolov8n-mobile-phone@1	yolov8n-mobile-phone	ultralytics-yolo	1	画面中的 mobile_phone 手机物体

四个 onnxruntime-yolov8 的 @2 制品已经生成：

注册模型 ID	制品与模型卡	SHA256
construction-ppe-yolov8@2	construction-ppe-yolov8/v2	b8e5d116...0b57a
ppe-6classes-yolov8n@2	ppe-6classes-yolov8n/v2	6cb0e567...3c03b
people-talking-yolov8x@2	people-talking-yolov8x/v2	b4387307...e840b
yolov8n-mobile-phone@2	yolov8n-mobile-phone/v2	df170d9b...f857f

三个部署 YAML 已切换到 @2。运行时会先校验同目录 manifest.json、模型身份、标签、 输入尺寸和整个 ONNX 文件 SHA256，再创建 ONNX Runtime session。

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

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

配置规则

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

nodes:
  detector:
    uses: detection.model@1
    with:
      model: construction-ppe-yolov8@2
      model_options:
        weights: models/detection/construction-ppe-yolov8/v2/model.onnx
        providers: [CPUExecutionProvider]
        intra_op_threads: 1
        inter_op_threads: 1

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

当前主动 Pipeline 会从同一个 decoder 并行运行 Construction PPE 与 People-Talking 两个 detector。People-Talking checkpoint 的 class 0 名称是含义不清的 label；注册 表为保证 ID 对齐而保留它，但部署配置只选择 talking on phone。

configs/detection_viewer.yaml 不改变生产告警链路，它使用 yolov8n-mobile-phone@2 替代 People-Talking，与 Construction PPE 同帧显示。该模型 只说明画面中检测到手机物体，不能直接判断人员正在通话。

新增版本

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

1. 新建独立的 <model-name>/v<version>/ 目录；已有的 yolov8n-mobile-phone@1 保留上游文件名和扁平目录，后续版本应恢复这一约定；
2. 把完整权重作为普通 Git 文件提交，并编写完整模型卡；
3. 使用 SHA256 校验权重来源和复制结果；
4. 在 DetectionModelRegistry 中注册唯一的 <model-name>@<version>；
5. 保证 supported_labels 与 checkpoint 类别编号严格同序；
6. 更新部署 YAML，并先执行 cmvr-edge-ai models 和 cmvr-edge-ai validate。

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

ONNX 导出与验收

运行 ONNX 模型的边缘环境不需要 Torch/Ultralytics：

uv sync --locked --extra onnx-cpu

构建机安装锁定的 PT 与 ONNX 导出依赖，并一次导出一个目标版本：

uv sync --locked --extra onnx-export-cpu
uv run --no-sync python scripts/export_detection_onnx.py \
  --model-id yolov8n-mobile-phone@2

导出脚本固定 batch=1、dynamic=false、nms=false 和 CPU FP32，验证 source checkpoint 标签、ONNX checker、静态图输入输出及 metadata，清除训练机路径/时间戳， 然后生成普通 Git 文件 model.onnx 和记录来源/制品 SHA256 的 manifest.json。脚本 不会执行 INT8 量化，也不会自动修改部署 YAML。

当前已完成制品哈希、真实 ORT 加载/推理和配置编译测试；投入现场前仍须执行：

1. 用现场代表性图片逐图比较 .pt 与 ONNX 的类别、框、置信度和 NMS 后数量；
2. 在目标边缘端测量冷启动、稳态 P50/P95 延迟、峰值 RSS、CPU 占用和连续运行；
3. 复核 manifest.json、模型卡、许可和普通 Git 服务端的单文件大小限制；
4. 使用非方形现场图；PT parity 基线必须显式 rect=False，与静态 640×640 ONNX letterbox 语义保持一致。

People-Talking 的源模型是 YOLOv8x，参数量和计算量远高于三个较小模型。ONNX 可减少 Python runtime 依赖，但不会自动降低网络 FLOPs；如果目标设备仍不达标，应重新训练 n/s 级模型或使用有现场校准集的 INT8 流程，而不是把未校准量化结果直接发布。