nnUNet保姆级使用教程！从情况配置到练习与推理（新手必看）

nnUNet 从零跑通：环境配置、安装、数据摆放到训练推理

接触医学图像分割，第一个项目多半就是拿 nnUNet 跑脑肿瘤数据集。nnUNet 最大的特点是自适应：给一个新数据集，它能根据数据属性自动调大多数超参数，几乎不用手调，在多个公开分割挑战里都拿到过 SOTA。下面按在 Ubuntu 服务器上的实际操作顺序走一遍，顺带记录几个高频坑。

一、nnUNet 是什么

nnU-Net 由德国癌症研究中心、海德堡大学及海德堡大学医院的研究者（Fabian Isensee、Jens Petersen、Andre Klein）提出，是一个能自适应任何新数据集的医学影像分割框架。它只依赖朴素的 U-Net 结构和稳健的训练方案，不做花活，靠"配置自动适配"取胜。官方建议环境：Python 3.9+ / PyTorch 1.13 / CUDA 11.x，具体以 README 为准。

二、配置虚拟环境

强烈建议在一个全新的 conda 虚拟环境里做，别装在基础环境。原因很简单：pip 装包会带一堆间接依赖，卸包时只卸你显式装的那个，留下的依赖越积越多，环境用久了几乎没法管理。

环境里需要备好 CUDA、cudnn、PyTorch 以及 nibabel（读 nii.gz 医学影像）、scikit-image 等。激活环境后再开始后面所有操作——忘了激活是新手最常见的低级失误，会跑到基础环境里去找包。

三、安装 nnUNet

两条路：

• 当作标准基线用、或直接拿预训练模型推理：pip install nnunet
• 当作集成框架、要改网络代码：克隆源码到本地

方式 B（改代码走这条路）

git clone https://github.com/MIC-DKFZ/nnUNet.git
cd nnUNet
pip install -e .        # 注意最后这个点不能省

三行命令分别做了什么：git clone 就是把 GitHub 上的代码克隆下来（跟手动下载文件是一回事，总共才 1 MB）；cd nnUNet 是进目录；pip install -e . 相当于执行仓库里的 setup.py，它干两件事——装上 nnUNet 依赖的 Python 包，以及往终端注册几个 nnUNet_ 前缀的命令（nnUNet_preprocess、nnUNet_train、nnUNet_predict 等），激活环境后任何目录都能直接跑。

源码目录里 setup.py 之外还有 nnUNet/ 主体代码、documentation/ 里的说明，以及 hiddenlayer 相关入口。

装 hiddenlayer（可选）

装上之后 nnUNet 能画出它自动生成的网络拓扑图，对理解"它到底选了什么配置"很有帮助：

pip install --upgrade git+https://github.com/FabianIsensee/hiddenlayer.git@more_plotted_details#egg=hiddenlayer

这是一整行，别拆开复制。装完重开终端让命令生效。

两个高频坑

• git clone 慢到 20 KB/s：GitHub 域名在国内被限速。换加速镜像或走代理，别死等。
• pip 太慢导致 pip install -e . 超时报错：配国内 pip 源（清华、阿里）或挂代理再装。

四、数据集目录结构（这一步最容易错）

nnUNet 对数据存放路径有严格要求，务必照抄下面这个结构，一级都别改：

1. 进入 nnUNet 文件夹，新建 nnUNetFrame
2. 在 nnUNetFrame 里新建 DATASET
3. 在 DATASET 里建三个目录：nnUNet_raw、nnUNet_preprocessed、nnUNet_trained_models
4. 进入 nnUNet_raw（第二个文件夹），建 nnUNet_cropped_data（放裁剪后的数据）和 nnUNet_raw_data（放原始数据）
5. 进入 nnUNet_raw_data，建 Task01_BrainTumour 这样的任务目录。任务名里的数字是 task id：公开竞赛任务用 01–09，自己改数据的话建议从 500 起步（上限 999），避免和预训练模型的 id 撞车
6. 把数据集放进任务目录，结构为 TaskXX_名字/imagesTr/、labelsTr/、以及 dataset.json。以 Task01 脑肿瘤为例，从 Medical Decathlon（http://medicaldecathlon.com/）下载对应数据集；Task02 是心脏分割，同理

dataset.json 里要写好 modality（各模态文件的后缀，如 CT 是 0000）、labels（标签值到名称的映射）、training（每个样本 images/labels 的相对路径）、test 等字段，写错会在 preprocessing 阶段报很难懂的错。

五、整体流程回顾

1. 预训练（可选）：nnUNet_predict 直接用已训练模型跑，适合只想出结果的场景。
2. 预处理：nnUNet_preprocess -t Task01_BrainTumour，这一步会做重采样、归一化、裁剪，并把数据集属性（体素间距、patch size 候选等）写进 dataset.json，供后续"自动配置"读取。
3. 训练：nnUNet_train，默认会跑 5 折交叉验证（-tr 指定训练器如 nnUNetTrainerV2，-ctl 控制有几个 GPU）。训练时长取决于数据量与卡数，脑肿瘤这一套通常几小时到一天。
4. 推理：nnUNet_predict -i 输入目录 -o 输出目录 -t Task01_BrainTumour，模型会自动选交叉验证里表现最好的那折。
5. 评估（有标签时）：用 Dice 系数等分割指标对比预测与金标准。

六、常见报错速查

• nnUNet_xxx: command not found：没激活 conda 环境，或 pip install -e . 那步没跑成功。
• Error: dataset.json not found：数据集路径不对，检查是不是套错了 nnUNetFrame/DATASET 那几层。
• preprocessing 报形状不匹配：图像与标签尺寸对不上，或 dataset.json 的 modality 写错。
• CUDA out of memory：降低 -bs（batch size）或 patch size；医学影像显存吃得很凶。
• 训练几轮就崩：检查 labels 里背景类是不是被排除了（nnUNet 默认不训练背景），以及标签值是否越界。

nnUNet 的"自动"体现在 preprocessing 之后它会自己选 U-Net 配置并写进 nnUNet_trained_models 的 planner 文件，想看它到底选了什么，读 plans*.pkl 解析一下就清楚了。v2 版本在流程上做了简化（不再强制手动指定 fold、数据路径统一到 nnUNet_results），新项目建议直接上 v2。

qidao123.com企服评测-应用市场 编辑提示