# 模型管理设计

日期：2026-05-05  
仓库：`C:\Users\Tellme\apps\3588AdminBackend`

## 目标

模型管理页用于统一管理平台标准模型，并检查各设备上的模型完整性与版本一致性。

这一页回答四个问题：

1. 平台当前有哪些标准模型
2. 每个标准模型的版本、哈希、文件信息是什么
3. 每台设备上这些标准模型是否完整、是否一致
4. 如何对单台或多台设备发起模型更新任务

## 边界

### 属于模型管理

- 标准模型目录
- 模型元数据
- 模型版本管理
- 设备模型完整性检查
- 单模型或全模型更新任务

### 不属于模型管理

- 人脸库
- 其他资源文件
- 场景模板或识别单元配置本身

人脸库归到“资源管理”，并与模型目录分开。

## 现有现实基础

视觉服务项目中，当前标准模型主要位于：

`C:\Users\Tellme\apps\OrangePi3588Media\models`

现阶段可以识别出的标准模型包括：

- `face_det_scrfd_500m_640_rk3588.rknn`
- `face_recog_mobilefacenet_arcface_112_rk3588.rknn`
- `object_det_yolov8n_coco_640_rk3588.rknn`
- `ppe_det_yolov8_ppe11_768_rk3588.rknn`
- `shoe_det_yolov8s_workshoe_640_rk3588.rknn`

模板中引用的主模型路径也基本都是 `./models/*.rknn`。

## 后台目录设计

后台项目中新增标准模型目录，作为平台统一模型源：

- `C:\Users\Tellme\apps\3588AdminBackend\models\standard_models`

资源管理中的人脸库目录单独维护，例如：

- `C:\Users\Tellme\apps\3588AdminBackend\resources\face_galleries`

两类目录不混用。

## 数据模型

后台数据库新增标准模型记录表，建议字段如下：

- `name`
  - 模型标识，例如 `face_det_scrfd_500m_640`
- `file_name`
  - 实际文件名，例如 `face_det_scrfd_500m_640_rk3588.rknn`
- `version`
  - 用户可读版本号，例如 `v1.2.0`
- `sha256`
  - 文件哈希，作为一致性判断依据
- `size_bytes`
  - 文件大小
- `model_type`
  - 模型类型，例如 `face_det`、`face_recog`、`object_det`、`ppe_det`、`shoe_det`
- `description`
  - 中文说明
- `created_at`
- `updated_at`

### 版本判断原则

- 页面显示版本号
- 实际一致性校验以 `sha256` 为准

也就是：

- 人看版本号
- 系统比哈希

## 设备侧状态模型

每台设备需要提供当前模型清单，用于后台比对。

每个设备模型状态项至少包括：

- `name`
- `file_name`
- `sha256`
- `size_bytes`
- `updated_at`

后台将设备上报结果与标准模型目录进行比对，产出三类状态：

- 完整且一致
- 缺失
- 已安装但版本不一致

## 页面结构

模型管理页保持简洁，不做过多说明文字。

### 1. 顶部概览

显示以下核心统计：

- 标准模型总数
- 在线设备数
- 完整设备数
- 缺失设备数
- 版本不一致设备数

重点是让用户一眼知道整体是否健康。

### 2. 标准模型列表

每行一个标准模型，字段建议为：

- 模型名
- 类型
- 版本
- 文件名
- 哈希摘要
- 文件大小
- 更新时间

主操作：

- 上传新模型
- 更新模型版本
- 查看使用范围

第一阶段不做复杂版本树，也不在主界面塞过多附加说明。

### 3. 设备模型状态表

每台设备一行，按标准模型展开状态列。

推荐表现方式：

- 单元格状态标签或轻量色块
- 清楚标识“一致 / 缺失 / 不一致”

目标是让用户快速看出：

- 哪台设备缺模型
- 哪台设备版本旧
- 哪些设备整体完整

## 操作方式

更新动作全部走任务系统，不在页面直接做同步上传。

支持两类动作：

### 单模型更新

对一个标准模型，选择：

- 单台设备
- 多台设备
- 全部在线设备

创建任务后进入任务页查看进度。

### 全模型更新

对设备执行：

- 全部标准模型同步

这个动作适合新设备初始化，或者设备模型目录整体修复。

## 任务语义

模型更新任务由现有任务系统统一管理和监控。

建议新增任务类型：

- `model_sync_one`
- `model_sync_all`

每台设备单独显示：

- 待执行
- 执行中
- 成功
- 失败

失败时保留错误信息，例如：

- 设备离线
- 上传失败
- 哈希校验失败
- 替换失败

## Agent / 设备侧契约

为了支撑模型管理，设备侧需要提供：

### 模型清单查询

后台可获取设备当前模型清单与哈希信息。

### 模型上传 / 替换

支持上传单个模型并替换设备侧现有模型文件。

### 全量同步

后台可按标准模型目录，对设备执行整包模型同步。

### 可选的校验结果返回

上传完成后返回：

- 文件名
- sha256
- 落盘路径

用于后台任务结果核对。

## 第一阶段范围

第一阶段只做这些：

1. 后台本地标准模型目录
2. 数据库存标准模型元数据
3. 模型管理页的标准模型列表
4. 设备模型清单比对与状态显示
5. 单模型 / 全模型更新任务

第一阶段不做：

- 模型版本回滚
- 旧版本归档管理
- 复杂依赖分析
- 场景模板到模型的反向引用图

## 与现有系统的关系

- 场景模板仍然引用模型路径
- 模型管理负责维护这些路径对应的标准模型文件
- 设备页只查看设备当前模型状态，不承担模型维护职责

这样可以保持分层一致：

- 场景模板：描述识别策略
- 模型管理：维护标准模型
- 设备：只消费模型结果

## 后续扩展

后续如果第一阶段稳定，可以再扩：

- 模型版本回滚
- 模型使用范围统计
- 模型差异详情页
- 按模型类型筛选设备问题
- 模型与识别模板的引用关系展示

## 结论

模型管理的核心不是上传按钮，而是：

- 标准模型目录
- 设备完整性检查
- 基于任务的统一模型更新

页面应突出“是否完整、是否一致、怎么更新”，而不是堆太多辅助说明。