Add model management design spec
This commit is contained in:
parent
6eb712fcfe
commit
4c9119b2bf
283
docs/superpowers/specs/2026-05-05-model-management-design.md
Normal file
283
docs/superpowers/specs/2026-05-05-model-management-design.md
Normal file
@ -0,0 +1,283 @@
|
||||
# 模型管理设计
|
||||
|
||||
日期：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. 单模型 / 全模型更新任务
|
||||
|
||||
第一阶段不做：
|
||||
|
||||
- 模型版本回滚
|
||||
- 旧版本归档管理
|
||||
- 复杂依赖分析
|
||||
- 场景模板到模型的反向引用图
|
||||
|
||||
## 与现有系统的关系
|
||||
|
||||
- 场景模板仍然引用模型路径
|
||||
- 模型管理负责维护这些路径对应的标准模型文件
|
||||
- 设备页只查看设备当前模型状态，不承担模型维护职责
|
||||
|
||||
这样可以保持分层一致：
|
||||
|
||||
- 场景模板：描述识别策略
|
||||
- 模型管理：维护标准模型
|
||||
- 设备：只消费模型结果
|
||||
|
||||
## 后续扩展
|
||||
|
||||
后续如果第一阶段稳定，可以再扩：
|
||||
|
||||
- 模型版本回滚
|
||||
- 模型使用范围统计
|
||||
- 模型差异详情页
|
||||
- 按模型类型筛选设备问题
|
||||
- 模型与识别模板的引用关系展示
|
||||
|
||||
## 结论
|
||||
|
||||
模型管理的核心不是上传按钮，而是：
|
||||
|
||||
- 标准模型目录
|
||||
- 设备完整性检查
|
||||
- 基于任务的统一模型更新
|
||||
|
||||
页面应突出“是否完整、是否一致、怎么更新”，而不是堆太多辅助说明。
|
||||
Loading…
Reference in New Issue
Block a user