20260430_001744-feat: PyTorch CUDA + SAM2 GPU inference, video thumbnail, real FPS + configurable parse FPS, DICOM batch import

工程分析/经验记录.md

@@ -5,6 +5,50 @@
 
 ---
 
+## 2026-04-30-00-17-44 — PyTorch CUDA + SAM2 + 封面 + 帧率 + DICOM 批量导入
+
+### A. 具体问题
+1. PyTorch 为 CPU 版本，SAM2 未安装，GPU 推理不可用
+2. 项目库视频卡片无封面缩略图
+3. 项目库 FPS 为硬编码 "30FPS"，不显示真实原始帧率，也无法修改解析帧率
+4. 不支持 DICOM 连续帧批量导入
+
+### B. 产生原因
+1. 系统磁盘仅 24GB，PyTorch CUDA wheel (~1GB) + SAM2 编译依赖导致 `No space left on device`
+2. 解析视频时未提取封面，Project 模型无 thumbnail_url 字段
+3. 解析视频时未读取原始帧率，Project 模型无 original_fps / parse_fps 字段
+4. upload 接口仅支持单文件，无批量 DICOM 上传接口，Project 无 source_type 区分视频/DICOM
+
+### C. 解决方案
+1. **磁盘扩容后安装 PyTorch CUDA + SAM2**：
+   - `pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124`
+   - `pip install sam2`（成功编译安装 sam2-1.1.0）
+   - 修正 `config.py` 中 `sam_model_config` 为 `configs/sam2/sam2_hiera_t.yaml`（Hydra 包内相对路径）
+   - 验证 `torch.cuda.is_available()` → True，RTX 4090 识别正常
+2. **视频封面**：
+   - `frame_parser.py` 新增 `extract_thumbnail()`，从视频第一帧提取 640px JPEG 封面
+   - `media.py` `parse_media()` 解析视频时自动上传封面到 `projects/{id}/thumbnail.jpg`
+   - `projects.py` 返回 presigned URL
+   - 前端 `ProjectLibrary.tsx` 卡片背景显示 `<img>` 封面
+3. **真实帧率 + 可修改解析帧率**：
+   - `models.py` Project 新增 `original_fps` (Float), `parse_fps` (Float, default=30)
+   - `frame_parser.py` `get_video_fps()` 用 OpenCV 读取真实帧率，`parse_video()` 返回 `(frames, original_fps)`
+   - 前端 `ProjectLibrary.tsx` 上传视频时弹窗允许用户滑动设置 parse_fps (1-60)
+   - 项目卡片显示 `原 60.0fps` 和 `30FPS` 标签
+4. **DICOM 批量导入**：
+   - `models.py` Project 新增 `source_type` (video | dicom)
+   - `media.py` 新增 `/api/media/upload/dicom` 接口，接收 `List[UploadFile]`，上传多个 .dcm 到 `uploads/{id}/dicom/`
+   - `media.py` `parse_media()` 支持 DICOM 模式：从 MinIO 下载整个 dicom 目录 → `parse_dicom()` 解析
+   - 前端 `ProjectLibrary.tsx` 导入按钮展开菜单：导入视频 / 导入 DICOM 序列，DICOM 用 `<input multiple accept=".dcm">`
+
+### D. 后续如何避免问题
+1. **SAM2 配置路径必须用 Hydra 包内相对路径**：`build_sam2()` 使用 Hydra，配置文件必须传 `configs/sam2/xxx.yaml` 而非绝对路径
+2. **数据库 schema 变更必须彻底清理旧表**：PostgreSQL `drop_all()` 可能因外键约束不彻底，生产环境应使用 Alembic 迁移，开发环境应手动 `DROP TABLE ... CASCADE`
+3. **大依赖安装必须预留足够磁盘空间**：PyTorch CUDA (~1GB) + SAM2 build (~500MB temp) 至少需要 5GB 可用空间
+4. **前端上传交互必须区分媒体类型**：视频和 DICOM 的上传流程、文件选择器 `accept`、后续解析逻辑完全不同，应提供明确的模式切换
+
+---
+
 ## 2026-04-29-23-28-13 — 视频帧显示链路全修复
 
 ### A. 具体问题