模型管理界面-需求文档

文档版本：V1.0 创建日期：2026-06-05 负责人：[姓名已隐藏] 关联原型：模型管理界面原型.html

一、项目背景

市"项目甲"体系中的多源视频智能检测工具，需要对各类 AI 识别模型进行统一管理和运维。现有系统缺少模型版本管理、识别目标配置、业务来源绑定等核心能力，无法满足生产环境对模型全生命周期管理的需求。

本需求文档描述模型管理中心的功能需求、界面设计和数据规范，作为前端开发和后端接口设计的依据。

二、设计目标

三、功能需求

3.1 模型列表（主页面）

入口：顶部导航「模型管理」

界面结构：

• 左侧：行业类别导航树（全部 / 行业通用 / 林业监管 / 矿山安全 / 智慧城管 / 公共安全）
• 右侧：工具栏 + 模型卡片网格

工具栏功能：

• 搜索框：按模型名称 / ID 搜索
• 状态筛选：全部状态 / 已启用 / 已停用 / 更新中
• 导出列表按钮
• 「新增模型」按钮（主操作，绿色高亮）

卡片展示字段（每个模型卡片）：

卡片交互：

• 点击卡片任意位置 → 进入模型详情页
• 点击「查看详情」→ 进入模型详情页
• 点击「···」→ 弹出操作菜单（编辑 / 版本管理 / 启用或停用 / 删除）

3.2 新增模型

触发方式：模型列表页点击「新增模型」按钮

弹窗字段：

3.2.1 业务来源绑定（新增/编辑弹窗内）

功能说明：配置该模型在不同业务场景下的识别目标过滤规则。

数据格式（对应 start 接口参数）：

{
  "business_source": "森林日常巡查",
  "targets": ["烟雾检测", "火焰检测"]
}

前端不传 business_source 参数时：后端走原有逻辑，全量识别。

界面交互：

• 点击「+ 添加业务来源」新增一行
• 每行包含：业务名称（文本输入）+ 识别目标（多选下拉）+ 删除按钮
• 识别目标下拉选项来源于「识别目标」字段已选项

3.3 模型详情页

入口：模型列表点击任意卡片

页面结构：

3.3.1 顶部区域（Hero）

操作按钮组：

• 「切换状态」（启用/停用）
• 「编辑配置」（打开编辑弹窗）
• 「上传新版本」（打开版本管理弹窗）
• 「查看识别线索」（跳转预警成果页，带模型过滤）
• 「查看调用日志」（跳转模型日志页，带模型过滤）

3.3.2 调用统计（Tab：调用统计）

3.3.3 识别目标（Tab：识别目标）

• 标签云展示该模型支持的所有识别目标
• 每个标签显示触发次数（可选）

3.3.4 业务绑定（Tab：业务绑定）

3.3.5 基础信息（右侧面板）

3.3.6 版本管理（右侧面板）

• 当前版本高亮显示（版本号 + 更新时间 + 更新说明 + 上传人）
• 历史版本时间轴列表（版本号 / 更新时间 / 说明 / 操作人 / 操作按钮「回滚」）

3.4 版本管理（弹窗）

触发方式：

• 模型详情页点击「上传新版本」
• 模型列表卡片「···」菜单 → 「版本管理」

弹窗内容：

版本更新规则：

• 模型 ID 保持不变
• 新版本上传后，原版本进入历史版本列表
• 支持版本回滚（将历史版本设为当前版本）

3.5 编辑模型

触发方式：模型详情页点击「编辑配置」

弹窗内容：与「新增模型」弹窗基本一致，区别在于：

• 标题为「编辑模型」
• 模型文件为非必填（不重新上传则保留当前版本文件）
• 版本号字段置灰（版本更新需通过「上传新版本」功能）

3.6 启用 / 停用模型

触发方式：

• 模型详情页点击「切换状态」
• 模型列表卡片「···」菜单 → 「启用」/「停用」

规则：

• 已启用模型 → 可停用，停用后不再参与识别任务
• 已停用模型 → 可启用，启用后恢复正常识别
• 更新中模型 → 不可切换状态，需等待版本更新完成

3.7 删除模型

触发方式：模型列表卡片「···」菜单 → 「删除」

规则：

• 弹出确认框，提示「确定删除该模型？删除后无法恢复」
• 有关联识别记录的模型，提示「该模型有关联识别记录，删除后历史数据仍可查看」
• 删除后模型 ID 作废，不可复用

四、数据字段定义

4.1 模型主表（model_info）

4.2 识别目标（model_targets）

4.3 业务来源绑定（model_biz_binding）

4.4 版本记录（model_versions）

五、接口需求（供后端参考）

5.1 模型列表查询

GET /api/v1/models
Query: 
  - keyword (可选): 搜索关键词
  - status (可选): on/off/updating
  - cat (可选): 业务类型过滤
  - page, page_size: 分页

Response:
  {
    "code": 0,
    "data": {
      "total": 6,
      "items": [/* ModelInfo */]
    }
  }

5.2 新增模型

POST /api/v1/models
Body: FormData
  - name, cat, type, version, desc
  - file: 模型文件
  - targets: JSON字符串
  - biz_bindings: JSON字符串

Response: { "code": 0, "data": { "id": "mdl-0007" } }

5.3 模型详情

GET /api/v1/models/{model_id}
Response: { "code": 0, "data": { /* ModelDetail */ } }

5.4 更新模型（编辑配置）

PUT /api/v1/models/{model_id}
Body: FormData (同新增，file可选)

5.5 上传新版本

POST /api/v1/models/{model_id}/versions
Body: FormData
  - version: 新版本号
  - description: 更新说明
  - file: 新版本文件

Response: { "code": 0 }

5.6 版本回滚

POST /api/v1/models/{model_id}/versions/{version}/rollback

5.7 启用/停用模型

PUT /api/v1/models/{model_id}/status
Body: { "status": "on" | "off" }

5.8 start 接口新增参数（识别时）

POST /api/v1/recognize/start
Body: {
  "model_id": "mdl-0001",
  "business_source": "森林日常巡查",  // 新增参数
  "stream_url": "..."
}

// 后端逻辑：
// 1. 如果 business_source 为空 → 走原有逻辑，全量识别
// 2. 如果 business_source 有值 → 查 model_biz_binding 表，
//    按绑定的 targets 过滤识别目标

六、非功能需求

七、界面设计规范引用

• 整体风格：深色科技感（背景 #06161c，主色 #22d3ee）
• 卡片样式：圆角 16px，毛玻璃效果（backdrop-filter: blur）
• 状态颜色：已启用-绿色 / 已停用-灰色 / 更新中-橙色
• 字体：PingFang SC / Microsoft YaHei
• 参考原型文件：模型管理界面原型.html

八、需求跟踪

*本文档关联原型文件：`[本地路径已隐藏]