3588AdminBackend/docs/superpowers/specs/2026-05-05-model-management-design.md

模型管理设计

日期：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. 单模型 / 全模型更新任务

第一阶段不做：

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

与现有系统的关系

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

这样可以保持分层一致：

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

后续扩展

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

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

结论

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

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

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