# AI 模型说明文档

本文档说明 `models/` 目录中各 AI 模型的用途、类别映射及配置参数。

## 目录结构

```
models/
├── best-768.rknn                  # YOLO PPE检测模型 (11类，实际使用2类)
├── yolov5s-640-640.rknn           # YOLOv5 COCO预训练模型 (80类)
├── yolov8n-640.rknn               # YOLOv8n COCO预训练模型 (80类)
├── RetinaFace_mobile320.rknn      # 人脸检测模型
├── mobilefacenet_arcface.rknn     # 人脸识别模型
└── face_gallery.db                # 人脸特征库 (SQLite)
```

## 模型详情

### 1. best-768.rknn (PPE11)

**类型**: YOLOv8 PPE检测模型  
**输入尺寸**: 768x768  
**类别数**: 11  
**实际使用类别**: 2 (boots + Person)

| 索引 | 类别名 | 业务使用 | 说明 |
|------|--------|----------|------|
| 0 | helmet | ❌ | 安全帽 |
| 1 | gloves | ❌ | 手套 |
| 2 | vest | ❌ | 反光背心 |
| 3 | **boots** | ✅ | 安全靴 |
| 4 | goggles | ❌ | 护目镜 |
| 5 | none | ❌ | 无/背景 |
| 6 | **Person** | ✅ | 人 |
| 7 | no_helmet | ❌ | 未戴安全帽 |
| 8 | no_goggle | ❌ | 未戴护目镜 |
| 9 | no_gloves | ❌ | 未戴手套 |
| 10 | no_boots | ❌ | 未穿安全靴 (不作为告警依据) |

**业务侧只消费**: `class_id in {3, 6}` (boots 和 Person)

**配置示例**:
```json
{
  "type": "ai_yolo",
  "model_path": "./models/best-768.rknn",
  "model_version": "v8",
  "model_w": 768,
  "model_h": 768,
  "num_classes": 11,
  "conf": 0.2,
  "nms": 0.45,
  "class_filter": [3, 6]
}
```

**OSD标签配置**:
```json
{
  "type": "osd",
  "labels": ["helmet", "gloves", "vest", "boots", "goggles", "none", "Person", "no_helmet", "no_goggle", "no_gloves", "no_boots"]
}
```

**Tracker配置**:
```json
{
  "type": "tracker",
  "track_classes": [3, 6],
  "per_class": true
}
```

---

### 2. yolov5s-640-640.rknn

**类型**: YOLOv5s COCO预训练模型  
**输入尺寸**: 640x640  
**类别数**: 80 (COCO标准类别)  

使用标准 COCO 类别映射，详见代码中 `kCocoLabels` 数组。

**配置示例**:
```json
{
  "type": "ai_yolo",
  "model_path": "./models/yolov5s-640-640.rknn",
  "model_version": "v5",
  "num_classes": 80,
  "conf": 0.25,
  "nms": 0.45
}
```

---

### 3. yolov8n-640.rknn

**类型**: YOLOv8n COCO预训练模型  
**输入尺寸**: 640x640  
**类别数**: 80 (COCO标准类别)  

使用标准 COCO 类别映射。

**配置示例**:
```json
{
  "type": "ai_yolo",
  "model_path": "./models/yolov8n-640.rknn",
  "model_version": "v8",
  "num_classes": 80,
  "conf": 0.25,
  "nms": 0.45
}
```

---

### 4. RetinaFace_mobile320.rknn

**类型**: RetinaFace 人脸检测  
**输入尺寸**: 320x320  
**输出**: 人脸框 + 5点关键点  

**配置示例**:
```json
{
  "type": "ai_face_det",
  "model_path": "./models/RetinaFace_mobile320.rknn",
  "conf": 0.7,
  "nms": 0.4,
  "max_faces": 10,
  "output_landmarks": true
}
```

---

### 5. mobilefacenet_arcface.rknn

**类型**: MobileFaceNet + ArcFace 人脸识别  
**输入尺寸**: 112x112  
**输出维度**: 512  

**配置示例**:
```json
{
  "type": "ai_face_recog",
  "model_path": "./models/mobilefacenet_arcface.rknn",
  "align": true,
  "threshold": {
    "accept": 0.45,
    "margin": 0.05
  },
  "gallery": {
    "backend": "sqlite",
    "path": "./models/face_gallery.db",
    "expected_dim": 512
  }
}
```

---

## 模型选择建议

| 场景 | 推荐模型 | 说明 |
|------|----------|------|
| 通用目标检测 | yolov8n-640.rknn | 80类COCO，通用性强 |
| 工地安全检测 (人+靴) | best-768.rknn | 11类PPE，只使用3(boots)+6(Person) |
| 人脸检测+识别 | RetinaFace + MobileFaceNet | 人脸识别链路 |

## 注意事项

1. **模型尺寸匹配**: `preprocess` 节点的 `dst_w/dst_h` 必须与模型输入尺寸一致
2. **num_classes**: 必须与模型实际类别数一致，否则后处理会出错
3. **class_filter**: 用于过滤只关心的类别，减少后续处理负载
4. **best-768.rknn**: 只消费类别 3(boots) 和 6(Person)，其他类别在 class_filter 中已过滤