GHBanner
# 语义分割系统（SegServer） > 基于 React + FastAPI + SAM 2 的全栈交互式图像/视频语义分割与标注平台。 > > 支持本地多媒体资产上传、服务器端按帧解析、AI 视觉大模型实时推理（正反向选点、框选生成分割 Mask）、动态图层状态管理及最终标注数据结构化导出。 --- ## 核心功能 - **多媒体资产管理** — 支持视频（MP4/AVI/MOV）和 DICOM 医学影像的上传、存储与解析 - **AI 智能分割引擎** — 集成 SAM 2 模型，支持点分割（point）、框分割（box）、语义分割（semantic）和自动分割（auto） - **交互式画布标注** — 基于 Konva 的高性能 Canvas，支持缩放/平移/选点/框选，实时渲染 Mask 遮罩 - **本体字典管理** — 可配置的分类体系、颜色映射、图层优先级（z-index） - **项目工作区** — 项目创建、帧浏览、多图层标注、进度追踪 - **数据导出** — 支持 COCO JSON 格式和 PNG Mask 批量导出 --- ## 系统架构 ``` ┌─────────────────────────────────────────────────────────────┐ │ 前端展示层 (React 19 + Vite + TailwindCSS) │ │ localhost:3000 │ │ Zustand(状态) + Axios(API) + WebSocket(实时进度) │ │ Konva(Canvas渲染) + lucide-react(图标) │ └──────────────────────────┬──────────────────────────────────┘ │ HTTP / WebSocket ┌──────────────────────────▼──────────────────────────────────┐ │ 业务逻辑层 (FastAPI + Python 3.11) │ │ localhost:8000 │ │ ├── /api/auth 登录认证 │ │ ├── /api/projects 项目 & 视频帧 CRUD │ │ ├── /api/templates 本体字典（分类/颜色/z-index） │ │ ├── /api/media 文件上传 & FFmpeg/pydicom 帧解析 │ │ ├── /api/ai SAM 2 推理（点/框/语义/自动分割） │ │ └── /api/export COCO JSON / PNG Masks 导出 │ └──────────────────────────┬──────────────────────────────────┘ │ SQLAlchemy 2.0 ┌──────────────────────────▼──────────────────────────────────┐ │ 数据持久化层 │ │ PostgreSQL 14 — 项目/帧/标注/Mask 元数据 │ │ Redis 6 — 缓存 & 任务队列状态 │ │ MinIO — 对象存储（原始视频/解析帧/Mask图像） │ └─────────────────────────────────────────────────────────────┘ ``` --- ## 技术栈 | 层级 | 技术选型 | 版本 | |------|----------|------| | 前端框架 | React + TypeScript | React 19, TS 5.8 | | 构建工具 | Vite | v6 | | 样式方案 | TailwindCSS + 自定义深色主题 | v4 | | 状态管理 | Zustand | - | | Canvas 渲染 | Konva + react-konva | - | | HTTP 客户端 | Axios | - | | 后端框架 | FastAPI | v0.136+ | | 数据库 ORM | SQLAlchemy + Alembic | 2.0+ | | 数据库 | PostgreSQL | 14 | | 缓存 | Redis | 6 | | 对象存储 | MinIO | 2025+ | | AI 推理 | SAM 2 (Meta) + PyTorch | - | | 视频处理 | FFmpeg + OpenCV | 4.4+ | | DICOM 处理 | pydicom | 3.0+ | --- ## 目录结构 ``` Seg_Server/ ├── backend/ # FastAPI 后端 │ ├── main.py # 应用入口（CORS/生命周期/路由注册） │ ├── config.py # 环境变量配置（Pydantic Settings） │ ├── database.py # SQLAlchemy 引擎 + Session │ ├── models.py # ORM 模型（Project/Frame/Template/Annotation/Mask） │ ├── schemas.py # Pydantic 请求/响应校验模型 │ ├── minio_client.py # MinIO 上传/下载/预签名URL封装 │ ├── redis_client.py # Redis 连接封装 │ ├── download_sam2.py # SAM 2 模型权重自动下载脚本 │ ├── requirements.txt # Python 依赖 │ ├── routers/ # API 路由 │ │ ├── auth.py # 登录认证 │ │ ├── projects.py # 项目 & 帧 CRUD │ │ ├── templates.py # 本体字典管理 │ │ ├── media.py # 上传 & 解析 │ │ ├── ai.py # SAM 2 推理接口 │ │ └── export.py # 数据导出 │ └── services/ # 业务服务 │ ├── sam2_engine.py # SAM 2 推理引擎（懒加载 + stub降级） │ └── frame_parser.py # FFmpeg 拆帧 / pydicom 读片 ├── src/ # React 前端 │ ├── main.tsx # 应用挂载点 │ ├── App.tsx # 根组件（模块路由 + 鉴权） │ ├── store/ │ │ └── useStore.ts # Zustand 全局状态 │ ├── lib/ │ │ ├── api.ts # Axios 实例 + API 方法封装 │ │ ├── websocket.ts # WebSocket 客户端（解析进度） │ │ └── utils.ts # cn() 工具函数 │ └── components/ # 组件（扁平化目录） │ ├── Login.tsx # 登录页 │ ├── Sidebar.tsx # 左侧导航栏 │ ├── Dashboard.tsx # 总体概况仪表盘（解析队列） │ ├── ProjectLibrary.tsx # 项目库列表 │ ├── VideoWorkspace.tsx # 核心分割工作区布局 │ ├── CanvasArea.tsx # Konva 画布（缩放/平移/选点/Mask渲染） │ ├── ToolsPalette.tsx # 左侧工具栏 │ ├── OntologyInspector.tsx # 右侧本体/属性检查面板 │ ├── FrameTimeline.tsx # 底部时间轴 │ ├── AISegmentation.tsx # AI 智能分割引擎界面 │ └── TemplateRegistry.tsx # 模板库管理 ├── models/ # SAM 2 模型权重（.pt 文件） ├── uploads/ # 临时上传目录 ├── frames/ # 临时帧目录 ├── start_services.sh # 一键启动所有服务脚本 ├── server.ts # 旧版 Express 入口（已弃用） ├── index.html # SPA HTML 入口 ├── vite.config.ts # Vite 构建配置 ├── package.json # npm 依赖与脚本 └── tsconfig.json # TypeScript 配置 ``` --- ## 环境准备 ### 系统要求 - **OS**: Ubuntu 22.04 LTS - **GPU**: NVIDIA GPU（推荐 RTX 4090 或同等算力），用于 SAM 2 推理 - **CUDA**: 12.x / 13.x - **Node.js**: 22.x+ - **Python**: 3.11（通过 Miniconda/Anaconda 管理） ### 安装系统级依赖 ```bash # 更新包索引 sudo apt update # 安装 PostgreSQL、Redis、FFmpeg、构建工具 sudo apt install -y postgresql postgresql-contrib redis-server ffmpeg \ libpq-dev build-essential curl ca-certificates gnupg # 安装 MinIO（二进制方式） mkdir -p ~/minio_data cd /tmp wget https://dl.min.io/server/minio/release/linux-amd64/minio chmod +x minio sudo mv minio /usr/local/bin/ ``` --- ## 部署流程 ### 步骤 1: 配置 PostgreSQL 数据库 ```bash # 启动服务 sudo systemctl start postgresql redis-server # 创建数据库和用户 sudo -u postgres psql -c "CREATE DATABASE segserver;" sudo -u postgres psql -c "CREATE USER seguser WITH PASSWORD 'segpass123';" sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE segserver TO seguser;" sudo -u postgres psql -d segserver -c "GRANT ALL ON SCHEMA public TO seguser;" sudo -u postgres psql -c "ALTER DATABASE segserver OWNER TO seguser;" ``` ### 步骤 2: 启动 MinIO ```bash nohup minio server ~/minio_data --console-address :9001 > /tmp/minio.log 2>&1 & # 验证 # API: http://localhost:9000 # 控制台: http://localhost:9001 （minioadmin / minioadmin） ``` ### 步骤 3: 创建 Conda 环境并安装 Python 依赖 ```bash # 创建环境 conda create -n seg_server python=3.11 -y conda activate seg_server # 安装 PyTorch（根据 CUDA 版本选择） # CUDA 12.x 用户: pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124 # CPU 用户（无 GPU）: pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu # 安装后端依赖 cd ~/Desktop/Seg_Server/backend pip install -r requirements.txt ``` ### 步骤 4: 下载 SAM 2 模型权重 ```bash 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) ``` > **注意**：当前系统磁盘紧张时，建议仅保留 `sam2_hiera_tiny.pt`，删除其他模型以释放空间。 ### 步骤 5: 配置环境变量 项目根目录已提供默认配置，如需修改请编辑以下文件： **backend/.env**（数据库/Redis/MinIO/SAM 路径）: ```ini DATABASE_URL=postgresql://seguser:segpass123@localhost:5432/segserver REDIS_URL=redis://localhost:6379/0 MINIO_ENDPOINT=localhost:9000 MINIO_ACCESS_KEY=minioadmin MINIO_SECRET_KEY=minioadmin MINIO_BUCKET_NAME=seg-media SAM2_MODEL_PATH=/home/wkmgc/Desktop/Seg_Server/models/sam2_hiera_tiny.pt ``` ### 步骤 6: 启动后端服务 ```bash cd ~/Desktop/Seg_Server/backend source ~/miniconda3/etc/profile.d/conda.sh conda activate seg_server uvicorn main:app --host 0.0.0.0 --port 8000 # 或使用后台模式 nohup uvicorn main:app --host 0.0.0.0 --port 8000 > /tmp/fastapi.log 2>&1 & ``` 后端启动后将自动： - 创建数据库表（如果不存在） - 检查 MinIO bucket 是否存在 - 测试 Redis 连接 - 懒加载 SAM 2 模型（权重存在且 sam2 包已安装时） ### 步骤 7: 安装前端依赖并构建 ```bash cd ~/Desktop/Seg_Server # 安装依赖 npm install # 类型检查 npm run lint # 生产构建 npm run build # 启动前端服务 npm start # 或使用后台模式 nohup npm start > /tmp/frontend.log 2>&1 & ``` --- ## 一键启动（推荐） 项目根目录提供了 `start_services.sh` 脚本，可一键启动所有服务： ```bash cd ~/Desktop/Seg_Server ./start_services.sh ``` 脚本将依次检查并启动：PostgreSQL → Redis → MinIO → FastAPI 后端 → 前端。 --- ## 访问地址与默认凭证 | 服务 | 地址 | 说明 | |------|------|------| | 前端界面 | http://localhost:3000 | admin / 123456 | | 后端 API 文档 | http://localhost:8000/docs | Swagger UI | | MinIO 控制台 | http://localhost:9001 | minioadmin / minioadmin | | PostgreSQL | localhost:5432 | seguser / segpass123 | --- ## 可用命令 ### 前端 ```bash npm install # 安装依赖 npm run dev # Vite 开发模式（端口 5173） npm run build # 生产构建（输出到 dist/） npm run lint # TypeScript 类型检查 npm start # Node.js 运行 server.ts（旧版） ``` ### 后端 ```bash # 在 conda seg_server 环境中 cd backend uvicorn main:app --host 0.0.0.0 --port 8000 --reload # 开发模式（热重载） uvicorn main:app --host 0.0.0.0 --port 8000 # 生产模式 ``` --- ## 常见问题 ### Q1: 磁盘空间不足导致 PyTorch / sam2 安装失败 **现象**: `OSError: [Errno 28] No space left on device` **解决**: ```bash # 1. 清理系统包缓存 sudo apt autoremove -y && sudo apt clean # 2. 清理 conda 缓存 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 # 4. 如需安装 sam2 包，确保有 >5GB 可用空间后再执行 ``` ### Q2: SAM 2 推理返回 dummy polygons（矩形框） **原因**: `sam2` Python 包未安装，或模型权重路径不正确。 **解决**: ```bash # 1. 确认模型文件存在 ls ~/Desktop/Seg_Server/models/sam2_hiera_tiny.pt # 2. 安装 sam2（需 >5GB 磁盘空间） cd /tmp git clone --depth 1 https://github.com/facebookresearch/segment-anything-2.git cd segment-anything-2 pip install -e . --no-build-isolation # 3. 重启后端服务 ``` ### Q3: MinIO 报 `XMinioStorageFull` **原因**: 系统磁盘可用空间低于 MinIO 默认阈值。 **解决**: 清理解析产生的临时帧文件或扩展磁盘空间。 ### Q4: 前端无法连接后端 API **检查清单**: 1. 后端是否已启动（`curl http://localhost:8000/health`） 2. `backend/.env` 中的 `cors_origins` 是否包含 `http://localhost:3000` 3. 前端 `src/lib/api.ts` 中的 `baseURL` 是否为 `http://localhost:8000` --- ## 开发团队 本项目基于 Google AI Studio 模板构建，经全栈化改造后用于工业级语义分割场景。 --- > 如需添加新功能或修复问题，请遵循项目根目录 `工程分析/代码编纂工作流.md` 中定义的代码编纂流程。