# Construction PPE YOLOv8s v1

本版本作为可信 PT 导出源与回滚版本保留；当前部署使用
[`construction-ppe-yolov8@2`](../v2/README.md) ONNX 制品。

## 注册信息

| 字段 | 值 |
|---|---|
| Model ID | `construction-ppe-yolov8@1` |
| 注册名称 | `Construction PPE YOLOv8s` |
| Backend | `ultralytics-yolo` |
| 任务 | 施工/园区人员 PPE、PPE 缺失违规及部分现场设备检测 |
| 权重 | `models/detection/construction-ppe-yolov8/v1/best.pt` |
| 权重格式 | PyTorch/Ultralytics `.pt` checkpoint |
| SHA256 | `31ef3ca04a17cf545f3fcfc64c4af8993a41d52ccc460e82aff01d5354603533` |

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

## 有序标签

checkpoint 的类别编号必须与下表严格一致：

| ID | 标签 | ID | 标签 |
|---:|---|---:|---|
| 0 | `Boots` | 10 | `No-Helmet` |
| 1 | `Ear-Protection` | 11 | `No-Mask` |
| 2 | `Glass` | 12 | `No-Vest` |
| 3 | `Glove` | 13 | `Worker` |
| 4 | `Hard_hat` | 14 | `Vest` |
| 5 | `Mask` | 15 | `Circular_Saw` |
| 6 | `No-Boots` | 16 | `Fire_Extinguisher` |
| 7 | `No-Ear-Protection` | 17 | `Fire_prevention_Net` |
| 8 | `No-Glass` | 18 | `Welding_Equipment` |
| 9 | `No-Glove` |  |  |

`No-*` 是模型直接输出的违规类别，不是框架根据正向 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: construction-ppe-yolov8@1
    detect_labels:
      - No-Boots
      - No-Ear-Protection
      - No-Glass
      - No-Glove
      - No-Helmet
      - No-Mask
      - No-Vest
    confidence: 0.50
    max_fps: 10
    attach_frame: true
    model_options:
      weights: models/detection/construction-ppe-yolov8/v1/best.pt
      device: cpu
      imgsz: 640
      iou: 0.70
      half: false
      max_det: 100
```

## 训练与评估摘要

原模型说明记录了约 13,000 张训练图像、60 个 epoch，以及以下近似结果：

| 指标 | 原说明记录值 |
|---|---:|
| mAP50 | `~0.76` |
| mAP50-95 | `~0.43` |
| Precision | `~0.81` |
| Recall | `~0.72` |

这些数据来自原模型说明，未由 cmvr-edge-ai 在目标园区数据上独立复现，不能替代部署前
的现场验证。

## 限制与风险

- `Ear-Protection` 样本不足，相关正向或违规结果应谨慎使用。
- `Boots`、`No-Ear-Protection`、`No-Glove` 等类别可能出现漏检。
- 远距离小目标、遮挡、运动模糊、低照度、摄像机角度和区域性 PPE 样式会影响效果。
- 模型尚未证明能泛化到所有园区、工地或人群；告警应用应保留人工复核。
- 模型同时检测人员、PPE 和现场设备，但不提供目标跟踪，也不保证每件 PPE 与具体人员
  的空间关联正确。

## 许可证与来源

- 原模型卡声明权重许可证为 Apache-2.0。
- 模型基于 Ultralytics YOLOv8；Ultralytics 软件及商业使用可能受其许可证约束，部署方
  必须自行核对当前适用条款。
- 训练数据由多个公开来源合并，原说明指出主要来自 Roboflow，并包含其他 GitHub 来源；
  各底层数据集可能有独立许可证。当前模型卡不能替代对训练数据授权链的审查。
- 权重来源为 Hugging Face 上的
  [`killuminati1/construction-ppe-yolov8`](https://huggingface.co/killuminati1/construction-ppe-yolov8)；
  仓库内以本目录路径和上述 SHA256 作为部署制品标识。