Tiger AI Plateform项目中图像分割功能的技术实现、依赖环境、模型权重、API 接口与使用流程

本文档说明 CV Python Tigerpro 项目中图像分割功能的技术实现、依赖环境、模型权重、API 接口与使用流程。

1. 模块概述

图像分割模块位于前端菜单视觉识别 → 图像分割（路由/ai/segment），提供双引擎分割能力：

说明：当前模块未集成Ultralytics YOLO-Seg、Meta 原版 SAM 等其他分割后端；所有推理统一走backend/inference.py，路由挂载于backend/routes/ai_model.py。

2. 技术栈

2.1 前端

主要源文件：

• frontend/src/views/ai/segment/index.vue— 分割页面
• frontend/src/api/ai.js—modelApi.segment/segmentVideo/videoProgress
• frontend/src/composables/useInferProgress.js— MobileSAM 推理进度估算

2.2 后端

主要源文件：

• backend/inference.py—segment_image_rfdetr/segment_video_rfdetr/segment_image_mobilesam
• backend/routes/ai_model.py— 分割路由、权重拉取、视频任务
• backend/seed.py— 预置分割模型与菜单权限

2.3 架构示意

┌─────────────────┐ multipart/form-data ┌──────────────────────┐ │ segment/index │ ───────────────────────────► │ ai_model.py │ │ (Vue 前端) │ ◄── JSON {detections, image} │ segment_route │ └─────────────────┘ └──────────┬───────────┘ │ ┌───────────────────────────────┴───────────────────────────────┐ │ inference.py │ │ rfdetr → segment_image_rfdetr / segment_video_rfdetr │ │ mobilesam → segment_image_mobilesam (prompt / auto) │ └───────────────────────────────────────────────────────────────┘

3. 功能模式

3.1 RF-DETR 实例分割

• 输出 COCO 80 类实例，每实例含：类别名、置信度、边界框、PNG mask（Base64）
• 可视化：半透明 mask + 检测框 + 类别标签（supervision标注器）

3.2 MobileSAM 交互分割

• 点击模式在 Canvas 上标注，绿色 = 前景，红色 = 背景
• 后端另支持box框选参数，前端 UI 暂未暴露
• 推理进度为时间估算进度条（首次加载模型较慢）
  
  
  
  

4. 依赖与环境

4.1 Python 依赖（分割相关）

在backend/requirements.txt中，与图像分割直接相关的包：

rfdetr>=1.8.0 mobile-sam @ git+https://github.com/ChaoningZhang/MobileSAM.git torch==2.11.0 torchvision==0.26.0 transformers>=5.1.0,<6.0.0 # RF-DETR 内部依赖 BackboneConfigMixin imageio==2.37.3 imageio-ffmpeg==0.6.0 requests==2.32.3 # MobileSAM 权重下载

间接依赖（由 rfdetr / 推理链路使用）：

4.2 安装与启动

conda activate cv_python_tigerprocdbackend pipinstall-rrequirements.txt python app.py# 默认 http://127.0.0.1:5001

cdfrontendnpminstallnpmrun dev# 默认 http://127.0.0.1:5173

4.3 硬件建议

4.4 存储与上传限制

来自backend/config.py：

5. 模型与权重

5.1 系统预置模型

种子数据（backend/seed.py）预置2 个分割模型，启用状态status=0：

5.2 权重拉取方式

在模型管理中对对应模型点击拉取权重（POST /api/ai/model/<id>/fetch，需ai:model:add权限）：

本地存储路径示例：

backend/uploads/models/rf-detr-seg-medium/rf-detr-seg-medium.pt backend/uploads/models/mobile-sam/mobile_sam.pt

5.3 RF-DETR-Seg 可选规格（代码支持，未全部预置）

inference.py中_RFDETR_SEG_CLASS映射支持以下model_key，可在模型管理中手动新增同 library/task 的模型条目后拉取对应权重：

类别名解析使用 COCO 80 类（rfdetr.assets.coco_classes）。

5.4 MobileSAM 模型结构

• 架构：sam_model_registry["vit_t"]（ViT-Tiny，约 40MB）
• 设备：有 CUDA 时用 GPU，否则 CPU
• 模型缓存：按权重路径 + 文件修改时间缓存SamPredictor，避免重复加载

6. 使用流程

6.1 首次准备

1. 启动后端与前端（见 §4.2）
2. 使用管理员账号登录（默认admin / admin123）
3. 进入模型管理，对RF-DETR Seg Medium与MobileSAM分别拉取权重
4. 侧栏进入视觉识别 → 图像分割

6.2 RF-DETR 图片分割

1. Tab 选择RF-DETR 实例分割
2. 模式选图片
3. 选择已拉取权重的 RF-DETR-Seg 模型，调整置信度（默认 0.25）
4. 上传图片 → 点击开始分割
5. 查看原图/结果并排、下方检测表格；可下载结果 JPG

6.3 RF-DETR 视频分割

1. 模式选视频
2. 上传视频 →开始分割
3. 等待进度条（processed / total帧）
4. 完成后播放/下载结果 MP4

6.4 MobileSAM 点击分割

1. Tab 选择MobileSAM 交互分割
2. SAM 模式选点击分割
3. 上传图片，在原图上：
   • 左键— 前景点（保留区域）
   • Shift + 左键— 背景点（排除区域）
4. 点击开始分割；可用「清除标点」重新标注

6.5 MobileSAM 全自动分割

1. SAM 模式选全自动
2. 上传图片 →开始分割
3. 返回最多 40 个区域（region_1…region_N），按面积降序

7. API 接口

基础路径：/api/ai/model（需 JWT，Authorization: Bearer <token>）

7.1 图片分割

POST /api/ai/model/{modelId}/segment Content-Type: multipart/form-data 权限: ai:model:query

通用字段：

MobileSAM 额外字段：

响应示例：

{"code":0,"message":"分割完成","data":{"detections":[{"className":"person","classId":0,"confidence":0.9234,"bbox":[120.5,80.2,340.1,520.8],"maskBase64":"<PNG Base64>"}],"count":1,"imageBase64":"<JPEG Base64 标注图>","width":640,"height":480}}

7.2 视频分割（仅 RF-DETR-Seg）

POST /api/ai/model/{modelId}/segment-video Content-Type: multipart/form-data 权限: ai:model:query

响应：

{"code":0,"message":"任务已启动","data":{"jobId":"a1b2c3..."}}

7.3 视频任务进度

GET /api/ai/model/{modelId}/video-progress/{jobId}

进行中：

{"code":0,"data":{"status":"running","processed":120,"total":500,"stats":null,"error":null}}

完成：

{"code":0,"data":{"status":"done","processed":500,"total":500,"stats":{"frames":500,"totalFrames":500,"totalDetections":1234,"classCounts":{"person":400,"chair":120},"fps":25.0,"width":1920,"height":1080,"output":"match_1710000000_seg.mp4"}}}

7.4 下载结果视频

GET /api/ai/model/output/{outputFileName}

返回video/mp4二进制流（路径穿越已防护）。

7.5 拉取模型权重

POST /api/ai/model/{modelId}/fetch 权限: ai:model:add

按模型library自动分流至 RF-DETR 或 MobileSAM 下载逻辑。

8. 权限说明

9. 关键代码索引

10. 常见问题

Q1：页面提示「暂无 RF-DETR-Seg / MobileSAM 模型」

• 确认模型管理中已存在task与library匹配的记录
• 确认已拉取权重（filePath非空）
• 确认模型状态为启用（status=0）

Q2：MobileSAM 点击分割按钮灰色

• 「点击分割」模式需至少1 个前景点且已上传图片
• 「全自动」模式仅需上传图片

Q3：视频分割很慢

• RF-DETR 逐帧推理，时长与分辨率、帧数、硬件正相关
• 建议使用 GPU；降低输入视频分辨率可显著提速

Q4：能否用 YOLO-Seg？

• 当前不支持。实例分割仅实现 RF-DETR-Seg；交互分割仅实现 MobileSAM。

Q5：mask 数据如何使用？

• 图片接口每个 detection 含maskBase64（PNG 二值图）
• 视频逐帧统计中省略 mask（include_mask=False）以提升速度，但输出视频仍带 mask 可视化

11. 实测截图清单（待补充）

以下截图建议在本地跑通流程后补充到docs/images/segment/目录，并在上文对应占位处替换为 Markdown 图片链接：

替换示例：

![RF-DETR 图片分割结果](images/segment/02-rfdetr-image-result.png)

12. 版本与参考

• RF-DETR：Roboflow RF-DETR
• MobileSAM：ChaoningZhang/MobileSAM
• Supervision 可视化：supervision

文档随项目代码维护；若接口或预置模型有变更，以backend/seed.py与backend/routes/ai_model.py为准。