Ubuntu 22.04 + Python 3.10 环境，手把手教你搞定 nnUNetV2 和 MSD 数据集预处理
Ubuntu 22.04 + Python 3.10 环境下的 nnUNetV2 与 MSD 数据集全流程实战指南
在医学图像分割领域，nnUNetV2 以其出色的自适应能力和稳定的表现，成为众多研究者和开发者的首选工具。本文将带你从零开始，在 Ubuntu 22.04 系统和 Python 3.10 环境下，完成 nnUNetV2 的完整部署、MSD 数据集预处理以及模型训练全流程。不同于常规教程，我们会特别关注版本兼容性问题和那些容易被忽略的关键细节。
1. 环境准备与验证
1.1 系统基础环境检查
在开始之前，请确保你的 Ubuntu 22.04 系统已经完成基础配置：
# 检查系统版本 lsb_release -a # 检查 Python 版本 python3 --version如果系统尚未安装 Python 3.10，可以通过以下命令安装：
sudo apt update sudo apt install python3.10 python3.10-dev python3.10-venv注意：Ubuntu 22.04 默认可能自带 Python 3.10，建议先检查现有版本再决定是否需要重新安装。
1.2 虚拟环境创建与依赖管理
为避免系统 Python 环境被污染，强烈建议使用虚拟环境：
# 创建虚拟环境 python3.10 -m venv ~/nnunet_env # 激活环境 source ~/nnunet_env/bin/activate验证虚拟环境是否激活成功：
which python # 应显示 ~/nnunet_env/bin/python2. nnUNetV2 的安装与配置
2.1 源码获取的优化方案
官方推荐的git clone方式在国内可能速度较慢，我们可以采用以下替代方案：
直接下载 ZIP 包：
- 访问 nnUNet GitHub 仓库
- 点击 "Code" → "Download ZIP"
- 解压到
~/nnUNet目录
使用镜像加速（如果仍希望使用 git）：
git clone https://hub.fastgit.org/MIC-DKFZ/nnUNet.git
2.2 依赖安装与配置
进入 nnUNet 目录后，使用清华源加速安装：
cd ~/nnUNet pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -e .关键点检查：
- 确保命令末尾的
.包含在内 - 如果遇到权限问题，可添加
--user参数
安装完成后，验证关键依赖版本：
pip show torch # 应显示 torch >= 2.0.03. 文件系统结构与环境变量配置
3.1 创建必要的目录结构
nnUNetV2 需要特定的目录结构来管理数据：
mkdir -p ~/nnUNetFrame/DATASET/{nnUNet_raw,nnUNet_preprocessed,nnUNet_results}目录用途说明：
| 目录名称 | 用途 |
|---|---|
| nnUNet_raw | 存储原始数据集和转换后的标准格式数据 |
| nnUNet_preprocessed | 存储预处理后的数据 |
| nnUNet_results | 存储训练结果和模型 |
3.2 环境变量配置的可靠方法
编辑~/.bashrc文件：
nano ~/.bashrc在文件末尾添加（替换为你的实际路径）：
export nnUNet_raw="~/nnUNetFrame/DATASET/nnUNet_raw" export nnUNet_preprocessed="~/nnUNetFrame/DATASET/nnUNet_preprocessed" export nnUNet_results="~/nnUNetFrame/DATASET/nnUNet_results"保存后，应用更改：
source ~/.bashrc常见问题排查：
- 如果更改未生效，尝试完全关闭并重新打开终端
- 使用
echo $nnUNet_raw验证变量是否设置成功 - 确保路径中不包含特殊字符或空格
4. MSD 数据集处理全流程
4.1 数据集获取与准备
以 MSD (Medical Segmentation Decathlon) 中的心脏数据集为例：
- 从官方链接下载数据集
- 解压到
~/msd_data/Task02_Heart目录
目录结构应类似于：
Task02_Heart/ ├── imagesTr ├── imagesTs ├── labelsTr └── labelsTs4.2 数据集格式转换
nnUNetV2 提供了专用转换工具：
nnUNetv2_convert_MSD_dataset -i ~/msd_data/Task02_Heart -overwrite_id 2转换成功后，检查nnUNet_raw目录：
nnUNet_raw/ └── Dataset002_Heart ├── dataset.json ├── imagesTr ├── imagesTs └── labelsTr关键验证点：
- 确认每个图像文件有对应的
_0000后缀（如la_003_0000.nii.gz） - 标签文件不应有
_0000后缀 dataset.json文件应包含正确的元数据
4.3 数据预处理与规划
运行预处理管道：
nnUNetv2_plan_and_preprocess -d 2 --verify_dataset_integrity这个过程可能耗时较长，取决于你的硬件配置。预处理完成后，检查nnUNet_preprocessed目录：
nnUNet_preprocessed/ └── Dataset002_Heart ├── gt_segmentations ├── nnUNetPlans.json └── ...提示：预处理阶段会生成多种分辨率的数据，这是 nnUNet 自适应策略的一部分，不要手动修改这些文件。
5. 模型训练与验证
5.1 训练配置选择
nnUNetV2 提供多种训练配置：
| 配置名称 | 适用场景 | 显存需求 |
|---|---|---|
| 2d | 适用于切片间间距较大的数据 | 较低 |
| 3d_fullres | 高分辨率三维数据 | 较高 |
| 3d_lowres | 大体积数据的第一阶段训练 | 中等 |
| 3d_cascade_lowres | 级联模型的第二阶段 | 高 |
5.2 启动训练任务
以 2D 配置和 5 折交叉验证为例：
nnUNetv2_train 2 2d 0参数说明：
2：数据集 ID（对应 Dataset002_Heart）2d：训练配置0：交叉验证的折数（0-4）
训练过程中会输出如下关键信息：
- 当前 epoch 的损失值
- 验证集上的 Dice 分数
- 学习率变化情况
5.3 训练监控与优化
使用 TensorBoard 监控训练过程：
tensorboard --logdir ~/nnUNetFrame/DATASET/nnUNet_results/Dataset002_Heart/nnUNetTrainer__nnUNetPlans__2d在浏览器中访问localhost:6006查看训练曲线。
性能优化技巧：
- 如果显存不足，尝试减小
patch_size（修改nnUNetPlans.json） - 使用混合精度训练添加
--amp参数 - 多 GPU 训练添加
-device cuda:0,1（根据实际 GPU 数量调整）
6. 模型推理与应用
6.1 单样本预测
对测试集中的样本进行预测：
nnUNetv2_predict -i ~/msd_data/Task02_Heart/imagesTs -o ~/predictions -d 2 -f 0参数说明：
-i：输入图像目录-o：输出目录-d：数据集 ID-f：使用的交叉验证折数（0-4）
6.2 结果分析与可视化
安装必要的可视化工具：
pip install -U nibabel matplotlib使用以下 Python 脚本查看预测结果：
import nibabel as nib import matplotlib.pyplot as plt # 加载预测结果 pred = nib.load("~/predictions/la_003.nii.gz").get_fdata() # 可视化中间切片 plt.imshow(pred[:,:,pred.shape[2]//2], cmap='jet') plt.colorbar() plt.show()7. 高级技巧与问题排查
7.1 自定义数据集的适配
对于非 MSD 数据集，需要确保：
文件命名符合规范：
- 图像：
case_identifier_XXXX.nii.gz（XXXX 为模态编号） - 标签：
case_identifier.nii.gz
- 图像：
dataset.json必须包含：{ "channel_names": {"0": "CT"}, "labels": { "background": 0, "tumor": 1 } }
7.2 常见错误解决方案
| 错误类型 | 可能原因 | 解决方案 |
|---|---|---|
| 环境变量未识别 | .bashrc 未正确加载 | 使用绝对路径 source |
| 数据集验证失败 | 文件命名不规范 | 检查_0000后缀 |
| CUDA 内存不足 | patch_size 过大 | 修改 plans 文件 |
| 训练中断 | 磁盘空间不足 | 清理预处理缓存 |
7.3 性能优化策略
IO 加速：
export nnUNet_n_proc_DA=8 # 数据增强并行进程数混合精度训练：
nnUNetv2_train 2 2d 0 --amp缓存优化：
export nnUNet_preprocessed="/dev/shm/nnUNet_preprocessed" # 使用内存盘
在实际项目中，我发现将预处理目录放在内存盘上可以显著提升数据加载速度，特别是在使用 3D 全分辨率配置时。不过要注意内存容量限制，对于大型数据集可能需要调整nnUNet_n_proc_DA参数来平衡内存使用。