From f41d9c20f5ab8b6b05669ab58b03766395b996eb Mon Sep 17 00:00:00 2001 From: admin <572701190@qq.com> Date: Wed, 29 Apr 2026 22:32:06 +0800 Subject: [PATCH] =?UTF-8?q?2026-04-29-22-29-26=20-=20=E5=AE=8C=E5=96=84REA?= =?UTF-8?q?DME.md=EF=BC=9A=E7=B3=BB=E7=BB=9F=E6=9E=B6=E6=9E=84+=E6=8A=80?= =?UTF-8?q?=E6=9C=AF=E6=A0=88+=E5=AE=8C=E6=95=B4=E9=83=A8=E7=BD=B2?= =?UTF-8?q?=E6=B5=81=E7=A8=8B+=E5=B8=B8=E8=A7=81=E9=97=AE=E9=A2=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 388 ++++++++++++++++++++++- 工程分析/实现方案-2026-04-29-22-29-26.md | 42 +++ 工程分析/测试方案-2026-04-29-22-29-26.md | 48 +++ 工程分析/经验记录.md | 18 ++ 工程分析/需求分析-2026-04-29-22-29-26.md | 50 +++ 5 files changed, 536 insertions(+), 10 deletions(-) create mode 100644 工程分析/实现方案-2026-04-29-22-29-26.md create mode 100644 工程分析/测试方案-2026-04-29-22-29-26.md create mode 100644 工程分析/需求分析-2026-04-29-22-29-26.md diff --git a/README.md b/README.md index ef9f2f6..974698f 100644 --- a/README.md +++ b/README.md @@ -2,19 +2,387 @@ GHBanner -# Run and deploy your AI Studio app +# 语义分割系统（SegServer） -This contains everything you need to run your app locally. +> 基于 React + FastAPI + SAM 2 的全栈交互式图像/视频语义分割与标注平台。 +> +> 支持本地多媒体资产上传、服务器端按帧解析、AI 视觉大模型实时推理（正反向选点、框选生成分割 Mask）、动态图层状态管理及最终标注数据结构化导出。 -View your app in AI Studio: https://ai.studio/apps/2707f0e1-d453-4594-a618-fba53cb937c4 +--- -## Run Locally +## 核心功能 -**Prerequisites:** Node.js +- **多媒体资产管理** — 支持视频（MP4/AVI/MOV）和 DICOM 医学影像的上传、存储与解析 +- **AI 智能分割引擎** — 集成 SAM 2 模型，支持点分割（point）、框分割（box）、语义分割（semantic）和自动分割（auto） +- **交互式画布标注** — 基于 Konva 的高性能 Canvas，支持缩放/平移/选点/框选，实时渲染 Mask 遮罩 +- **本体字典管理** — 可配置的分类体系、颜色映射、图层优先级（z-index） +- **项目工作区** — 项目创建、帧浏览、多图层标注、进度追踪 +- **数据导出** — 支持 COCO JSON 格式和 PNG Mask 批量导出 +--- -1. Install dependencies: - `npm install` -2. Set the `GEMINI_API_KEY` in [.env.local](.env.local) to your Gemini API key -3. Run the app: - `npm run dev` +## 系统架构 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ 前端展示层 (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` 中定义的代码编纂流程。 diff --git a/工程分析/实现方案-2026-04-29-22-29-26.md b/工程分析/实现方案-2026-04-29-22-29-26.md new file mode 100644 index 0000000..95abc05 --- /dev/null +++ b/工程分析/实现方案-2026-04-29-22-29-26.md @@ -0,0 +1,42 @@ +# 实现方案 - 2026-04-29-22-29-26 + +## 对应需求 +- 需求分析文档: `需求分析-2026-04-29-22-29-26.md` + +## 方案概述 +将现有 20 行的旧版 README.md 重写为完整的项目文档，涵盖系统介绍、技术架构、目录结构、环境准备、分步部署流程、配置说明和常见问题。 + +## 修改文件清单 + +### 文件 1: README.md（重写） +- **修改类型**: 重写 +- **内容结构**: + 1. 项目标题与概述 + 2. 核心功能列表 + 3. 系统架构图（文本版） + 4. 技术栈表格 + 5. 目录结构说明 + 6. 环境准备（系统依赖、Conda、Node.js） + 7. 部署流程（分步命令） + - 步骤 1: 基础设施（PostgreSQL/Redis/MinIO/FFmpeg） + - 步骤 2: Conda 环境创建与 Python 依赖安装 + - 步骤 3: SAM 2 模型权重下载 + - 步骤 4: 数据库初始化 + - 步骤 5: 后端启动 + - 步骤 6: 前端依赖安装与构建 + - 步骤 7: 前端启动 + 8. 一键启动脚本说明 + 9. 环境变量配置说明 + 10. 访问地址与默认凭证 + 11. 常见问题（磁盘空间、SAM2 安装） + +## 新增依赖 +无 + +## 兼容性分析 +- 无业务代码变更 +- 回滚策略: 从 git 历史恢复旧 README + +## 预估工作量 +- 文档编写: 15 分钟 +- 验证: 5 分钟 diff --git a/工程分析/测试方案-2026-04-29-22-29-26.md b/工程分析/测试方案-2026-04-29-22-29-26.md new file mode 100644 index 0000000..fd1f4b4 --- /dev/null +++ b/工程分析/测试方案-2026-04-29-22-29-26.md @@ -0,0 +1,48 @@ +# 测试方案 - 2026-04-29-22-29-26 + +## 对应实现方案 +- 实现方案文档: `实现方案-2026-04-29-22-29-26.md` + +## 测试范围 +- README.md 内容完整性 +- Markdown 语法正确性 +- 部署命令准确性 + +## 测试用例 + +### 用例 1: 文档结构完整性 +- **前置条件**: README.md 已更新 +- **操作步骤**: 检查是否包含以下章节 + 1. 项目概述 + 2. 核心功能 + 3. 系统架构 + 4. 技术栈 + 5. 目录结构 + 6. 环境准备 + 7. 部署流程 + 8. 一键启动 + 9. 环境变量 + 10. 访问地址 + 11. 常见问题 +- **预期结果**: 全部 11 个章节均存在 +- **通过标准**: grep 每个章节标题均有匹配 + +### 用例 2: Markdown 渲染验证 +- **前置条件**: README.md 已更新 +- **操作步骤**: 在 Gitea 或 Markdown 预览器中打开 +- **预期结果**: 无格式错乱，表格/代码块/标题层级正确 +- **通过标准**: 视觉检查通过 + +### 用例 3: 部署命令准确性抽查 +- **前置条件**: README.md 已更新 +- **操作步骤**: 随机抽取 3 条命令在 Shell 中验证语法 +- **预期结果**: 命令格式正确，路径存在 +- **通过标准**: 3/3 通过 + +## 回归测试 +- [ ] 不破坏现有文件 +- [ ] .gitignore 未受影响 + +## 测试环境 +- Gitea Markdown 渲染器 +- Shell bash diff --git a/工程分析/经验记录.md b/工程分析/经验记录.md index 2329580..d579350 100644 --- a/工程分析/经验记录.md +++ b/工程分析/经验记录.md @@ -99,4 +99,22 @@ AI 助手运行的容器/环境与项目实际开发环境分离，后者才装 --- +## 2026-04-29-22-29-26 — README.md 完善 + +### A. 具体问题 +项目全栈改造完成后，README.md 仍为旧版 AI Studio 模板，未反映真实系统架构和部署流程，新用户无法按文档独立完成部署。 + +### B. 产生原因 +前期聚焦功能开发，文档滞后；改造涉及后端/前端/基础设施/AI 模型多个层级，文档编写工作量大。 + +### C. 解决方案 +按代码编纂工作流，编写需求分析→实现方案→测试方案，然后一次性重写 README.md，涵盖系统架构、技术栈、目录结构、分步部署命令、环境变量、访问凭证、常见问题。 + +### D. 后续如何避免问题 +- 任何架构级变更后，同步更新 README.md +- 将 README 纳入代码审查清单 +- 新成员入职时按 README 走通部署流程作为验收标准 + +--- + > 新增经验请追加到文件末尾，保持时间倒序或正序均可，但需确保每条经验包含完整的 A/B/C/D 四段。 diff --git a/工程分析/需求分析-2026-04-29-22-29-26.md b/工程分析/需求分析-2026-04-29-22-29-26.md new file mode 100644 index 0000000..4bef936 --- /dev/null +++ b/工程分析/需求分析-2026-04-29-22-29-26.md @@ -0,0 +1,50 @@ +# 需求分析 - 2026-04-29-22-29-26 + +## 需求来源 +- 提出时间: 2026-04-29-22-29-26 +- 需求类型: 文档完善 + +## 原始需求描述 +完善 README.md，在其中加入程序部署流程。 + +## 需求拆解 + +### 需求 1: 重写 README.md 项目概述 +- **详细描述**: 当前 README 仍为 AI Studio 旧模板，需更新为反映全栈语义分割系统的真实定位 +- **优先级**: P0-阻塞 +- **影响范围**: README.md +- **验收标准**: README 开篇准确描述项目定位、核心功能、技术栈 + +### 需求 2: 加入系统架构图/说明 +- **详细描述**: 用文本或 Markdown 表格描述前后端架构拓扑 +- **优先级**: P0-阻塞 +- **影响范围**: README.md +- **验收标准**: 读者可从 README 理解系统各层级关系 + +### 需求 3: 加入完整部署流程 +- **详细描述**: 包含基础设施安装（PostgreSQL/Redis/MinIO/FFmpeg）、Conda 环境配置、Python 依赖安装、模型权重下载、前后端启动 +- **优先级**: P0-阻塞 +- **影响范围**: README.md +- **验收标准**: 新用户按 README 可独立完成从零到运行的全部部署 + +### 需求 4: 加入目录结构说明 +- **详细描述**: 列出 backend/、src/、models/ 等关键目录的用途 +- **优先级**: P1-高 +- **影响范围**: README.md +- **验收标准**: 目录结构清晰，便于开发者快速定位代码 + +### 需求 5: 加入环境变量和配置说明 +- **详细描述**: 说明 .env、backend/.env 等配置文件的作用和必填项 +- **优先级**: P1-高 +- **影响范围**: README.md +- **验收标准**: 配置项完整，默认值合理 + +## 约束条件 +- 使用中文撰写 README（界面已中文，文档保持一致） +- 不修改任何业务代码 +- 保留现有 banner 图片（如有） + +## 风险评估 +| 风险点 | 影响 | 缓解措施 | +|--------|------|----------| +| 文档与实际代码不同步 | 中 | 基于实际已部署的代码和配置编写 |