nnU-Net Residual Encoder Presets（ResEnc M/L/XL）完整使用指南：从实验规划、训练到多 GPU 扩展

人工智能深度学习计算机视觉医疗健康【免费下载链接】nnUNet项目地址https://gitcode.com/gh_mirrors/nn/nnUNet点击查看免费下载本指南以 nnU-Net 官方文档 documentation/resenc_presets.md 为主体系统讲解 nnU-Net v2 中基于残差编码器 U-NetResidual Encoder UNet的三大预设配置nnUNetPlannerResEncM/L/XL它们的定位与显存/算力预算、在大规模数据集上的性能表现、完整的命令行接入方式规划、预处理、训练、推理、如何把预设扩展到任意显存如 80GB乃至多 GPU以及论文级别的正确基准评测姿势。读完本文你将能直接上手用 ResEnc 预设跑通一个数据集的完整流程并能通过编辑 plans JSON 安全地自定义网络配置。背景一直存在却容易被忽视的 Residual Encoder UNet残差编码器 U-Net 早在 nnU-Net 团队参加 KiTS2019 挑战赛时就已被 nnU-Net 支持但长期以来没有作为一等公民被推广。随着nnUNetResEncUNet系列预设即文档所称的 nnUNetResEncUNet presets的推出这一状况得以改变尤其是在 KiTS2023、AMOS2022 这类大样本数据集上残差编码器结构能够带来明显的分割性能提升。需要说明的是使用这些预设时官方要求引用其论文详见文末参考文献 [1]Isensee, F., Wald, T., Ulrich, C., Baumgartner, M., Roy, S., Maier-Hein, K., Jaeger, P. (2024). nnU-Net Revisited: A Call for Rigorous Validation in 3D Medical Image Segmentation.从源码结构看残差编码器网络本体来自dynamic_network_architectures库中的ResidualEncoderUNetresidual_encoder_unet_planners.py 顶部导入它与标准PlainConvUNet默认实验规划器使用的网络类见 default_experiment_planner.py最大的区别在于编码器各 stage 内部采用残差块堆叠UNet_blocks_per_stage_encoder为(1, 3, 4, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6)而解码器每 stage 仅 1 个卷积块(1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1)相比默认规划器的(2, 2, 2, ...)编码器结构残差编码器在相同显存预算下能容纳更深、更强的特征提取。三个预设按显存与算力预算选型nnU-Net 提供三个开箱即用的预设每个针对不同的 GPU 显存与训练时长预算预设适用 GPU / 显存预算A100 上的训练时长nnU-Net ResEnc M与标准 UNet 配置相近的 GPU 预算最适合 9–11GB 显存的 GPU如 RTX 2080 Ti~12 小时nnU-Net ResEnc L需要 24GB 显存的 GPU如 RTX 4090、Titan RTX、Quadro 6000~35 小时nnU-Net ResEnc XL需要 40GB 显存的 GPU如 A100 40GB、RTX 6000 Ada Generation~66 小时官方建议明确推荐将 nnU-Net ResEnc L 作为新的默认 nnU-Net 配置。它只比标准配置多消耗约 1.5GB 显存训练时 9.1GB vs 7.7GB见下节基准表却在多个数据集上获得一致的性能提升。在六个公开数据集上的 5 折交叉验证结果Dice下表来自官方论文参考文献 [1]报告的是各数据集上的 5 折交叉验证 Dice 分数所有模型均从零训练。表中同时对比了多种 3D 医学分割架构用于说明 ResEnc 预设的定位方法BTCV (n30)ACDC (n200)LiTS (n131)BraTS (n1251)KiTS (n489)AMOS (n360)VRAM (GB)RT (h)Arch.nnUnnU-Net (org.) [1]83.0891.5480.0991.2486.0488.647.709CNNYesnnU-Net ResEnc M83.3191.9980.7591.2686.7988.779.1012CNNYesnnU-Net ResEnc L83.3591.6981.6091.1388.1789.4122.7035CNNYesnnU-Net ResEnc XL83.2891.4881.1991.1888.6789.6836.6066CNNYesMedNeXt L k3 [2]84.7092.6582.1491.3588.2589.6217.3068CNNYesMedNeXt L k5 [2]85.0492.6282.3491.5087.7489.7318.00233CNNYesSTU-Net S [3]82.9291.0478.5090.5584.9388.085.2010CNNYesSTU-Net B [3]83.0591.3079.1990.8586.3288.468.8015CNNYesSTU-Net L [3]83.3691.3180.3191.2685.8489.3426.5051CNNYesSwinUNETR [4]78.8991.2976.5090.6881.2783.8113.1015TFYesSwinUNETRV2 [5]80.8592.0177.8590.7484.1486.2413.4015TFYesnnFormer [6]80.8692.4077.4090.2275.8581.555.708TFYesCoTr [7]81.9590.5679.1090.7384.5988.028.2018TFYesNo-Mamba Base83.6991.8980.5791.2685.9889.0412.024CNNYesU-Mamba Bot [8]83.5191.7980.4091.2686.2289.1312.4024MamYesU-Mamba Enc [8]82.4191.2280.2790.9186.3488.3824.9047MamYesA3DS SegResNet [9,11]80.6990.6979.2890.7981.1187.2720.0022CNNNoA3DS DiNTS [10, 11]78.1882.9769.0587.7565.2882.3529.2016CNNNoA3DS SwinUNETR [4, 11]76.5482.6868.5989.9052.8285.0534.509TFNo表注RT训练运行时间在 1× Nvidia A100 PCIe 40GB 上测得。VRAM训练期间 GPU 显存占用nvidia-smi 报告。Arch.CNN 卷积神经网络TF TransformerMam Mamba。nnU该架构是否已集成并由官方或原作者在 nnU-Net 框架下测试。阅读这张表可以得到几个关键结论ResEnc 系列在 LiTS、KiTS、AMOS 等大体量数据集上的提升最为显著如 ResEnc L 在 KiTS 上比标准 nnU-Net 高 2.13 个 Dice 点且三档预设的显存/时长增长是可控的对比同量级的 Transformer/Mamba 架构ResEnc 系列以明显更低的训练成本取得了有竞争力的分数。如何使用新预设两条命令接入完整流程新预设的使用方式非常统一(M/L/XL) 三选一只需要在实验规划阶段和后续所有命令中分别指定规划器与 plans 文件即可。第 1 步规划与预处理在运行实验规划与预处理时通过-pl指定规划器类nnUNetv2_plan_and_preprocess -d DATASET -pl nnUNetPlannerResEncM # 或 nnUNetv2_plan_and_preprocess -d DATASET -pl nnUNetPlannerResEncL # 或 nnUNetv2_plan_and_preprocess -d DATASET -pl nnUNetPlannerResEncXL关键细节这些规划器与标准 2d 和 3d_fullres 配置共用同一份预处理数据目录因为预处理产出的数据完全相同网络拓扑与数据无关。唯一的例外是3d_lowres它的预处理数据会存放到单独目录从而保证所有配置标准 nnUNetPlans 与 ResEnc 系列 plans可以共存互不干扰。这一点在源码中有明确实现ResEncUNetPlanner.generate_data_identifierresidual_encoder_unet_planners.py对2d和3d_fullres配置直接返回nnUNetPlans_2d/nnUNetPlans_3d_fullres与默认规划器一致实现数据复用而其余配置则返回plans_identifier _ configuration_name例如nnUNetResEncUNetMPlans_3d_lowres因此低分辨率数据天然被隔离。如果你只打算跑 3d_fullres 和/或 2d且这些配置的预处理数据已经生成过可以跳过重复预处理直接单独运行规划命令nnUNetv2_plan_experiment -d DATASET -pl nnUNetPlannerResEnc(M/L/XL)该命令只做指纹提取与实验规划plan_and_preprocess_entrypoints.py 中-pl参数默认值为ExperimentPlanner这里替换为 ResEnc 规划器即可会为你节省大量预处理时间。第 2 步训练、推理等后续命令统一指定 plans规划完成之后在nnUNetv2_train、nnUNetv2_predict等所有命令中通过-p指定对应的 plans 标识。nnU-Net 所有命令的接口保持一致# 训练以 M 预设为例-p 指定 plans 文件标识 nnUNetv2_train DATASET 3d_fullres FOLD -p nnUNetResEncUNetMPlans # 推理 nnUNetv2_predict -i INPUT_FOLDER -o OUTPUT_FOLDER -d DATASET -c 3d_fullres \ -p nnUNetResEncUNetMPlans三个预设对应的规划器类名与 plans 标识对照如下均可在 residual_encoder_unet_planners.py 中找到预设-pl规划器类名-pplans 标识默认显存目标ResEnc MnnUNetPlannerResEncMnnUNetResEncUNetMPlans8 GBResEnc LnnUNetPlannerResEncLnnUNetResEncUNetLPlans24 GBResEnc XLnnUNetPlannerResEncXLnnUNetResEncUNetXLPlans40 GB从命令行解析源码看nnUNetv2_train与nnUNetv2_predict的-p参数默认值均为nnUNetPlans见 run_training.py 与 predict_from_raw_data.py切换到 ResEnc 预设只需显式传入上述标识。新预设的训练结果会存放在独立目录绝不会覆盖标准 nnU-Net 的训练结果所以可以放心尝试不会破坏已有实验。规划器内部做了什么从源码角度nnUNetPlannerResEncM/L/XL均继承自ResEncUNetPlanner后者又继承自ExperimentPlanner并在初始化时做三件事设置网络类为ResidualEncoderUNetself.UNet_class ResidualEncoderUNet设置显存参考基准UNet_reference_val_3d/UNet_reference_val_2d用于在 patch size 搜索循环中估算并匹配目标显存。例如 M 预设为 3D 6.8 亿 / 2D 1.35 亿与标准配置 5.6 亿/8500 万相比显著更高因为残差编码器在相同 patch 下占用更多特征图显存L 预设为 21 亿/3.8 亿XL 预设为 36 亿/5.6 亿取消 batch size 上限self.max_dataset_covered 1标准规划器为0.05即一个 batch 最多覆盖整个数据集的 5%见 default_experiment_planner.py。预设移除这一限制后batch size 可以任意放大这是大显存配置能进一步提速的关键。显存估计过程本身是从大到小的搜索规划器先按目标 spacing 构造一个初始 patch size通过static_estimate_VRAM_usage实例化网络并计算compute_conv_feature_map_size(patch_size)若估计值超过参考显存预算则逐步收缩违反宽高比最严重的轴直至满足预算剩余显存余量则用于上调 batch size。整套逻辑与标准ExperimentPlanner共用区别仅在于参考基准数值与 batch 上限。突破预设按你的 GPU 显存任意缩放预设本身只是为了让生活更简单、并提供可复现的标准化配置供社区基准评测。你可以轻易调整 GPU 显存目标来匹配你的硬件甚至扩展到 40GB 以上。预设与原始ResEncUNetPlanner的差异只有两点为gpu_memory_target_in_gb设置了新的默认值以对应各自显存档位移除了 0.05 的 batch size 上限此前一个 batch 覆盖的像素数不能超过整个数据集的 5%现在可以任意大。为什么不直接使用ResEncUNetPlanner因为它仍然保留了 5% 上限示例缩放到 80GB 显存Dataset003_LivernnUNetv2_plan_experiment -d 3 -pl nnUNetPlannerResEncM -gpu_memory_target 80 \ -overwrite_plans_name nnUNetResEncUNetPlans_80G之后所有命令都改用新的 plans 标识即可nnUNetv2_train 3 3d_fullres 0 -p nnUNetResEncUNetPlans_80G几点注意事项务必遵守运行上面的命令会看到一条警告You are running nnUNetPlannerM with a non-standard gpu_memory_target_in_gb提示你传入了非标准显存目标。这是规划器在 residual_encoder_unet_planners.py 中有意抛出的属于正常的你确实在有意修改的确认信号此处可以忽略。每次改动显存目标都必须用-overwrite_plans_name NEW_PLANS_NAME指定新的 plans 标识以避免覆盖预设的 plans 文件这一点在nnUNetv2_plan_experiment的-gpu_memory_target与-overwrite_plans_name参数说明中也被标注为 DANGER ZONE见 plan_and_preprocess_entrypoints.py修改显存目标会直接影响 patch 与 batch size进而影响模型性能必须先把标准 nnU-Net 跑出基线再考虑自定义。从 API 层看-gpu_memory_target与-overwrite_plans_name最终会分别透传为规划器的gpu_memory_target_in_gb与plans_name构造参数plan_and_preprocess_api.py从而生成独立命名的 plans JSON 文件。缩放时的注意事项缩放显存目标本身也有边界目标显存越大规划器搜索出的 patch size 越大但超大显存目标下初始 patch size 的构造基准3D 以 256³ 体素为参照2D 以 2048² 为参照可能会让搜索循环的迭代次数增加规划耗时变长——这在源码注释中有明确说明residual_encoder_unet_planners.py。扩展到多 GPU手动调大 batch size 而不是显存目标当要扩展到多 GPU 时不要简单地把多张卡的显存总和传给nnUNetv2_plan_experiment的-gpu_memory_target——这会导致规划出单张 GPU 无法处理的过大 patch size。正确做法是先按单张 GPU 的显存预算运行规划例如上面 80GB 的例子若单卡为 80GB然后手动编辑生成的 plans JSON 文件来增大 batch size。编辑方法利用了 nnU-Net 的配置继承机制详细说明见 configuration inheritance。在生成的 plans JSON 的configurations字典中添加如下条目3d_fullres_bsXX: { inherits_from: 3d_fullres, batch_size: XX },其中XX是新的 batch size。例如若3d_fullres在单卡上的 batch size 为 2你要扩展到 8 张 GPU则新 batch size 应设为 2×8 16。配置继承在运行期由PlansManager解析它会在读取配置时递归查找inherits_from指向的父配置并做字典合并plans_handler.py因此3d_fullres_bs16会自动继承3d_fullres的 patch size、spacing、架构定义等全部设置仅覆盖 batch size。这是 plans 文件比 v1 更灵活的核心机制之一。然后就可以用 nnU-Net 的多 GPU 设置训练这个新配置nnUNetv2_train DATASETID 3d_fullres_bsXX FOLD -p nnUNetResEncUNetPlans_80G -num_gpus 8其中-num_gpus参数会触发基于torch.multiprocessing.spawn的单节点多进程 DDP 训练run_training.py每个 worker 持有一张 GPU。提出新分割方法请按正确姿势做基准评测当你拿自己的新分割方法去和 nnU-Net 对比时官方鼓励与残差编码器系列进行对比。为了公平起见应选择与你的方法显存占用和算力需求最接近的那一档 ResEnc 变体M / L / XL而不是只对比显存需求最低的标准配置——这样得出的结论才具有说服力也符合论文 [1] 所倡导的严格验证精神。参考文献[1] Isensee, Fabian, et al. nnU-Net: a self-configuring method for deep learning-based biomedical image segmentation. Nature methods 18.2 (2021): 203-211以及 Isensee, F., Wald, T., Ulrich, C., Baumgartner, M., Roy, S., Maier-Hein, K., Jaeger, P. (2024). nnU-Net Revisited: A Call for Rigorous Validation in 3D Medical Image Segmentation. arXiv preprint arXiv:2404.09556使用预设时需引用的论文。[2] Roy, Saikat, et al. Mednext: transformer-driven scaling of convnets for medical image segmentation. MICCAI 2023.[3] Huang, Ziyan, et al. Stu-net: Scalable and transferable medical image segmentation models empowered by large-scale supervised pre-training. arXiv preprint arXiv:2304.06716 (2023).[4] Hatamizadeh, Ali, et al. Swin unetr: Swin transformers for semantic segmentation of brain tumors in mri images. MICCAI Brainlesion Workshop 2021.[5] He, Yufan, et al. Swinunetr-v2: Stronger swin transformers with stagewise convolutions for 3d medical image segmentation. MICCAI 2023.[6] Zhou, Hong-Yu, et al. nnformer: Interleaved transformer for volumetric segmentation. arXiv preprint arXiv:2109.03201 (2021).[7] Xie, Yutong, et al. Cotr: Efficiently bridging cnn and transformer for 3d medical image segmentation. MICCAI 2021.[8] Ma, Jun, Feifei Li, and Bo Wang. U-mamba: Enhancing long-range dependency for biomedical image segmentation. arXiv preprint arXiv:2401.04722 (2024).[9] Myronenko, Andriy. 3D MRI brain tumor segmentation using autoencoder regularization. BrainLes 2018 (with MICCAI 2018).[10] He, Yufan, et al. Dints: Differentiable neural network topology search for 3d medical image segmentation. CVPR 2021.[11] Auto3DSeg, MONAI 1.3.0。相关仓库资源预设与规划器实现residual_encoder_unet_planners.pyResEncUNetPlanner基类及 M/L/XL 三个子类旧路径的弃用说明与兼容转发resencUNet_planner.py标准规划器基类patch/batch 搜索逻辑、5% 上限来源default_experiment_planner.py命令行入口与参数解析-pl、-gpu_memory_target、-overwrite_plans_nameplan_and_preprocess_entrypoints.py规划/预处理 API 层plan_and_preprocess_api.pyplans 配置继承机制plans_handler.py 与 explanation_plans_files.md训练命令-p、-num_gpusrun_training.py推理命令-ppredict_from_raw_data.py赞分享人工智能深度学习计算机视觉医疗健康【免费下载链接】nnUNet项目地址https://gitcode.com/gh_mirrors/nn/nnUNet点击查看免费下载相关推荐DiT训练资源规划实战从GPU瓶颈到高效训练的完整指南DiT训练资源规划实战从GPU瓶颈到高效训练的完整指南 DiTScalable Diffusion Models with Transformers作为基人工智能深度学习计算机视觉媒体生成nnU-Net v2 模型训练完全指南nnUNetv2_train 命令、配置选择与多 GPU 实战nnU Net v2 模型训练完全指南nnUNetv2_train 命令、配置选择与多 GPU 实战 本篇技术指南以 nnU Net v2当前仓库 nnun人工智能深度学习计算机视觉医疗健康nnU-Net v2 多 GPU 训练完全指南并行 Fold、单节点 DDP 与 torchrun 多节点实战nnU Net v2 多 GPU 训练完全指南并行 Fold、单节点 DDP 与 torchrun 多节点实战 本文是 nnU Net v2 官方多 GPU人工智能深度学习计算机视觉医疗健康上一篇AI流体动力学终极突破DeepCFD实现模拟加速1000倍的革命性技术下一篇Inline-Execute-PE开发解析BOF编写与CobaltStrike Aggressor脚本集成创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考