OrangePi3588Media/docs/models.md

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)

配置示例:

{
  "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标签配置:

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

Tracker配置:

{
  "type": "tracker",
  "track_classes": [3, 6],
  "per_class": true
}

---

2. 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
}

---

3. 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
}

---

4. 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
}

---

5. 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-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 中已过滤