cmvr_edge_ai/models/detection/ppe-6classes-yolov8n/v1/README.md

# PPE Detection YOLOv8n（6 Classes）v1

本版本作为可信 PT 导出源与回滚版本保留；对应 ONNX 制品见
[`ppe-6classes-yolov8n@2`](../v2/README.md)。

## 注册信息

| 字段 | 值 |
|---|---|
| Model ID | `ppe-6classes-yolov8n@1` |
| 注册名称 | `PPE Detection YOLOv8n (6 Classes)` |
| Backend | `ultralytics-yolo` |
| 任务 | 六类 PPE 正向目标检测 |
| 权重 | `models/detection/ppe-6classes-yolov8n/v1/best.pt` |
| 权重格式 | PyTorch/Ultralytics `.pt` checkpoint |
| SHA256 | `07172ef3ae9e256c40a1fb0ce3eefe5547d90170645aa73dded0fffc382cdb31` |

Model ID 的 `@1` 与本目录的 `v1` 对应。替换权重前必须重新核对 SHA256、checkpoint
标签和评估结果；不兼容的新权重应注册为新版本，不能覆盖本文件记录的 `v1`。

## 有序标签

checkpoint 的类别编号必须与下表严格一致，大小写也不能改变：

| ID | 标签 |
|---:|---|
| 0 | `Gloves` |
| 1 | `Vest` |
| 2 | `goggles` |
| 3 | `helmet` |
| 4 | `mask` |
| 5 | `safety_shoe` |

这六个类别都表示“画面中检测到对应装备”。模型没有 `Person` 或 `No-*` 类，不能把
“没有检测到 helmet”直接解释为“某个人没有佩戴安全帽”。如需人员违规判断，必须增加
人员检测、人员与 PPE 空间关联以及缺失判定逻辑。

## 输入与运行参数

- 输入必须是已经解码的 packed `BGR8` 或 `RGB8` 图像，buffer 大小为
  `width × height × 3`；adapter 会把 `RGB8` 转换为 backend 使用的 BGR 顺序。
- 训练/常用推理尺寸为 `640`；实际推理尺寸由 `model_options.imgsz` 控制。
- 当前项目锁定的 Ultralytics 版本为 `8.4.31`。部署 `.pt` 时还需要与目标设备匹配的
  PyTorch 运行时。
- CPU 部署使用 `device: cpu`、`half: false`。CUDA/Jetson 必须使用与驱动或
  JetPack 匹配的独立环境，不能只修改 `device`。

常用参数：

| 参数 | 说明 |
|---|---|
| `weights` | 本模型权重路径，必填 |
| `device` | `cpu`、`cuda:0` 或非负 GPU 编号 |
| `imgsz` | 推理尺寸，默认 `640` |
| `iou` | NMS IoU 阈值，默认 `0.70` |
| `half` | 是否使用 FP16，CPU 应保持 `false` |
| `max_det` | 单帧最大检测框数 |
| `agnostic_nms` | 是否启用类别无关 NMS |

## YAML 示例

以下相对路径假定从仓库根目录启动：

```yaml
detector:
  uses: detection.model@1
  with:
    model: ppe-6classes-yolov8n@1
    detect_labels:
      - Gloves
      - Vest
      - goggles
      - helmet
      - mask
      - safety_shoe
    confidence: 0.50
    max_fps: 10
    attach_frame: false
    model_options:
      weights: models/detection/ppe-6classes-yolov8n/v1/best.pt
      device: cpu
      imgsz: 640
      iou: 0.70
      half: false
      max_det: 100
```

## 训练与评估摘要

原模型说明记录了 YOLOv8n 基础模型、50 个 epoch、`imgsz=640`、`batch=32`，以及以下
近似结果：

| 指标 | 原说明记录值 |
|---|---:|
| mAP50 | `~0.81` |
| mAP50-95 | `~0.53` |
| Precision | `~0.80` |
| Recall | `~0.74` |

原说明记录的逐类 mAP50 约为：`Gloves 0.69`、`Vest 0.90`、`goggles 0.90`、
`helmet 0.90`、`mask 0.80`、`safety_shoe 0.64`。这些数据未由 cmvr-edge-ai 在目标园区
数据上独立复现，不能替代部署前的现场验证。

## 限制与风险

- 低照度、运动模糊、远距离小目标、遮挡和不同地区的 PPE 外观会降低准确率。
- 原数据存在类别不均衡，`goggles` 和 `safety_shoe` 等类别应重点做现场回归测试。
- 模型只检测 PPE 的出现，不进行人员检测、目标跟踪或人员/PPE 归属判断。
- 不应在没有人工复核的情况下用于处罚、法律执法或其他高风险决定。
- 摄像采集和平台上报仍需遵守工作场所隐私、告知和数据保留要求。

## 许可证与来源

- 原模型卡声明权重许可证为 MIT。
- 模型基于 Ultralytics YOLOv8；Ultralytics 软件及商业使用可能受其许可证约束，部署方
  必须自行核对当前适用条款。
- 原模型说明称训练数据为自定义 Roboflow 格式 PPE 数据集，但没有在本目录提供完整的
  数据授权链。部署方应在商业或高风险使用前核对数据来源和许可。
- 本目录只记录 v1 `.pt`；v2 ONNX 制品在相邻版本目录维护。
- 权重来源为 Hugging Face 上的
  [`Tanishjain9/yolov8n-ppe-detection-6classes`](https://huggingface.co/Tanishjain9/yolov8n-ppe-detection-6classes)；
  仓库内以本目录路径和上述 SHA256 作为部署制品标识。