docs/PET_VLM_PROJECT_PLAN.md

# FDG-PET 区域代谢多模态项目定义

## 1. 当前数据状态

当前目录已经清理为一一配对的数据集：

- FDG-PET 体数据：`fdgpet_M00_112/fdgpet_M00_112/*.nii.gz`，共 1015 个。
- 区域 SUVR 表：`petfdg_suvr_csv/petfdg_suvr_csv/*.csv`，共 1015 个。
- 成功配对：1015 对。
- 未配对文件：0 个。
- PET 尺寸：全部为 `112 x 128 x 112`。
- 体素间距：全部为 `1.5 x 1.5 x 1.5 mm`。
- 每个 CSV：121 行，其中 `Background` 1 行，真实脑区 120 行。

已经固定的数据划分：

| split | samples | subjects |
|---|---:|---:|
| train | 710 | 710 |
| val | 152 | 152 |
| test | 153 | 153 |

划分文件保存在：

- `metadata/pet_fdg_manifest.csv`
- `metadata/splits/train.csv`
- `metadata/splits/val.csv`
- `metadata/splits/test.csv`
- `metadata/splits/split_summary.csv`
- `metadata/splits/pet_fdg_manifest_with_split.csv`

划分按 `subject_id` 完成，避免同一受试者泄漏到不同 split。

## 2. 任务目标判断

当前阶段的主任务不是分割，也不应该直接定义为临床分类。

### 不是分割

分割任务需要 voxel-level mask 或 ROI label map 作为监督信号。当前目录没有脑区 mask、病灶 mask、配准标签或分割真值，只有 PET 图像和由 PET 派生出来的区域 SUVR CSV。因此不能把当前项目定义为分割。

### 目前也不是临床分类

分类任务需要类别标签，例如 CN/MCI/AD、pMCI/sMCI、阳性/阴性、疾病分期等。当前目录没有诊断标签、年龄、性别、MMSE、ADAS-Cog 或转化状态。因此现在不能严肃地训练“AD 分类器”，也不能声称模型能做诊断分类。

### 当前最合理目标

当前最合理、数据支撑最充分的目标是：

> 训练一个 FDG-PET 区域代谢理解 encoder，使模型能够从 3D PET 图像中学习区域代谢模式，并与 120 脑区 SUVR 数值表示对齐。这个 encoder 后续可作为 VLM 的视觉/医学影像前端，用于分类、检索、问答或报告生成。

换句话说，当前阶段应该做的是 **PET-SUVR 表征学习和区域代谢理解**，不是最终临床任务。

## 3. 当前可训练任务

在没有临床标签的条件下，可以做以下任务：

1. **PET -> SUVR 回归**
   - 输入：3D FDG-PET。
   - 输出：120 个脑区 SUVR。
   - 目的：验证 image encoder 是否真正学到区域代谢分布。

2. **PET-SUVR 对比学习**
   - 同一扫描的 PET embedding 和 SUVR embedding 作为正样本。
   - 不同扫描作为负样本。
   - 目的：把 3D 图像表示和区域结构化表示对齐。

3. **高低代谢脑区预测**
   - 预测 top-k 高 SUVR 脑区和 top-k 低 SUVR 脑区。
   - 目的：形成可解释的区域级输出。

4. **相似病例检索**
   - 用 PET embedding 或 PET-SUVR fused embedding 检索相似代谢模式病例。
   - 目的：验证表示空间是否有实际用途。

5. **规则报告生成**
   - 基于真实或预测 SUVR 生成结构化文本摘要。
   - 目的：为后续 VLM/LLM 接入准备可控文本接口。

## 4. 后续可扩展任务

补充临床标签后，才建议做：

- CN / MCI / AD 三分类。
- AD vs CN 二分类。
- pMCI vs sMCI 转化预测。
- MMSE / ADAS-Cog 回归。
- 脑龄或疾病风险评分。
- PET 图像问答。
- 自动报告生成。

这些是下游任务，不是当前数据本身直接支持的第一任务。

## 5. Backbone 与 VLM 路线

不建议从头训练完整 VLM。1015 个 3D 样本太少，直接训练大模型会过拟合。推荐路线是：

```text
3D FDG-PET
  -> pretrained 3D medical image encoder
  -> projection layer / Q-Former / Perceiver resampler
  -> visual tokens
  -> fusion with SUVR region tokens
  -> downstream head or LLM adapter
```

推荐阶段：

1. **流程基线**
   - 使用当前 `scripts/train_pet_vlm_baseline.py` 里的小型 3D CNN。
   - 目的只是验证数据读取、预处理、loss、训练循环。

2. **正式第一版 encoder**
   - 推荐 MedicalNet 3D ResNet-50。
   - 原因：轻量、稳定、3D 医学影像预训练，适合作为 PET encoder 起点。

3. **架构对照**
   - SwinUNETR 或 SAM-Med3D image encoder。
   - 目的：验证 Transformer-style encoder 是否比 ResNet 更适合区域代谢建模。

4. **VLM 接入**
   - 不让 LLM 直接读 NIfTI。
   - 先由 3D encoder 把 PET 压成 embedding/token。
   - 再通过 projector 或 Q-Former 接到语言模型。

## 6. 当前保留文件

项目根目录保留：

```text
fdgpet_M00_112/                  # 原始 PET NIfTI
petfdg_suvr_csv/                 # 原始 SUVR CSV，已清理为 1015 个
metadata/
  pet_fdg_manifest.csv           # 全量 1015 对配对清单
  splits/
    train.csv
    val.csv
    test.csv
    split_summary.csv
    pet_fdg_manifest_with_split.csv
docs/
  PET_VLM_PROJECT_PLAN.md
scripts/
  pet_vlm_dataset.py             # 可复用 Dataset 和预处理
  train_pet_vlm_baseline.py      # 可复用训练基线
requirements.txt
预训练3D脑MRI编码器验证报告.pdf
```

已经删除的一次性或临时文件：

- manifest 生成脚本。
- split 生成脚本。
- smoke test checkpoint。
- `__pycache__`。

## 7. 当前代码入口

安装依赖：

```bash
pip install -r requirements.txt
```

运行最小 PET-SUVR 对齐训练：

```bash
python scripts/train_pet_vlm_baseline.py --epochs 2 --batch-size 2
```

显存不够时：

```bash
python scripts/train_pet_vlm_baseline.py --epochs 2 --batch-size 1 --output-size 80 80 80
```

当前训练脚本默认读取：

- train：`metadata/splits/train.csv`
- val：`metadata/splits/val.csv`

test 集不参与调参，只用于最终评估。

## 8. 下一步决策

下一步应该做两件事：

1. 把当前小 3D CNN baseline 跑通完整 train/val，看 PET->SUVR 回归和对齐 loss 是否稳定下降。
2. 引入 MedicalNet 3D ResNet-50 作为正式 PET encoder，替换当前小 CNN。

如果之后拿到临床标签，再新增分类任务头，而不是推翻当前路线。