# AI 模型命名与资产说明

本文档说明 `models/` 目录中的模型命名规范和当前模型用途。运维侧应优先以本文件和当前配置文件中的路径为准。

## 命名规范

模型文件名采用业务语义优先：

```text
<业务域>_<任务>_<模型或数据集>_<输入尺寸>_<平台>[可选版本].<扩展名>
```

常用字段：

| 字段 | 示例 | 含义 |
|------|------|------|
| 业务域 | `face` / `object` / `shoe` / `ppe` | 模型主要服务的业务方向 |
| 任务 | `det` / `recog` | 检测或识别 |
| 模型或数据集 | `scrfd_500m` / `yolov8n_coco` / `mobilefacenet_arcface` | 模型架构、训练集或业务版本 |
| 输入尺寸 | `640` / `768` / `112` | 模型输入尺寸 |
| 平台 | `rk3588` | RKNN 编译目标平台 |

示例：

```text
face_det_scrfd_500m_640_rk3588.rknn
face_recog_mobilefacenet_arcface_112_rk3588.rknn
object_det_yolov8n_coco_640_rk3588.rknn
shoe_det_yolov8s_workshoe_640_rk3588.rknn
```

## 当前模型清单

| 文件 | 用途 | 主要配置 |
|------|------|----------|
| `face_det_scrfd_500m_640_rk3588.rknn` | SCRFD 人脸检测，输出人脸框和关键点 | `ai_scrfd` / `ai_scrfd_sliding` |
| `face_recog_mobilefacenet_arcface_112_rk3588.rknn` | MobileFaceNet + ArcFace 人脸 embedding | `ai_face_recog` |
| `object_det_yolov8n_coco_640_rk3588.rknn` | YOLOv8n COCO 通用目标检测，当前主要用于人体检测 | `ai_yolo`, `model_version=v8`, `num_classes=80` |
| `shoe_det_yolov8s_workshoe_640_rk3588.rknn` | 当前白鞋/工鞋检测主模型 | 鞋子检测链路 |
| `ppe_det_yolov8_ppe11_768_rk3588.rknn` | 历史 PPE11 检测模型，部分老配置仍引用 | PPE/压力测试配置 |
| `object_det_yolov5s_coco_640_rk3588.rknn` | YOLOv5s COCO 通用目标检测 | 老示例配置 |
| `shoe_det_openimages_ppe_v1_rk3588.rknn` | OpenImages/PPE 鞋检测历史模型 | `ai_shoe_det` 文档示例 |

## 运行数据

| 文件 | 用途 | 说明 |
|------|------|------|
| `face_gallery.db` | 人脸库 SQLite 数据库 | 运行期数据，不按 `.rknn` 模型命名规则改名；agent/API 和 AddFaceTo3588 仍以该默认名称协作 |

## 待确认删除候选

当前无待确认删除候选。历史人脸库备份、未引用 PPE 测试模型和 960 输入鞋检测实验模型已清理。

## 配置注意事项

1. `model_path` 必须使用当前规范名称，避免新旧名称混用。
2. `model_w` / `model_h` 必须与文件名中的输入尺寸一致。
3. `model_version`、`num_classes`、`class_filter` 必须与模型实际输出一致。
4. `face_gallery.db` 是人脸库数据文件，不是 RKNN 模型；不要用 `face_recog_*` 规则重命名它，除非同步修改 AddFaceTo3588、agent 默认路径和所有配置。
5. 删除任何待确认候选前，必须先确认 RK3588 设备侧配置、测试脚本和运维流程不再依赖该文件。