admin/Pre_Seg_Server
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
4ec917efe756b61eda08eb270909f66d4fc03c4e
Pre_Seg_Server/README.md

14 KiB
Raw Blame History

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 管理）

安装系统级依赖

# 更新包索引
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 数据库

# 启动服务
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

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 依赖

# 创建环境
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 模型权重

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 路径）:

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: 启动后端服务

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: 安装前端依赖并构建

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 脚本，可一键启动所有服务：

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

可用命令

前端

npm install       # 安装依赖
npm run dev       # Vite 开发模式（端口 5173）
npm run build     # 生产构建（输出到 dist/）
npm run lint      # TypeScript 类型检查
npm start         # Node.js 运行 server.ts（旧版）

后端

# 在 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

解决:

# 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 包未安装，或模型权重路径不正确。

解决:

# 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 中定义的代码编纂流程。

Reference in New Issue View Git Blame Copy Permalink