《nnU-Net 0基础入门（4）：第一次跑通 nnU-Net v2，plan、preprocess、train、predict 全流程》

本篇学习目标

这是《nnU-Net 0基础入门》系列的第 4 篇。前面我们已经完成了安装和数据集格式准备。本文要做的是跑通第一个完整闭环：从数据集编号开始，完成 plan、preprocess、train 和 predict。

读完本文，你应该能够：

知道 nnUNetv2_plan_and_preprocess 实际做了哪三件事。
能启动一个 fold 的训练，并理解 DATASET_ID CONFIGURATION FOLD 三个参数。
能用训练好的模型对新图像执行预测。
知道每一步的输入、输出和常见检查点。

1. 完整闭环长什么样

如果你已经按第 3 篇准备好了 Dataset001_Liver 这类数据集，那么 nnU-Net v2 的第一个闭环可以概括为：

flowchart LR
    A[nnUNet_raw 中的数据集] --> B[plan_and_preprocess]
    B --> C[nnUNet_preprocessed 中的 fingerprint / plans / 预处理数据]
    C --> D[nnUNetv2_train]
    D --> E[nnUNet_results 中的 checkpoint 和日志]
    E --> F[nnUNetv2_predict]
    F --> G[输出分割结果]

这里有三个目录会反复出现：

nnUNet_raw：放原始数据集。
nnUNet_preprocessed：放数据分析、计划文件和预处理后的训练数据。
nnUNet_results：放训练好的模型、日志和验证结果。

2. 第一步：plan and preprocess

官方文档推荐新数据集第一次运行：

nnUNetv2_plan_and_preprocess -d 1 --verify_dataset_integrity

如果你的数据集是 Dataset123_MyDataset，命令就是：

nnUNetv2_plan_and_preprocess -d 123 --verify_dataset_integrity

--verify_dataset_integrity 表示先检查数据集完整性。对初学者来说，第一次跑某个数据集一定建议加上它。这样能提前发现图像命名、标签缺失、类别值不一致等问题。

这个命令实际做三件事：

extract dataset fingerprint：提取数据集指纹，也就是图像尺寸、spacing、强度分布等数据特征。
experiment planning：生成实验计划，决定会有哪些 configuration，例如 2d 或 3d_fullres。
preprocessing：按计划执行预处理，把训练需要的中间数据写到 nnUNet_preprocessed。

完成后，你可以检查：

ls "$nnUNet_preprocessed"/Dataset001_Liver

通常会看到类似：

dataset_fingerprint.json
dataset.json
nnUNetPlans.json
nnUNetPlans_2d/
nnUNetPlans_3d_fullres/

实际目录名会因数据集和 nnU-Net 版本有所不同，但 dataset_fingerprint.json 和 nnUNetPlans.json 是你需要重点认识的文件。前者描述数据，后者描述 nnU-Net 为数据生成的训练计划。

3. 第二步：选择一个 configuration

configuration 可以理解为训练配置。官方训练文档列出的常见配置包括：

2d：使用 2D U-Net。
3d_fullres：使用全分辨率 3D U-Net。
3d_lowres：使用低分辨率 3D U-Net。
3d_cascade_fullres：级联的全分辨率 3D U-Net。

不是每个数据集都会生成所有配置。官方文档明确提醒：小数据集或不需要 cascade 的数据集可能不会生成 3d_lowres 和 3d_cascade_fullres。

第一次学习时，可以优先选择已经生成的 3d_fullres 或 2d。具体选哪个，要看预处理后目录里有哪些配置，以及你的 GPU 显存是否够用。

4. 第三步：训练一个 fold

官方基本训练命令是：

nnUNetv2_train DATASET_NAME_OR_ID CONFIGURATION FOLD

例如训练数据集 1 的 3d_fullres 配置、第 0 个 fold：

nnUNetv2_train 1 3d_fullres 0

fold 指交叉验证中的数据划分编号。nnU-Net 通常用 5-fold cross-validation，也就是把训练集分成 5 份，每次用其中一份做验证，其余做训练。第一个闭环里，我们先训练 fold 0，目的是跑通流程。后面第 5、6 篇会系统讲 5-fold 和模型选择。

如果你之后想使用 nnUNetv2_find_best_configuration 自动比较配置和做 ensemble，官方文档建议训练时加 --npz，保存验证概率：

nnUNetv2_train 1 3d_fullres 0 --npz

如果有多张 GPU，可以用 CUDA_VISIBLE_DEVICES 指定当前训练使用哪张卡：

CUDA_VISIBLE_DEVICES=0 nnUNetv2_train 1 3d_fullres 0 --npz

训练输出会写到 nnUNet_results 下，官方文档给出的结构大致是：

nnUNet_results/
└── Dataset001_Liver/
    └── TRAINER__PLANS__CONFIGURATION/
        └── fold_0/
            ├── checkpoint_final.pth
            ├── checkpoint_best.pth
            ├── progress.png
            └── validation/

checkpoint_final.pth 是训练结束时的模型权重，checkpoint_best.pth 是验证表现较好的权重，progress.png 可以帮助你快速观察训练曲线。

5. 第四步：准备推理输入

推理输入必须遵守第 3 篇讲过的命名规则：文件后缀和 channel 编号要与训练数据集一致。

例如单通道输入：

input_images/
├── case_001_0000.nii.gz
└── case_002_0000.nii.gz

两通道输入：

input_images/
├── case_001_0000.nii.gz
├── case_001_0001.nii.gz
├── case_002_0000.nii.gz
└── case_002_0001.nii.gz

推理阶段不需要标签文件，因为模型要预测的就是标签。

6. 第五步：执行预测

官方推理命令是：

nnUNetv2_predict -i INPUT_FOLDER -o OUTPUT_FOLDER -d DATASET_NAME_OR_ID -c CONFIGURATION

例如：

nnUNetv2_predict \
  -i ./input_images \
  -o ./predictions \
  -d 1 \
  -c 3d_fullres

默认情况下，nnU-Net 推理会使用训练好的 5 个 fold 做 ensemble。如果你只训练了 all fold，并且只想用这个模型，官方文档给出的方式是使用 -f all：

nnUNetv2_predict \
  -i ./input_images \
  -o ./predictions \
  -d 1 \
  -c 3d_fullres \
  -f all

如果你只训练了 fold 0，而还没有完整训练 5 个 fold，建议先把这一步当作理解命令形态。正式项目中，应按官方推荐完成交叉验证和模型选择后，再使用最佳配置的推理命令。

7. 第一轮闭环命令速查

阶段	命令	主要输出
数据检查 + 计划 + 预处理	`nnUNetv2_plan_and_preprocess -d 1 --verify_dataset_integrity`	`nnUNet_preprocessed/Dataset001_...`
训练 fold 0	`nnUNetv2_train 1 3d_fullres 0 --npz`	`nnUNet_results/Dataset001_.../.../fold_0`
预测	`nnUNetv2_predict -i input_images -o predictions -d 1 -c 3d_fullres`	`predictions` 中的分割结果

8. 常见错误检查点

plan 阶段找不到数据集：检查数据集是否放在 nnUNet_raw 下，目录名是否是 Dataset001_Name。
完整性检查失败：优先检查 imagesTr 和 labelsTr 的 case id 是否对应，标签类别值是否都写进 dataset.json。
训练时找不到 configuration：检查 nnUNet_preprocessed 中实际生成了哪些配置，不要假设一定有 3d_fullres 或 cascade。
训练显存不足：先尝试其他已生成配置，或更换显存更大的 GPU。不要一开始就随意改 plans。
预测时报输入文件错误：检查推理输入是否带 _0000 等 channel 编号，文件后缀是否与训练数据一致。

9. 官方资料入口

本文主要参考：

本篇总结

nnU-Net v2 的第一个完整闭环是：先用 nnUNetv2_plan_and_preprocess 分析数据、生成计划并预处理；再用 nnUNetv2_train DATASET CONFIGURATION FOLD 训练指定配置和 fold；最后用 nnUNetv2_predict 对新图像进行预测。

这一篇的目标不是马上得到最终最佳模型，而是让你把从数据到预测的主流程跑通。后面我们会继续解释 fold、checkpoint、日志、模型选择和 postprocessing。