OrangePi3588Media/docs/models.md

AI 模型说明文档

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

目录结构

models/
├── best-640.rknn                  # YOLO 通用检测模型 (3类)
├── best-768.rknn                  # YOLO PPE检测模型 (11类)
├── 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-640.rknn

类型: YOLOv8 目标检测
输入尺寸: 640x640
类别数: 3

索引	类别名	说明
0	person	人
1	vest	反光背心
2	boots	安全靴

配置示例:

{
  "type": "ai_yolo",
  "model_path": "./models/best-640.rknn",
  "model_version": "v8",
  "num_classes": 3,
  "conf": 0.35,
  "nms": 0.45
}

---

2. best-768.rknn (PPE11)

类型: YOLOv8 PPE检测模型
输入尺寸: 768x768
类别数: 11
模型名: ppe11_person_boots_boost

索引	类别名	业务使用	说明
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)

配置示例:

{
  "type": "ai_yolo",
  "model_path": "./models/best-768.rknn",
  "model_version": "v8",
  "model_w": 768,
  "model_h": 768,
  "num_classes": 11,
  "conf": 0.35,
  "nms": 0.45,
  "class_filter": [3, 6]
}

OSD标签配置:

{
  "type": "osd",
  "labels": ["helmet", "gloves", "vest", "boots", "goggles", "none", "Person", "no_helmet", "no_goggle", "no_gloves", "no_boots"]
}

---

3. yolov5s-640-640.rknn

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

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

配置示例:

{
  "type": "ai_yolo",
  "model_path": "./models/yolov5s-640-640.rknn",
  "model_version": "v5",
  "num_classes": 80,
  "conf": 0.25,
  "nms": 0.45
}

---

4. yolov8n-640.rknn

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

使用标准 COCO 类别映射。

配置示例:

{
  "type": "ai_yolo",
  "model_path": "./models/yolov8n-640.rknn",
  "model_version": "v8",
  "num_classes": 80,
  "conf": 0.25,
  "nms": 0.45
}

---

5. RetinaFace_mobile320.rknn

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

配置示例:

{
  "type": "ai_face_det",
  "model_path": "./models/RetinaFace_mobile320.rknn",
  "conf": 0.7,
  "nms": 0.4,
  "max_faces": 10,
  "output_landmarks": true
}

---

6. mobilefacenet_arcface.rknn

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

配置示例:

{
  "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-640.rknn	人/背心/安全靴
PPE完整检测	best-768.rknn	11类PPE，含正反例
人脸检测+识别	RetinaFace + MobileFaceNet	人脸识别链路

注意事项

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