108 lines
5.3 KiB
Markdown
108 lines
5.3 KiB
Markdown
# 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](construction-ppe-yolov8/v1/README.md) | `ultralytics-yolo` | 19 | PPE、PPE 缺失违规及部分现场设备 |
|
||
| `ppe-6classes-yolov8n@1` | [ppe-6classes-yolov8n/v1](ppe-6classes-yolov8n/v1/README.md) | `ultralytics-yolo` | 6 | 画面中实际出现的六类 PPE |
|
||
| `people-talking-yolov8x@1` | [people-talking-yolov8x/v1](people-talking-yolov8x/v1/README.md) | `ultralytics-yolo` | 2 | 上游通用 `label` 类及 `talking on phone` 行为类 |
|
||
| `yolov8n-mobile-phone@1` | [yolov8n-mobile-phone](yolov8n-mobile-phone/README.md) | `ultralytics-yolo` | 1 | 画面中的 `mobile_phone` 手机物体 |
|
||
|
||
四个 `onnxruntime-yolov8` 的 `@2` 制品已经生成：
|
||
|
||
| 注册模型 ID | 制品与模型卡 | SHA256 |
|
||
|---|---|---|
|
||
| `construction-ppe-yolov8@2` | [construction-ppe-yolov8/v2](construction-ppe-yolov8/v2/README.md) | `b8e5d116...0b57a` |
|
||
| `ppe-6classes-yolov8n@2` | [ppe-6classes-yolov8n/v2](ppe-6classes-yolov8n/v2/README.md) | `6cb0e567...3c03b` |
|
||
| `people-talking-yolov8x@2` | [people-talking-yolov8x/v2](people-talking-yolov8x/v2/README.md) | `b4387307...e840b` |
|
||
| `yolov8n-mobile-phone@2` | [yolov8n-mobile-phone/v2](yolov8n-mobile-phone/v2/README.md) | `df170d9b...f857f` |
|
||
|
||
三个部署 YAML 已切换到 `@2`。运行时会先校验同目录 `manifest.json`、模型身份、标签、
|
||
输入尺寸和整个 ONNX 文件 SHA256，再创建 ONNX Runtime session。
|
||
|
||
可通过以下命令查看运行时注册信息及有序标签：
|
||
|
||
```bash
|
||
uv run --no-sync cmvr-edge-ai models
|
||
```
|
||
|
||
## 配置规则
|
||
|
||
相对权重路径按启动进程的当前工作目录解析。本文档中的示例假定命令从仓库根目录执行：
|
||
|
||
```yaml
|
||
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：
|
||
|
||
```bash
|
||
uv sync --locked --extra onnx-cpu
|
||
```
|
||
|
||
构建机安装锁定的 PT 与 ONNX 导出依赖，并一次导出一个目标版本：
|
||
|
||
```bash
|
||
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 流程，而不是把未校准量化结果直接发布。
|