在Ubuntu 22.04上从零部署nnUNet_v2：一个医学影像研究生的踩坑与填坑实录
在Ubuntu 22.04上从零部署nnUNet_v2：一个医学影像研究生的踩坑与填坑实录
第一次在实验室的Ubuntu服务器上部署nnUNet_v2时，我盯着终端里红色的报错信息发了半小时呆。作为医学影像专业的研究生，本以为按官方文档一步步操作就能轻松跑通心脏CT分割任务，没想到从环境配置到训练预测处处是坑。这篇实录将分享我如何用三天时间从"Linux小白"到成功运行完整流程的实战经验，重点解决那些官方文档没写但实际必遇的问题。
1. 环境配置：那些官方没告诉你的细节
实验室新配的戴尔PowerEdge R740服务器预装了Ubuntu 22.04 LTS，当我用conda create -n nnUnet python=3.9创建环境时，第一个坑就出现了——默认的conda源下载速度只有50KB/s。换成国内镜像源后速度飙升：
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/ conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/ conda config --set show_channel_urls yes安装nnUNet_v2核心包时，直接pip install -e .会漏掉几个隐藏依赖。实测需要补充安装：
pip install hiddenlayer batchgenerators==0.25 torchio最坑爹的graphviz问题：当我想可视化网络结构时，报错"failed to execute PosixPath('dot')"。解决方案分三步：
- 用conda安装graphviz二进制包
- 将可执行文件路径加入环境变量
- 给当前用户添加执行权限
conda install -c conda-forge graphviz export PATH=$PATH:/home/your_username/anaconda3/envs/nnUnet/bin/ sudo chmod +x /home/your_username/anaconda3/envs/nnUnet/bin/dot2. 数据集准备的魔鬼细节
nnUNet对数据结构的严格程度超乎想象。我的心脏CT数据最初按DICOM标准存储，需要先转换为NIfTI格式。使用dcm2niix转换时要注意参数：
dcm2niix -z y -f %p_%s -o output_dir input_dicom_dir创建数据集目录树时，官方文档没说清楚的是：所有路径必须绝对路径且不能有中文或空格。我的目录结构最终如下：
nnUNetFrame/ └── DATASET/ ├── nnUNet_raw/ │ └── nnUNet_raw_data/ │ └── Task200_HeartCT/ │ ├── imagesTr/ # 训练图像 │ ├── labelsTr/ # 训练标签 │ ├── imagesTs/ # 测试图像 │ └── dataset.json ├── nnUNet_preprocessed/ └── nnUNet_results/dataset.json的标签定义必须与标注文件严格一致。我最初把右心室(RV)标签值写成2但标注文件里是1，导致训练时Dice系数始终为0。正确的标签定义示例：
{ "labels": { "background": 0, "LV": 1, // 左心室 "RV": 2, // 右心室 "LA": 3, // 左心房 "RA": 4 // 右心房 } }3. 数据预处理中的内存杀手
运行nnUNetv2_plan_and_preprocess时，我的128GB内存服务器居然被3D全分辨率数据撑爆了。通过分析源码发现几个优化点：
- 限制并行进程数：添加
-num_processes 4参数 - 跳过完整性验证：对已验证数据使用
--disable_verify - 分步预处理：先处理2D再处理3D
# 分步预处理示例 nnUNetv2_plan_and_preprocess -d 200 -c 2d --disable_verify nnUNetv2_plan_and_preprocess -d 200 -c 3d_fullres -num_processes 4注意：预处理会生成大量临时文件，确保
nnUNet_preprocessed目录所在分区有至少500GB空间
4. 训练过程的生存指南
当我在第五折验证时突然收到"CUDA out of memory"错误，才意识到默认批次大小对心脏CT太大了。通过修改nnUNetPlans.json中的配置：
{ "batch_size": { "2d": 12, "3d_fullres": 2, // 原值为4 "3d_lowres": 4 } }训练中断恢复的坑：直接用--c参数恢复会丢失之前的优化器状态。正确做法是：
- 备份中断的checkpoint
- 修改trainer代码保留optimizer.pt
- 使用
nnUNetv2_train 200 3d_fullres 0 --c
我用screen管理长时间训练任务，推荐配置：
screen -S nnUNet_train Ctrl+a → :hardstatus alwayslastline "%{= bw}%H %{=bw}%`"5. 预测与后处理的实战技巧
当测试集预测结果全是空白时，检查发现是dataset.json中的模态信息与图像不匹配。修正方法：
# 在数据转换后检查模态信息 import nibabel as nib img = nib.load("sample.nii.gz") print(img.header["dim"][0]) # 3表示3D, 4表示4D后处理时遇到ValueError: max() arg is an empty sequence错误，原因是预测结果与标签空间不一致。解决方案：
- 确保测试图像与训练图像相同空间分辨率
- 在预测命令中添加
-npp 1参数强制重采样
nnUNetv2_predict -i /input -o /output -d 200 -c 3d_fullres --save_probabilities6. 性能优化的隐藏开关
通过分析源码发现几个提升推理速度的参数：
| 参数 | 默认值 | 推荐值 | 作用 |
|---|---|---|---|
| --disable_tta | False | True | 关闭测试时增强 |
| --num_processes | 8 | 4 | 减少并行进程数 |
| --disable_overwrite | False | True | 禁用重复预测 |
对于心脏CT这类相对简单的结构，可以修改nnUNetPlans.json中的：
{ "num_pool_per_axis": [5, 5, 5], // 改为[4,4,4] "patch_size": [128,128,128] // 减小patch尺寸 }7. 可视化与结果分析
安装hiddenlayer后，可以通过修改nnunetv2/training/nnUNetTrainer/nnUNetTrainer.py添加网络结构可视化：
def on_train_start(self): import hiddenlayer as hl g = hl.build_graph(self.network, torch.zeros((1,1,64,64,64))) g.save("network_arch.pdf")评估结果时发现Dice系数波动大，通过分析发现是数据分布不均。解决方法：
- 在dataset.json中增加样本权重
- 修改损失函数为Dice+CrossEntropy
- 添加在线数据增强
# 在trainer中修改损失函数 self.loss = DC_and_CE_loss( {'batch_dice': True, 'do_bg': False}, {} )三天下来，从最初的满屏报错到最终跑通完整流程，最大的体会是：nnUNet虽然强大，但必须理解其设计哲学——所有自动化背后都有严格的约定。现在我的心脏CT分割Dice系数已达到0.92，这段踩坑经历或许比结果本身更有价值。