186 lines
8.4 KiB
Markdown
186 lines
8.4 KiB
Markdown
# 实现方案 - 2026-04-29-21-51-19
|
||
|
||
## 对应需求
|
||
- 需求分析文档: `需求分析-2026-04-29-21-51-19.md`
|
||
|
||
## 方案概述
|
||
在 RTX 4090 + Ubuntu 22.04 环境下，将纯前端 React 应用改造为全栈语义分割系统。本次为**骨架搭建 + 核心能力落地**，优先保证各模块可独立运行并互联互通。
|
||
|
||
## 整体架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ 前端层 (React 19) │
|
||
│ Zustand (状态) + Axios (HTTP) + WebSocket (实时进度) │
|
||
│ Konva (Canvas) + TailwindCSS (样式) │
|
||
└────────────────────────────┬────────────────────────────────────┘
|
||
│ HTTP / WebSocket
|
||
┌────────────────────────────▼────────────────────────────────────┐
|
||
│ 后端层 (FastAPI + Python) │
|
||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||
│ │ 项目/模板 API │ │ 媒体解析 API │ │ AI 推理 API │ │
|
||
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
|
||
│ └─────────────────┼─────────────────┘ │
|
||
│ │ SQLAlchemy │
|
||
│ ┌────────────────────────▼────────────────────────┐ │
|
||
│ │ PostgreSQL (关系数据) │ │
|
||
│ └─────────────────────────────────────────────────┘ │
|
||
│ │ │
|
||
│ ┌────────────────────────▼────────────────────────┐ │
|
||
│ │ MinIO (对象存储: 视频/帧/Mask) │ │
|
||
│ └─────────────────────────────────────────────────┘ │
|
||
│ │ │
|
||
│ ┌────────────────────────▼────────────────────────┐ │
|
||
│ │ Redis (缓存 + 任务队列) │ │
|
||
│ └─────────────────────────────────────────────────┘ │
|
||
│ │ │
|
||
│ ┌────────────────────────▼────────────────────────┐ │
|
||
│ │ SAM 3 (GPU 推理节点) │ │
|
||
│ └─────────────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 修改/新增文件清单
|
||
|
||
### A. 基础设施层
|
||
|
||
#### A1. 系统服务安装
|
||
- **操作**: `sudo apt install postgresql postgresql-contrib redis-server ffmpeg`
|
||
- **操作**: 下载并启动 MinIO 二进制
|
||
- **说明**: 配置 PostgreSQL 数据库/用户，Redis 默认端口，MinIO 端口 9000/9001
|
||
|
||
#### A2. Conda 环境
|
||
- **操作**: `conda create -n seg_server python=3.11`
|
||
- **操作**: 安装 PyTorch 2.5+ CUDA 13.x、FastAPI、SQLAlchemy、psycopg2-binary、redis-py、minio、uvicorn、python-multipart、celery、opencv-python、pillow、scikit-image、pydicom、numpy
|
||
|
||
### B. 后端层 (新增 backend/ 目录)
|
||
|
||
#### B1. `backend/main.py`
|
||
- **类型**: 新增
|
||
- **内容**: FastAPI 入口，CORS 配置， lifespan 管理（启动/关闭数据库、Redis、MinIO 连接）
|
||
|
||
#### B2. `backend/config.py`
|
||
- **类型**: 新增
|
||
- **内容**: 环境变量配置（DB_URL、REDIS_URL、MINIO_ENDPOINT、SAM_MODEL_PATH 等）
|
||
|
||
#### B3. `backend/database.py`
|
||
- **类型**: 新增
|
||
- **内容**: SQLAlchemy engine + session + Base，PostgreSQL 连接
|
||
|
||
#### B4. `backend/models.py`
|
||
- **类型**: 新增
|
||
- **内容**: 数据库 ORM 模型：Project、Frame、Annotation、Template、Mask
|
||
|
||
#### B5. `backend/schemas.py`
|
||
- **类型**: 新增
|
||
- **内容**: Pydantic 数据校验模型
|
||
|
||
#### B6. `backend/minio_client.py`
|
||
- **类型**: 新增
|
||
- **内容**: MinIO 客户端封装（上传、下载、预签名 URL）
|
||
|
||
#### B7. `backend/redis_client.py`
|
||
- **类型**: 新增
|
||
- **内容**: Redis 客户端封装
|
||
|
||
#### B8. `backend/routers/projects.py`
|
||
- **类型**: 新增
|
||
- **内容**: 项目 CRUD API
|
||
|
||
#### B9. `backend/routers/templates.py`
|
||
- **类型**: 新增
|
||
- **内容**: 本体模板 API
|
||
|
||
#### B10. `backend/routers/media.py`
|
||
- **类型**: 新增
|
||
- **内容**: 视频/图片/DCM 上传 API，FFmpeg 拆帧任务触发
|
||
|
||
#### B11. `backend/routers/ai.py`
|
||
- **类型**: 新增
|
||
- **内容**: SAM 3 推理 API（point/box/semantic），Mask 生成与存储
|
||
|
||
#### B12. `backend/routers/export.py`
|
||
- **类型**: 新增
|
||
- **内容**: 标注数据导出（COCO JSON、PNG Mask）
|
||
|
||
#### B13. `backend/services/sam3_engine.py`
|
||
- **类型**: 新增
|
||
- **内容**: SAM 3 模型加载、推理封装、GPU 内存管理
|
||
|
||
#### B14. `backend/services/frame_parser.py`
|
||
- **类型**: 新增
|
||
- **内容**: FFmpeg 视频拆帧、DCM 影像逐帧提取、帧上传 MinIO
|
||
|
||
#### B15. `backend/services/task_queue.py`
|
||
- **类型**: 新增
|
||
- **内容**: Celery + Redis 异步任务队列封装
|
||
|
||
#### B16. `backend/requirements.txt`
|
||
- **类型**: 新增
|
||
- **内容**: Python 依赖清单
|
||
|
||
### C. 前端层 (修改现有 src/)
|
||
|
||
#### C1. `src/store/index.ts` (新增)
|
||
- **内容**: Zustand 全局 Store（project、workspace、annotations、ui 状态）
|
||
|
||
#### C2. `src/lib/api.ts` (新增)
|
||
- **内容**: Axios 实例封装，baseURL 指向 FastAPI
|
||
|
||
#### C3. `src/lib/websocket.ts` (新增)
|
||
- **内容**: WebSocket 客户端，接收解析进度
|
||
|
||
#### C4. `src/App.tsx` (修改)
|
||
- **内容**: 移除 Login 硬编码，接入真实登录 API；Provider 包裹
|
||
|
||
#### C5. `src/components/ProjectLibrary.tsx` (修改)
|
||
- **内容**: 从后端 API 加载项目列表，支持创建/删除
|
||
|
||
#### C6. `src/components/TemplateRegistry.tsx` (修改)
|
||
- **内容**: 从后端 API 加载本体字典，支持动态增删
|
||
|
||
#### C7. `src/components/CanvasArea.tsx` (修改)
|
||
- **内容**: 点击画布捕获坐标，发送至后端 AI 接口，接收并渲染 Mask Path
|
||
|
||
#### C8. `src/components/AISegmentation.tsx` (修改)
|
||
- **内容**: 对接后端 SAM 3 推理接口，显示推理状态
|
||
|
||
#### C9. `src/components/Dashboard.tsx` (修改)
|
||
- **内容**: 显示真实解析队列进度（WebSocket）
|
||
|
||
### D. 部署与运维
|
||
|
||
#### D1. `start_services.sh` (新增)
|
||
- **内容**: 一键启动 PostgreSQL、Redis、MinIO、FastAPI 的脚本
|
||
|
||
#### D2. `backend/download_sam3.py` (新增)
|
||
- **内容**: SAM 3 模型权重自动下载脚本
|
||
|
||
## 新增依赖
|
||
|
||
### Python (conda 环境)
|
||
```
|
||
fastapi uvicorn[standard] python-multipart
|
||
sqlalchemy psycopg2-binary alembic
|
||
redis celery
|
||
minio
|
||
opencv-python pillow scikit-image pydicom numpy
|
||
```
|
||
|
||
### 前端 (npm)
|
||
```
|
||
zustand axios
|
||
```
|
||
|
||
## 兼容性分析
|
||
- Express `server.ts` 将被保留但不再作为默认启动方式，FastAPI 成为主后端
|
||
- 前端路由逻辑不变，仅数据获取方式从内存/mock 改为 HTTP API
|
||
- 回滚策略: 回退到 `npm start` 仍可运行旧版 Express 前端
|
||
|
||
## 预估工作量
|
||
- 基础设施: 20 分钟
|
||
- 后端骨架: 40 分钟
|
||
- 前端改造: 30 分钟
|
||
- SAM 3 部署: 20 分钟
|
||
- 联调验证: 20 分钟
|