在Featurize服务器上从零部署nnU-Net v2：避开内存爆掉和路径坑的完整实操记录

医学影像分割领域，nnU-Net v2以其自动化配置和卓越性能成为研究热点。但在云服务器环境部署时，开发者常面临内存溢出、路径配置错误等独特挑战。本文将基于Featurize平台实战经验，详解从环境搭建到结果下载的全流程避坑指南。

1. 环境配置：精准匹配版本依赖

云服务器环境配置需要特别注意版本兼容性。Featurize平台默认提供的CUDA驱动版本为11.7，这直接决定了PyTorch的安装选择。

关键组件版本要求 ：

• Python 3.9（必须精确匹配）
• PyTorch 2.0+（与CUDA 11.7配套）
• nnU-Net v2源码（GitHub最新版）

# 创建隔离环境（避免污染系统Python）
conda create -n nnunet_v2 python=3.9 -y
conda activate nnunet_v2

# 安装PyTorch套件（注意cuda版本匹配）
conda install pytorch torchvision torchaudio pytorch-cuda=11.7 -c pytorch -c nvidia

验证GPU可用性：执行 torch.cuda.is_available() 应返回True。若为False，需检查驱动版本匹配情况。

常见问题排查表：

现象	可能原因	解决方案
ImportError	PyTorch版本不匹配	重新安装指定版本
CUDA不可用	驱动版本不符	更换PyTorch CUDA版本
内存不足	默认worker过多	调整预处理参数

2. 项目结构与数据准备

nnU-Net v2对文件结构有严格要求，错误的目录命名会导致后续流程中断。推荐在本地预先组织好以下结构再上传至服务器：

DATASET/
├── nnUNet_raw
│   └── Dataset101_Lung
│       ├── imagesTr  # 训练图像(需含0000后缀)
│       ├── labelsTr  # 训练标签
│       └── dataset.json  # 关键配置文件
├── nnUNet_preprocessed  # 自动生成
└── nnUNet_results  # 训练输出

dataset.json配置要点 ：

{
  "channel_names": {"0": "CT"},
  "labels": {
    "background": 0,
    "tumor": 1
  },
  "file_ending": ".nii.gz"
}

文件命名示例： case_0000.nii.gz （图像）与 case.nii.gz （标签）必须严格对应。模态编号0000需在json中声明。

3. 环境变量配置：云平台特殊处理

Featurize等云平台通常使用zsh替代bash，需要特别注意配置文件的加载方式：

# 使用vim编辑配置文件（若不存在会自动创建）
vim ~/.zshrc

# 插入以下内容（路径需替换为实际值）
export nnUNet_raw="/path/to/nnUNet_raw"
export nnUNet_preprocessed="/path/to/nnUNet_preprocessed" 
export nnUNet_results="/path/to/nnUNet_results"

# 保存退出后加载配置
source ~/.zshrc

路径验证命令：

echo $nnUNet_raw  # 应显示正确路径

4. 内存优化：预处理参数调整

云服务器内存限制是常见瓶颈。通过修改 nnunetv2/plan_and_preprocess_entrypoints.py 调整默认worker数量：

# 原配置（可能导致内存溢出）
default_np = {"2d":8, "3d_fullres":4, "3d_lowres":8}

# 修改为（根据可用内存调整）
default_np = {"2d":2, "3d_fullres":1, "3d_lowres":2}  

启动预处理时添加验证参数：

nnUNetv2_plan_and_preprocess -d 101 --verify_dataset_integrity

内存监控技巧：

• 使用 htop 观察内存占用
• 预处理过程中内存峰值不应超过总可用内存的90%
• 若仍崩溃，可尝试设置 export CUDA_VISIBLE_DEVICES="" 强制使用CPU

5. 训练与推理：云环境最佳实践

分阶段训练策略 ：

# 先快速验证流程（减少epoch）
nnUNetv2_train 101 2d 0 --epochs 50

# 正式训练（5折交叉验证）
for fold in {0..4}; do
  nnUNetv2_train 101 2d $fold
done

中断续训技巧 ：

# 添加--c参数继续中断的训练
nnUNetv2_train 101 2d 0 --c

批量预测命令 ：

nnUNetv2_predict -i input_dir -o output_dir -d 101 -c 2d --save_probabilities

6. 结果下载：Featurize平台操作

完成训练后，通过Web界面高效下载结果：

1. 在文件管理器中选择目标文件夹
2. 右键点击"Compress"生成zip包
3. 对压缩包右键选择"Download"
4. 若文件过大，建议使用 split 命令分卷压缩

# 分卷压缩示例（每卷500MB）
zip -r -s 500m results.zip nnUNet_results/

7. 性能调优进阶技巧

混合精度训练 ： 在 nnUNetTrainer.py 中启用：

self.enable_deep_supervision = True
self.use_mixed_precision = True

数据增强优化 ：

# 修改plans.json中的配置
"data_augmentation": {
  "rotation": {"x": (-15,15), "y": (-15,15)},
  "scaling": (0.7, 1.4)
}

内存监控脚本 ：

while true; do
  nvidia-smi --query-gpu=memory.used --format=csv >> gpu_mem.log
  free -m >> cpu_mem.log
  sleep 30
done

实际部署中发现，将预处理worker设为1虽然速度较慢，但在16GB内存的Featurize实例上稳定性最佳。训练过程中适时清理 nnUNet_preprocessed 中的临时文件可节省30%以上存储空间。