nnU-Net 入门实操教程

原创

buzzfrog

修改于 2025-10-14 21:36:46

361

1. nnU-Net 简介

1.1 什么是 nnU-Net？

nnU-Net (no-new-UNet) 是一个用于医学图像分割的自适应深度学习框架，由德国癌症研究中心（DKFZ）开发。它最大的特点是自动配置，能够根据不同的数据集自动确定最优的网络架构、训练策略和数据增强方案。它对应的论文为：2020年12月《nnU-Net: a self-configuring method for deep learning-based biomedical image segmentation》和2024年7月《nnU-Net Revisited: A Call for Rigorous Validation in 3D Medical Image Segmentation》

1.2 核心优势

全自动配置：无需手动调参，自动适应不同数据集
性能优异：在多个医学图像分割挑战赛中获得第一名
标准化流程：提供完整的数据处理、训练、推理pipeline
开箱即用：遵循标准数据格式，即可快速上手

1.3 应用场景

医学图像分割（CT、MRI、超声等）
器官分割（肝脏、肺、脑组织等）
病灶检测（肿瘤、病变区域等）
3D 和 2D 图像分割任务

1.4 工作流程

原始数据 → 数据格式转换 → 预处理 → 训练 → 推理 → 结果可视化

2. 环境安装

2.1 系统要求

操作系统：Linux、macOS 或 Windows
Python：3.9 或更高版本
GPU：推荐使用 NVIDIA GPU（至少 8GB 显存，缺省参数实际会达到17GB）
存储空间：根据数据集大小，建议至少 50GB 可用空间

2.2 安装步骤

步骤 1：创建虚拟环境（推荐）

# 使用 conda
conda create -n nnunet python=3.10
conda activate nnunet

# 或使用 venv
python3 -m venv nnunet_env
source nnunet_env/bin/activate  # Linux/macOS
# nnunet_env\Scripts\activate  # Windows

步骤 2：安装 PyTorch

根据您的系统和 CUDA 版本安装 PyTorch：

# CUDA 11.8 (推荐)
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# CUDA 12.1
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# CPU 版本（仅用于测试，不推荐训练）
pip3 install torch torchvision torchaudio

# macOS (支持 MPS)
pip3 install torch torchvision torchaudio

步骤 3：安装 nnUNet

pip3 install nnunetv2

步骤 4：安装可视化依赖

pip3 install nibabel matplotlib

步骤 5：验证安装

python3 -c "import nnunetv2; print('nnU-Net v2 安装成功！')"

2.3 环境变量设置

nnU-Net 需要三个环境变量来指定数据存储路径：

# 创建项目目录
mkdir -p ~/nnUNet_workspace
cd ~/nnUNet_workspace

# 设置环境变量
export nnUNet_raw="$PWD/nnUNet_raw"
export nnUNet_preprocessed="$PWD/nnUNet_preprocessed"
export nnUNet_results="$PWD/nnUNet_results"

# 建议添加到 ~/.bashrc 或 ~/.zshrc，使其永久生效
echo 'export nnUNet_raw="$HOME/nnUNet_workspace/nnUNet_raw"' >> ~/.bashrc
echo 'export nnUNet_preprocessed="$HOME/nnUNet_workspace/nnUNet_preprocessed"' >> ~/.bashrc
echo 'export nnUNet_results="$HOME/nnUNet_workspace/nnUNet_results"' >> ~/.bashrc
source ~/.bashrc

目录说明：

nnUNet_raw：存放原始数据集
nnUNet_preprocessed：存放预处理后的数据
nnUNet_results：存放训练结果和模型权重

3. 数据集准备

3.1 示例数据集：Task04_Hippocampus

本教程使用 Hippocampus（海马体分割） 数据集作为示例。

数据集信息

名称：Task04_Hippocampus
来源：Medical Segmentation Decathlon
提供方：Vanderbilt University Medical Center
许可证：CC-BY-SA 4.0
模态：MRI
任务：海马体前部（Anterior）和后部（Posterior）分割
训练样本：260 例
测试样本：130 例

标签说明

0：背景（background）
1：海马体前部（Anterior）
2：海马体后部（Posterior）

3.2 数据集下载

方法 1：官方下载地址

访问 Medical Segmentation Decathlon 官网：

https://drive.google.com/drive/folders/1HqEgzS8BV2c7xYNrZdEAnrHk7osJJ--2

在其中找到 Task04_Hippocampus.tar 文件并下载。

方法 2：命令行下载（需要 gdown）

# 安装 gdown
pip3 install gdown

# 下载数据集（文件ID可能会变化，请从官网获取最新链接）
gdown https://drive.google.com/uc?id=1RzPB1_bqzQhlWvU-YGvZzhx2omcDh38C

方法 3：命令行下载（需要 wget）

# 安装wget
sudo apt install wget

# 下载数据集（链接未来可能会失效）
wget https://msd-for-monai.s3-us-west-2.amazonaws.com/Task04_Hippocampus.tar -o Task04_Hippocampus.tar

3.3 数据集目录结构

下载后，将 Task04_Hippocampus.tar 解压到 nnUNet_raw 目录：

cd $nnUNet_raw
tar -xvf Task04_Hippocampus.tar

解压后的目录结构：

$nnUNet_raw/Task04_Hippocampus/
├── dataset.json          # 数据集元数据
├── imagesTr/             # 训练图像 (260个 .nii.gz 文件)
│   ├── hippocampus_001.nii.gz
│   ├── hippocampus_002.nii.gz
│   └── ...
├── labelsTr/             # 训练标签 (260个 .nii.gz 文件)
│   ├── hippocampus_001.nii.gz
│   ├── hippocampus_002.nii.gz
│   └── ...
└── imagesTs/             # 测试图像 (130个 .nii.gz 文件)
    ├── hippocampus_267.nii.gz
    └── ...

3.4 数据格式转换（旧版本 → nnUNet v2）

如果数据集是旧版 nnUNet 格式（如 Task04_Hippocampus），需要转换为 v2 格式：

# 重命名为标准格式（Task04 → Task004）
mv $nnUNet_raw/Task04_Hippocampus $nnUNet_raw/Task004_Hippocampus

# 使用转换工具
nnUNetv2_convert_old_nnUNet_dataset \
    $nnUNet_raw/Task004_Hippocampus \
    Dataset004_Hippocampus

转换后会生成新的数据集目录：

$nnUNet_raw/Dataset004_Hippocampus/
├── dataset.json
├── imagesTr/
│   ├── hippocampus_001_0000.nii.gz  # 注意：文件名添加了 _0000 后缀
│   └── ...
├── labelsTr/
│   ├── hippocampus_001.nii.gz
│   └── ...
└── imagesTs/
    ├── hippocampus_267_0000.nii.gz
    └── ...

说明：

_0000 后缀表示第 0 个通道（模态），多模态数据会有 _0001, _0002 等
dataset.json 包含数据集的元信息（标签、模态、文件列表等）

4. 数据预处理

4.1 预处理步骤

nnU-Net 会自动执行以下预处理：

数据分析：分析图像尺寸、间距、强度分布
重采样：统一图像间距（voxel spacing）
归一化：标准化图像强度值
裁剪：去除背景区域
生成训练计划：确定网络架构、batch size、patch size 等

4.2 执行预处理

nnUNetv2_plan_and_preprocess -d 4 --verify_dataset_integrity

参数说明：

-d 4：数据集 ID（对应 Dataset004_Hippocampus）
--verify_dataset_integrity：验证数据集完整性（检查文件是否缺失、标签是否正确等）

4.3 预处理输出

预处理完成后，会在 $nnUNet_preprocessed/Dataset004_Hippocampus 生成以下文件：

$nnUNet_preprocessed/Dataset004_Hippocampus/
├── dataset_fingerprint.json      # 数据集指纹（统计信息）
├── dataset.json                  # 数据集元数据
├── nnUNetPlans.json              # 训练计划（网络配置）
├── splits_final.json             # 交叉验证划分
├── gt_segmentations/             # Ground truth 分割（用于验证）
├── nnUNetPlans_2d/               # 2D 预处理数据
└── nnUNetPlans_3d_fullres/       # 3D 全分辨率预处理数据

4.4 查看训练计划

cat $nnUNet_preprocessed/Dataset004_Hippocampus/nnUNetPlans.json

该文件包含：

网络配置：UNet 编码器/解码器层数、卷积核大小
数据配置：patch size、batch size、数据增强策略
训练配置：学习率、优化器、训练轮数

5. 模型训练

5.1 训练命令

nnUNet 支持多种训练配置：

5.1.1 2D 网络训练

nnUNetv2_train 4 2d 0

参数说明：

4：数据集 ID
2d：网络配置（逐切片训练）
0：交叉验证 fold（0-4，共5折）

5.1.2 3D 全分辨率网络训练

nnUNetv2_train 4 3d_fullres 0

5.1.3 3D 低分辨率网络训练

nnUNetv2_train 4 3d_lowres 0

5.1.4 3D 级联网络训练

# 第一阶段：低分辨率
nnUNetv2_train 4 3d_lowres 0

# 第二阶段：级联
nnUNetv2_train 4 3d_cascade_fullres 0

5.2 GPU/CPU 设备选择

使用特定 GPU

CUDA_VISIBLE_DEVICES=0 nnUNetv2_train 4 2d 0

使用多 GPU

CUDA_VISIBLE_DEVICES=0,1 nnUNetv2_train 4 2d 0

使用 macOS MPS（Apple Silicon）

nnUNetv2_train -device mps 4 2d 0

使用 CPU（不推荐，速度慢）

nnUNetv2_train -device cpu 4 2d 0

5.3 训练过程监控

训练日志会保存在：

$nnUNet_results/Dataset004_Hippocampus/nnUNetTrainer__nnUNetPlans__2d/fold_0/
├── training_log.txt         # 训练日志
├── checkpoint_best.pth      # 最佳模型权重
├── checkpoint_final.pth     # 最终模型权重
├── progress.png             # 训练曲线图
└── validation_raw/          # 验证集预测结果

实时查看训练日志：

tail -f $nnUNet_results/Dataset004_Hippocampus/nnUNetTrainer__nnUNetPlans__2d/fold_0/training_log.txt

5.4 训练时间估计

2D 网络：GTX 1080 Ti 约 4-6 小时
3D 全分辨率：GTX 1080 Ti 约 12-24 小时
Apple M1/M2 (MPS)：约为 GPU 训练时间的 2-3 倍

5.5 训练所有交叉验证折

为了获得最佳性能，建议训练所有 5 折：

# 自动训练所有折
nnUNetv2_train 4 2d all

# 或手动训练每一折
for fold in 0 1 2 3 4; do
    nnUNetv2_train 4 2d $fold
done

6. 模型推理

6.1 推理命令

使用训练好的模型对新数据进行预测：

nnUNetv2_predict \
    -i $nnUNet_raw/Dataset004_Hippocampus/imagesTs \
    -o $nnUNet_results/Dataset004_Hippocampus/predictions \
    -d 4 \
    -c 2d \
    -f 0

参数说明：

-i：输入图像目录
-o：输出分割结果目录
-d：数据集 ID
-c：配置（2d、3d_fullres等）
-f：使用哪个 fold 的模型（可指定多个：-f 0 1 2 3 4）

6.2 使用所有折的集成预测

nnUNetv2_predict \
    -i $nnUNet_raw/Dataset004_Hippocampus/imagesTs \
    -o $nnUNet_results/Dataset004_Hippocampus/predictions_ensemble \
    -d 4 \
    -c 2d \
    -f 0 1 2 3 4  # 使用所有5折进行集成

集成预测通常比单折预测效果更好。

6.3 调整推理设置

禁用测试时增强（TTA）

nnUNetv2_predict -i INPUT -o OUTPUT -d 4 -c 2d -f 0 --disable_tta

保存概率图

nnUNetv2_predict -i INPUT -o OUTPUT -d 4 -c 2d -f 0 --save_probabilities

7. 结果可视化

7.1 使用提供的可视化脚本

项目中提供了三个可视化脚本：

7.1.1 快速查看（三视图）

python3 show_nii.py $nnUNet_raw/Dataset004_Hippocampus/imagesTr/hippocampus_001_0000.nii.gz

显示轴向、矢状、冠状三个切面的中间切片。

7.1.2 交互式浏览

python3 show_nii.py $nnUNet_raw/Dataset004_Hippocampus/imagesTr/hippocampus_001_0000.nii.gz -i --view axial

使用滑块逐层浏览切片。

视图选项：

axial：轴向切片（水平切面）
sagittal：矢状切片（侧面切面）
coronal：冠状切片（正面切面）

7.1.3 3D 表面渲染

python3 show_nii_3d.py nnUNet_raw/Dataset004_Hippocampus/labelsTr/hippocampus_001.nii.gz --mode surface

7.1.4 散点图模式

python3 show_nii_3d.py nnUNet_raw/Dataset004_Hippocampus/labelsTr/hippocampus_001.nii.gz --mode scatter

7.1.5 交互式 3D

python3 show_nii_3d_interactive.py nnUNet_raw/Dataset004_Hippocampus/labelsTr/hippocampus_001.nii.gz

可以使用鼠标旋转

8. 常见问题

8.1 环境和安装问题

Q1: 安装 nnUNetv2 时报错？

A: 确保先安装 PyTorch，再安装 nnUNetv2：

pip3 install torch torchvision torchaudio
pip3 install nnunetv2

Q2: 找不到环境变量？

A: 每次使用前确保设置了三个环境变量：

export nnUNet_raw="/path/to/nnUNet_raw"
export nnUNet_preprocessed="/path/to/nnUNet_preprocessed"
export nnUNet_results="/path/to/nnUNet_results"

或在脚本中指定：

#!/bin/bash
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
export nnUNet_raw="${SCRIPT_DIR}/nnUNet_raw"
export nnUNet_preprocessed="${SCRIPT_DIR}/nnUNet_preprocessed"
export nnUNet_results="${SCRIPT_DIR}/nnUNet_results"

# 后续命令...

8.2 数据集问题

Q3: dataset.json 格式不正确？

A: nnUNet v2 的 dataset.json 格式示例：

{
    "name": "Hippocampus",
    "description": "Left and right hippocampus segmentation",
    "reference": "Vanderbilt University Medical Center",
    "licence": "CC-BY-SA 4.0",
    "release": "1.0 04/05/2018",
    "channel_names": {
        "0": "MRI"
    },
    "labels": {
        "background": 0,
        "Anterior": 1,
        "Posterior": 2
    },
    "numTraining": 260,
    "file_ending": ".nii.gz"
}

Q4: 图像和标签不匹配？

A: 检查文件命名：

图像：case_001_0000.nii.gz（必须有 _0000 后缀）
标签：case_001.nii.gz（无后缀）

8.3 训练问题

Q5: 显存不足（CUDA out of memory）？

A: 尝试以下方法：

减小 batch size（修改 nnUNetPlans.json）
使用 2D 网络而非 3D
使用更小的 GPU（nnUNet 会自动调整）
启用混合精度训练（默认启用）

Q6: 训练速度很慢？

确保使用 GPU 而非 CPU
检查数据是否在 SSD 上（而非机械硬盘）
关闭不必要的后台程序

Q7: 如何恢复中断的训练？

A: nnUNet 会自动保存 checkpoint，直接重新运行相同的命令即可恢复：

nnUNetv2_train 4 2d 0  # 会自动从 checkpoint 恢复

8.4 推理和结果问题

Q8: 推理结果全是背景？

A: 检查：

输入图像格式是否正确（需要 _0000.nii.gz 后缀）
是否使用了正确的模型和配置
图像强度范围是否异常

Q9: 如何评估模型性能？

A: 使用 nnUNet 内置评估工具：

nnUNetv2_evaluate_folder \
    $nnUNet_results/Dataset004_Hippocampus/predictions \
    $nnUNet_raw/Dataset004_Hippocampus/labelsTs \
    -l 1 2  # 评估标签 1 和 2

会输出 Dice、IoU、95% Hausdorff 距离等指标。

8.5 自定义数据集

Q10: 如何准备自己的数据集？

A: 按照以下步骤：

mkdir -p $nnUNet_raw/Dataset999_MyDataset/{imagesTr,labelsTr,imagesTs}

准备图像和标签：
- 图像命名：case_001_0000.nii.gz
- 标签命名：case_001.nii.gz
- 确保图像和标签尺寸一致
创建 dataset.json：

{
    "name": "MyDataset",
    "description": "My custom dataset",
    "channel_names": {
        "0": "CT"
    },
    "labels": {
        "background": 0,
        "target": 1
    },
    "numTraining": 100,
    "file_ending": ".nii.gz"
}

运行预处理和训练：

nnUNetv2_plan_and_preprocess -d 999 --verify_dataset_integrity
nnUNetv2_train 999 2d 0

总结

本教程涵盖了 nnUNet 的基础使用流程：

✅ 环境安装和配置
✅ 数据集下载和准备
✅ 数据预处理
✅ 模型训练（2D/3D）
✅ 模型推理
✅ 结果可视化

进阶学习资源

官方文档：https://github.com/MIC-DKFZ/nnUNet
论文原文：Isensee et al., Nature Methods 2021
视频教程：YouTube 搜索 "nnUNet tutorial"
社区讨论：GitHub Issues

完整训练脚本示例

将以下内容保存为 train.sh：

#!/bin/bash

# 获取脚本所在目录
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"

# 设置环境变量
export nnUNet_raw="${SCRIPT_DIR}/nnUNet_raw"
export nnUNet_preprocessed="${SCRIPT_DIR}/nnUNet_preprocessed"
export nnUNet_results="${SCRIPT_DIR}/nnUNet_results"

# 1. 解压数据集
echo "==> 解压数据集..."
tar -xvf ./nnUNet_raw/Task04_Hippocampus.tar -C ./nnUNet_raw

# 2. 重命名数据集
echo "==> 重命名数据集..."
mv ./nnUNet_raw/Task04_Hippocampus ./nnUNet_raw/Task004_Hippocampus

# 3. 删除旧的 Dataset004（如果存在）
rm -rf ${nnUNet_raw}/Dataset004_Hippocampus

# 4. 转换为 nnUNet v2 格式
echo "==> 转换数据集格式..."
nnUNetv2_convert_old_nnUNet_dataset \
    ./nnUNet_raw/Task004_Hippocampus \
    Dataset004_Hippocampus

# 5. 数据预处理
echo "==> 数据预处理..."
nnUNetv2_plan_and_preprocess -d 4 --verify_dataset_integrity

# 6. 训练 2D 模型
echo "==> 开始训练 2D 模型..."
nnUNetv2_train -device mps 4 2d 0

# 7. （可选）训练 3D 模型
# echo "==> 开始训练 3D 模型..."
# nnUNetv2_train -device mps 4 3d_fullres 0

echo "==> 训练完成！"

运行脚本：

chmod +x train.sh
./train.sh

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

智慧医学影像

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

智慧医学影像

#nnU-Net

#nnunet

登录后参与评论

0 条评论

热度