admin/Pre_Seg_Server
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

feat: 完善 SAM2.1 模型选择与标注工作流

Browse Source 
- 后端 SAM2 引擎新增 sam2.1_hiera_tiny、sam2.1_hiera_small、sam2.1_hiera_base_plus、sam2.1_hiera_large 四个变体定义，并按变体维护 checkpoint/config、image predictor、video predictor、加载状态、错误信息和真实状态回报。

- 后端 SAM registry 仅暴露当前产品启用的 SAM2.1 变体，保留 sam2 作为 tiny 兼容别名，拒绝 sam3 产品入口，并把 point、box、interactive、auto、propagate 都分发到所选 SAM2.1 变体。

- 后端默认配置和下载脚本切换到 SAM2.1 checkpoint 命名，支持 legacy SAM2 checkpoint fallback，并在状态消息中标出 fallback 使用情况。

- 前端全局 AI 模型状态新增 SAM2.1 tiny/small/base+/large 类型和默认 tiny，API 请求默认携带 sam2.1_hiera_tiny，AI 页面提供模型变体选择和所选模型状态展示。

- AI 智能分割页移除当前产品不使用的 SAM3/文本提示入口，保留正向点、反向点、框选和参数开关；AI 页只展示本页生成的候选 mask，并支持遮罩清晰度调节、候选 mask 上继续加正/反点、清空本页候选、推送到工作区编辑。

- 工作区和 Canvas 补强 SAM2 交互式细化链路：框选后正/反点继续细化同一个候选 mask，反向点请求启用背景过滤，空结果会移除被否定候选；AI 推送到工作区后保留选中态和未保存 draft mask。

- 工作区标注保存闭环补强：未保存 mask 可归档保存，dirty saved mask 可更新，保存后用后端 saved annotation 替换已提交 draft，清空/删除已保存 mask 时同步后端删除。

- Dashboard 任务进度区改为展示 queued、running、success、failed、cancelled 最近任务，处理中统计只计算 queued/running，并保留近期完成记录。

- 时间轴在顶部时间进度条和底部缩略图导航轴之间新增已编辑帧标记带，基于当前项目帧内 masks 标出已有编辑/标注的帧，并支持点击标记跳转。

- 前端测试覆盖 SAM2.1 变体选择、模型状态徽标、AI 页候选隔离、遮罩透明度、候选上追加正/反点、推送工作区保留选择、Canvas 交互式细化、VideoWorkspace 传播/保存、Dashboard 进度和时间轴已编辑帧标记。

- 后端测试覆盖 SAM2.1 变体状态、sam2 alias 兼容、sam3 禁用、semantic 禁用、传播标注保存、Dashboard 最近任务状态和 SAM3 历史测试跳过说明。

- README、AGENTS 和 doc 文档同步当前真实进度，更新 SAM2.1 变体、SAM3 禁用、接口契约、设计冻结、需求冻结、前端元素审计、实施计划、FastAPI docs 说明和测试矩阵。
This commit is contained in:
admin
2026-05-01 23:39:53 +08:00
parent 8a9247075e
commit 29a1a87e52
38 changed files with 1087 additions and 631 deletions
Download Patch File Download Diff File Expand all files Collapse all files

86
README.md
View File

@@ -4,20 +4,20 @@
# 语义分割系统（SegServer）
> 基于 React + FastAPI + 可选 SAM 2 / SAM 3 的全栈交互式图像/视频语义分割与标注平台。
> 基于 React + FastAPI + SAM 2 的全栈交互式图像/视频语义分割与标注平台。
>
> 支持本地多媒体资产上传、服务器端按帧解析、交互式 Canvas 标注、视频片段传播、GT mask 导入、模板分类管理和标注数据结构化导出；工作区点/框 AI 推理默认走 SAM 2，SAM 3 支持语义文本、框选提示和 video tracker，前端会显示真实 GPU/模型状态。
> 支持本地多媒体资产上传、服务器端按帧解析、交互式 Canvas 标注、视频片段传播、GT mask 导入、模板分类管理和标注数据结构化导出；工作区点/框 AI 推理走可选 SAM 2.1 tiny/small/base+/large，前端会显示真实 GPU/模型状态。SAM 3 源码和脚本在仓库中保留，但由于当前系统不提供文本提示，产品入口已隐藏，后端也不暴露 `sam3` 模型。
---
## 核心功能
- **多媒体资产管理** — 支持视频（MP4/AVI/MOV）和 DICOM 医学影像上传；视频导入与生成帧分离，生成帧时选择目标 FPS
- **AI 智能分割引擎** — 后端提供 SAM 2 / SAM 3 模型选择；SAM 2 支持点分割（point）、框分割（box）、自动分割（auto）和 video predictor 传播，前端默认只采用最高分候选避免重叠备选同时显示；SAM 3 入口支持文本语义提示、框选提示和 external video tracker，并按真实运行环境显示可用性
- **AI 智能分割引擎** — 当前产品入口启用 SAM 2.1 四个变体（tiny/small/base+/large）选择；支持点分割（point）、框分割（box）、交互式正/反点细化、自动分割（auto）和 video predictor 传播，前端默认只采用最高分候选避免重叠备选同时显示
- **交互式画布标注** — 基于 Konva 的高性能 Canvas，支持缩放/平移/手工多边形/矩形/圆/点/线、polygon 顶点拖动/删除、边中点插点、双击边界插点、区域合并/去除、选点/框选、撤销/重做，实时渲染 Mask 遮罩
- **GT Mask 导入** — 工作区可导入 GT mask 图片，后端按非零像素值和连通域生成 polygon 标注并用 distance transform 写入 seed point；前端可回显和拖动 seed point
- **本体字典管理** — 可配置的分类体系、颜色映射、图层优先级（z-index）
- **项目工作区** — 项目创建、帧浏览、多图层标注、进度追踪
- **项目工作区** — 项目创建、帧浏览、多图层标注、已编辑帧提示、进度追踪
- **数据导出** — 支持 COCO JSON 格式和 PNG Mask 批量导出；PNG ZIP 包含单标注 mask、按 z-index 融合的语义 mask 和类别映射
---
@@ -40,7 +40,7 @@
│ ├── /api/templates 本体字典（分类/颜色/z-index） │
│ ├── /api/media 文件上传 & 异步拆帧任务创建 │
│ ├── /api/tasks Celery 后台任务状态/取消/重试/详情 │
│ ├── /api/ai SAM 2 / SAM 3 推理与模型状态 │
│ ├── /api/ai SAM 2 推理与模型状态 │
│ └── /api/export COCO JSON / PNG Masks 导出 │
└──────────────────────────┬──────────────────────────────────┘
│ SQLAlchemy 2.0
@@ -71,7 +71,7 @@
| 队列 Broker | Redis | 6 |
| 后台任务 | Celery worker | 5.6+ |
| 对象存储 | MinIO | 2025+ |
| AI 推理 | SAM 2 / SAM 3 (Meta) + PyTorch | - |
| AI 推理 | SAM 2.1 (Meta) + PyTorch，可选 tiny/small/base+/large | - |
| 视频处理 | FFmpeg + OpenCV | 4.4+ |
| DICOM 处理 | pydicom | 3.0+ |
@@ -94,7 +94,7 @@ Seg_Server/
│ ├── celery_app.py # Celery app 配置
│ ├── worker_tasks.py # Celery 任务入口
│ ├── download_sam2.py # SAM 2 模型权重自动下载脚本
│ ├── setup_sam3_env.sh # SAM 3 独立 Python 3.12 环境安装脚本
│ ├── setup_sam3_env.sh # 历史保留的 SAM 3 独立 Python 3.12 环境安装脚本；当前产品入口禁用
│ ├── requirements.txt # Python 依赖
│ ├── routers/ # API 路由
│ │ ├── auth.py # 登录认证
@@ -104,10 +104,10 @@ Seg_Server/
│ │ ├── ai.py # SAM 推理与模型状态接口
│ │ └── export.py # 数据导出
│ └── services/ # 业务服务
│ ├── sam2_engine.py # SAM 2 推理引擎（单帧推理 + video predictor 传播）
│ ├── sam3_engine.py # SAM 3 状态检测、外部环境桥接、文本语义推理、框选与 video tracker 适配器
│ ├── sam3_external_worker.py # 独立 sam3 conda 环境中执行的状态/推理 helper
│ ├── sam_registry.py # SAM 模型选择、GPU 状态与推理分发
│ ├── sam2_engine.py # SAM 2.1 变体选择、单帧推理 + video predictor 传播
│ ├── sam3_engine.py # 历史保留的 SAM 3 桥接实现；当前未接入 registry
│ ├── sam3_external_worker.py # 历史保留的独立 sam3 helper；当前未被产品入口调用
│ ├── sam_registry.py # 当前暴露 SAM 2.1 变体、GPU 状态与推理分发
│ └── frame_parser.py # FFmpeg 拆帧 / pydicom 读片
├── src/ # React 前端
│ ├── main.tsx # 应用挂载点
@@ -121,7 +121,7 @@ Seg_Server/
│ └── components/ # 组件（扁平化目录）
│ ├── Login.tsx # 登录页
│ ├── Sidebar.tsx # 左侧导航栏
│ ├── Dashboard.tsx # 总体概况仪表盘（解析队列/任务控制）
│ ├── Dashboard.tsx # 总体概况仪表盘（任务进度/任务控制）
│ ├── ProjectLibrary.tsx # 项目库列表
│ ├── VideoWorkspace.tsx # 核心分割工作区布局
│ ├── CanvasArea.tsx # Konva 画布（缩放/平移/手工绘制/选点/Mask渲染）
@@ -162,10 +162,10 @@ Seg_Server/
### 系统要求
- **OS**: Ubuntu 22.04 LTS
- **GPU**: NVIDIA GPU（推荐 RTX 4090 或同等算力），用于 SAM 推理；SAM 3 官方要求 Python 3.12+、PyTorch 2.7+ 和 CUDA 12.6+ 环境
- **GPU**: NVIDIA GPU（推荐 RTX 4090 或同等算力），用于 SAM 2 推理
- **CUDA**: 12.x / 13.x
- **Node.js**: 22.x+
- **Python**: 主后端使用 3.11（通过 Miniconda/Anaconda 管理）；SAM 3 使用独立 `sam3` Python 3.12 conda 环境
- **Python**: 主后端使用 3.11（通过 Miniconda/Anaconda 管理）；历史保留的 SAM 3 环境不是当前必需运行条件
### 安装系统级依赖
@@ -239,27 +239,30 @@ cd ~/Desktop/Seg_Server/backend
python download_sam2.py
# 模型将下载到 ~/Desktop/Seg_Server/models/
# sam2_hiera_tiny.pt (149 MB)
# sam2_hiera_small.pt (176 MB)
# sam2_hiera_base_plus.pt (309 MB)
# sam2_hiera_large.pt (856 MB)
# 推荐放置 SAM 2.1 文件名：
# sam2.1_hiera_tiny.pt
# sam2.1_hiera_small.pt
# sam2.1_hiera_base_plus.pt
# sam2.1_hiera_large.pt
#
# 兼容旧版 SAM 2 文件名：
# sam2_hiera_tiny.pt / sam2_hiera_small.pt / sam2_hiera_base_plus.pt / sam2_hiera_large.pt
```
> **注意**：当前系统磁盘紧张时，建议仅保留 `sam2_hiera_tiny.pt`，删除其他模型以释放空间。
> **注意**：当前系统磁盘紧张时，建议仅保留 `sam2.1_hiera_tiny.pt` 或兼容旧名 `sam2_hiera_tiny.pt`，删除其他模型以释放空间。前端可以选择四个变体，但只有本地存在对应 checkpoint 的变体会显示可用。
### 步骤 5: 可选安装 SAM 3 环境
### 步骤 5: 历史保留的 SAM 3 环境
当前后端不会把 SAM 3 直接装进 `seg_server`，而是通过独立 `sam3` conda 环境执行 `backend/services/sam3_external_worker.py`。这样可以保留现有 Python 3.11 / SAM 2 环境。
当前产品入口不再启用 SAM 3：前端隐藏 SAM 3 相关入口，后端 registry 只暴露 SAM 2.1 变体，`model=sam3` 会返回不支持。以下脚本和 helper 仅作为以后恢复 SAM 3 研究路径的保留文件，正常部署不需要执行。
```bash
cd ~/Desktop/Seg_Server
./backend/setup_sam3_env.sh
# 如果已把权重放在 sam3权重/sam3.pt，可直接走本地 checkpoint；
# 未配置本地 checkpoint 时，才需要 Hugging Face gated repo 授权和登录。
# 仅在后续恢复 SAM 3 实验路径时使用。
```
官方 `facebook/sam3` 权重约 3.45 GB，当前没有类似 SAM 2 `tiny/small/base/large` 的官方小权重梯度。当前仓库默认使用本机 `sam3权重/sam3.pt`，不会提交权重文件；未配置本地 checkpoint 且未获得 gated model 授权时，`GET /api/ai/models/status` 会把 SAM 3 标为不可用并说明 checkpoint access 不满足。
官方 `facebook/sam3` 权重约 3.45 GB，当前没有类似 SAM 2 `tiny/small/base/large` 的官方小权重梯度。本项目不会提交权重文件；由于当前系统不提供文本提示，SAM 3 不在模型状态接口和前端 UI 中展示。
### 步骤 6: 配置环境变量
@@ -273,14 +276,15 @@ minio_endpoint=192.168.3.11:9000
minio_access_key=minioadmin
minio_secret_key=minioadmin
minio_secure=false
sam_model_path=/home/wkmgc/Desktop/Seg_Server/models/sam2_hiera_tiny.pt
sam_model_config=configs/sam2/sam2_hiera_t.yaml
sam_default_model=sam2
sam3_model_version=sam3
sam3_checkpoint_path=/home/wkmgc/Desktop/Seg_Server/sam3权重/sam3.pt
sam3_external_enabled=true
sam3_external_python=/home/wkmgc/miniconda3/envs/sam3/bin/python
sam3_timeout_seconds=300
sam_model_path=/home/wkmgc/Desktop/Seg_Server/models/sam2.1_hiera_tiny.pt
sam_model_config=configs/sam2.1/sam2.1_hiera_t.yaml
sam_default_model=sam2.1_hiera_tiny
# 以下 sam3_* 配置为历史保留项；当前产品入口不读取它们来暴露 SAM 3。
# sam3_model_version=sam3
# sam3_checkpoint_path=/home/wkmgc/Desktop/Seg_Server/sam3权重/sam3.pt
# sam3_external_enabled=true
# sam3_external_python=/home/wkmgc/miniconda3/envs/sam3/bin/python
# sam3_timeout_seconds=300
cors_origins=["http://localhost:3000","http://192.168.3.11:3000"]
```
@@ -309,9 +313,9 @@ nohup uvicorn main:app --host 0.0.0.0 --port 8000 > /tmp/fastapi.log 2>&1 &
- 创建数据库表（如果不存在）
- 检查 MinIO bucket 是否存在
- 测试 Redis 连接
- 懒加载 SAM 模型；`GET /api/ai/models/status` 会返回 SAM 2、SAM 3、GPU 和 SAM 3 checkpoint access 的真实可用状态
- 懒加载所选 SAM 2.1 模型；`GET /api/ai/models/status` 会返回 tiny/small/base+/large 和 GPU 的真实可用状态，`selected_model=sam3` 会返回不支持
- `/api/ai/predict` 支持 AI 参数 `crop_to_prompt`、`auto_filter_background` 和 `min_score`，用于点/框 prompt 的局部裁剪推理、回映射和背景过滤
- `/api/ai/propagate` 支持从当前帧 seed 区域向视频片段传播：SAM 2 使用 `SAM2VideoPredictor.add_new_mask()` + `propagate_in_video()`，SAM 3 通过独立 Python 3.12 helper 调用官方 `build_sam3_video_predictor()` video tracker
- `/api/ai/propagate` 支持从当前帧 seed 区域向视频片段传播：当前使用所选 SAM 2.1 变体的 `SAM2VideoPredictor.add_new_mask()` + `propagate_in_video()`
### 步骤 6.1: 启动 Celery Worker
@@ -325,7 +329,7 @@ celery -A celery_app:celery_app worker --loglevel=info --concurrency=1
nohup celery -A celery_app:celery_app worker --loglevel=info --concurrency=1 > /tmp/celery.log 2>&1 &
```
视频导入只创建项目并把源视频保存到 MinIO，不会自动拆帧；用户在项目库点击“生成帧”后，再选择目标 FPS 并调用 `POST /api/media/parse`。该接口只创建 `processing_tasks` 记录并把任务投递给 Celery；真正的 FFmpeg/OpenCV/pydicom 拆帧由 worker 执行。接口支持 `parse_fps`、`max_frames` 和 `target_width`，用于生成后续 SAM 2 / SAM 3 视频处理可复用的标准帧序列；视频帧按 `frame_%06d.jpg` 连续命名，帧表会记录 `timestamp_ms` 和 `source_frame_number`，任务完成结果会返回 `frame_sequence` 元数据。worker 每次更新任务状态后会发布到 Redis `seg:progress` 频道，FastAPI 订阅后转发到 `/ws/progress`，前端 Dashboard 可实时更新。Dashboard 的 WebSocket 状态由浏览器 `onopen/onclose/onerror` 驱动，客户端会定时发送 `ping` 心跳，服务端返回 `status` 确认连接。Dashboard 也可调用 `/api/tasks/{id}/cancel`、`/api/tasks/{id}/retry` 和 `/api/tasks/{id}` 完成任务取消、重试与失败详情查看。
视频导入只创建项目并把源视频保存到 MinIO，不会自动拆帧；用户在项目库点击“生成帧”后，再选择目标 FPS 并调用 `POST /api/media/parse`。该接口只创建 `processing_tasks` 记录并把任务投递给 Celery；真正的 FFmpeg/OpenCV/pydicom 拆帧由 worker 执行。接口支持 `parse_fps`、`max_frames` 和 `target_width`，用于生成后续 SAM 2 视频处理可复用的标准帧序列；视频帧按 `frame_%06d.jpg` 连续命名，帧表会记录 `timestamp_ms` 和 `source_frame_number`，任务完成结果会返回 `frame_sequence` 元数据。worker 每次更新任务状态后会发布到 Redis `seg:progress` 频道，FastAPI 订阅后转发到 `/ws/progress`，前端 Dashboard 可实时更新。Dashboard 的任务进度区展示 queued/running/success/failed/cancelled 最近任务，处理中统计只计算 queued/running；WebSocket 状态由浏览器 `onopen/onclose/onerror` 驱动，客户端会定时发送 `ping` 心跳，服务端返回 `status` 确认连接。Dashboard 也可调用 `/api/tasks/{id}/cancel`、`/api/tasks/{id}/retry` 和 `/api/tasks/{id}` 完成任务取消、重试与失败详情查看。
### 步骤 7: 安装前端依赖并构建
@@ -417,9 +421,9 @@ sudo apt autoremove -y && sudo apt clean
conda clean --all -y
# 3. 仅保留最小模型
rm ~/Desktop/Seg_Server/models/sam2_hiera_large.pt
rm ~/Desktop/Seg_Server/models/sam2_hiera_base_plus.pt
rm ~/Desktop/Seg_Server/models/sam2_hiera_small.pt
rm ~/Desktop/Seg_Server/models/sam2.1_hiera_large.pt
rm ~/Desktop/Seg_Server/models/sam2.1_hiera_base_plus.pt
rm ~/Desktop/Seg_Server/models/sam2.1_hiera_small.pt
# 4. 如需安装 sam2 包，确保有 >5GB 可用空间后再执行
```
@@ -431,7 +435,7 @@ rm ~/Desktop/Seg_Server/models/sam2_hiera_small.pt
**解决**:
```bash
# 1. 确认模型文件存在
ls ~/Desktop/Seg_Server/models/sam2_hiera_tiny.pt
ls ~/Desktop/Seg_Server/models/sam2.1_hiera_tiny.pt
# 2. 安装 sam2（需 >5GB 磁盘空间）
cd /tmp
@@ -461,8 +465,8 @@ pip install -e . --no-build-isolation
- 前端 `predictMask()` 已发送后端需要的 `image_id`、`prompt_type`、`prompt_data`，并把后端 `polygons` 转成 Konva `pathData`。
- 工作区点选/框选会使用当前帧的数据库 `frame.id` 调用 `/api/ai/predict`。
- 工作区 SAM 2 交互式细化包含反向点时会启用后端背景过滤；若反向点排除了当前候选区域并返回空结果，前端会移除旧候选 mask。
- AI 页面生成的 SAM 2/SAM 3 mask 会写入全局 `masks` 并自动选中；右侧分类树可直接给生成结果换标签，“推送至工作区编辑”会切回工作区的多边形调整工具并保留选择。
- 工作区 SAM 2.1 交互式细化包含反向点时会启用后端背景过滤；若反向点排除了当前候选区域并返回空结果，前端会移除旧候选 mask。
- AI 页面只显示本页新生成的 SAM 2.1 候选，不会把工作区已有 mask 带入 AI 画布；新生成 mask 会写入全局 `masks` 并自动选中，右侧分类树可直接给生成结果换标签，“推送至工作区编辑”会切回工作区的多边形调整工具并保留选择。
- 工作区“传播片段”会使用当前选中区域或当前帧第一个区域作为 seed，调用 `/api/ai/propagate`，并在完成后刷新已保存标注。
- 前端 `exportCoco()` 已对齐到 `/api/export/{projectId}/coco`。
- 工作区“导出 JSON 标注集”和“导出 PNG Mask ZIP”按钮已绑定下载流程；导出前会先保存当前待归档的前端 mask。