nnU-Net（nnUNetv2）语义分割框架完全指南：自动配置管线、快速安装与端到端工作流

人工智能深度学习计算机视觉医疗健康【免费下载链接】nnUNet项目地址https://gitcode.com/gh_mirrors/nn/nnUNet点击查看免费下载nnU-Net 是一个会自动适配数据集的语义分割框架它通过分析训练数据生成数据集指纹dataset fingerprint自动配置合适的 U-Net 变体并提供从数据预处理、训练、模型选择到推理的完整端到端工作流。本文以仓库根目录的 readme.md 为主线结合 源码目录、pyproject.toml 与各级 文档系统讲解 nnU-Net v2 的核心原理、安装部署与实战命令帮助读者从零跑通自己的分割数据。一、nnU-Net 是什么一个自我配置的分割框架按 readme.md 的定位nnU-Net 是一个语义分割框架其核心能力是自动适配管线到具体数据集。它不需要用户为每个数据集手动调优网络架构、预处理与训练细节而是自动完成以下闭环分析训练数据生成数据集指纹dataset fingerprint配置合适的 U-Net 变体2D / 3D / 级联等提供端到端工作流预处理 → 训练 → 模型选择 → 推理。它主要面向有监督的医学图像分割同时也被广泛用作新分割方法研究的强基线strong baseline和开发框架。需要特别说明仓库当前代码对应的是nnU-Net v22.8.1 版本见 pyproject.toml如果寻找 v1 请切换到nnunetv1分支从 v1 迁移的用户建议先读 TLDR 迁移指南 和 What is different in v2?。设计动机为什么需要自动配置分割数据集差异极大How nnU-Net Works 列举了这些关键差异维度2D 还是 3D 数据模态modality与通道数图像尺寸与体素间距voxel spacing各向异性anisotropy类别不平衡class imbalance目标结构本身的形态特性。这些属性相互影响手工设计管线既容易出错又难以规模化。nnU-Net 的做法是把数据集属性转变成一个可复现的配置过程。适用范围Scope支持 2D 与 3D 数据、任意通道定义、多种图像格式依赖条件需要带标注的训练数据、一致的通道定义、且图像能在当前系统的预处理/后处理流程中被处理在从零训练training-from-scratch、生物医学数据集、挑战赛数据以及预训练自然图像模型不适用的非标准成像问题上表现尤为突出此表述以 readme.md 原文本为准属项目自述而非基准测试结论。二、自动配置原理三类参数与数据集指纹nnU-Net 的自动适配依赖三种决策详见 How nnU-Net Works参数类型含义示例固定参数Fixed不随数据集调整的稳定默认值架构模板、优化器、学习率、损失函数、数据增强、推理流程规则参数Rule-based由数据集指纹推导的启发式参数目标间距、重采样策略、强度归一化、patch size、网络拓扑、batch size经验参数Empirical通过比较得出的选择最佳配置选择find_best_configuration、后处理配置、集成ensemble选择数据集指纹dataset fingerprint汇总了图像尺寸、间距spacing、强度信息等属性nnU-Net 据此决定预处理方案、目标间距、patch size 与网络拓扑。在 v2 中指纹被显式保存为 JSON 文件见 changelog.md位于预处理输出目录下。主配置Main Configurations取决于数据集特性nnU-Net 可能生成以下配置之一或多个readme.md 与 How nnU-Net Works2d3d_fullres3d_lowres3d_cascade_fullres注意不是每个数据集都会生成全部配置。例如级联cascade只有在数据集特征证明其有必要时才会被创建readme.md 的 Project Notes 明确说明小数据集通常不会生成3d_cascade_fullres见 train-models.md。此外从 pyproject.toml 的入口点列表还可以看到nnUNetv2_plan_like_dynamic、nnUNetv2_preprocess_like_nnssl等扩展入口说明配置体系是可扩展的。三、快速安装与部署1. 前置条件Python 3.10 或更新pyproject.toml 声明requires-python 3.10首选 LinuxWindows 与 macOS 也受支持训练强烈建议使用 GPUApple Silicon 可用mps但 3D 卷积仍可能需要 CPU 回退先安装 PyTorch再安装 nnunetv2请先到 PyTorch 官网按硬件选择对应构建cuda/mps/cpu不要在 PyTorch 就位前安装nnunetv2。2. 安装命令普通使用pip install nnunetv2本地可编辑安装适合开发git clone https://github.com/MIC-DKFZ/nnUNet.git cd nnUNet pip install -e .在Intel非 Apple SiliconmacOS上需要额外安装intel_macosextra 以锁定兼容的 torch 与 numpy 版本该 extra 在 pyproject.toml 中定义为torch2.3与numpy2的 Darwin 平台约束pip install nnunetv2[intel_macos] # 或可编辑安装 pip install -e .[intel_macos]3. 创建三个存储位置nnU-Net 依赖三个环境变量指向的目录变量用途nnUNet_raw存放 nnU-Net 格式的原始数据集nnUNet_preprocessed存放训练所用的预处理数据nnUNet_results存放训练好的模型与安装的预训练模型Linux/macOS 持久配置写入.bashrc或.zshrcexport nnUNet_raw/path/to/nnUNet_raw export nnUNet_preprocessed/path/to/nnUNet_preprocessed export nnUNet_results/path/to/nnUNet_resultsWindows PowerShell$Env:nnUNet_raw C:/path/to/nnUNet_raw $Env:nnUNet_preprocessed C:/path/to/nnUNet_preprocessed $Env:nnUNet_results C:/path/to/nnUNet_resultsWindows CMDset nnUNet_rawC:/path/to/nnUNet_raw set nnUNet_preprocessedC:/path/to/nnUNet_preprocessed set nnUNet_resultsC:/path/to/nnUNet_results验证Linux/macOS 用echo $nnUNet_raw等Windows 用echo $Env:nnUNet_raw/echo %nnUNet_raw%。更完整的说明见 installation-and-setup.md 与 set_environment_variables.md。4. 可选组件与调优hiddenlayer用于生成网络拓扑图pip install --upgrade githttps://github.com/FabianIsensee/hiddenlayer.git在快速 GPU 上训练时可调优nnUNet_n_proc_DA以匹配数据增强吞吐量installation-and-setup.md。四、端到端工作流从数据到推理nnU-Net 的高层工作流How nnU-Net Works为准备数据 → 提取指纹/生成 plans/预处理 → 训练一个或多个配置 → 比较配置并确定后处理 → 用选定方案推理。对应到 Getting Started 推荐的路径如下。1. 准备数据集nnU-Net 要求数据集位于nnUNet_raw/DatasetXXX_Name结构为dataset-format.mdnnUNet_raw/ └── Dataset123_MyDataset ├── dataset.json ├── imagesTr ├── imagesTs └── labelsTr命名规则图像文件为{CASE_IDENTIFIER}_{XXXX}.{FILE_ENDING}XXXX是 4 位通道标识如0000、0001分割文件为{CASE_IDENTIFIER}.{FILE_ENDING}。多通道数据每个通道单独存一个文件所有通道必须几何对齐且通道顺序在所有 case 间保持一致——推理输入沿用同一约定。dataset.json核心字段{ channel_names: { 0: T2, 1: ADC }, labels: { background: 0, PZ: 1, TZ: 2 }, numTraining: 32, file_ending: .nii.gz }要点labels将标签名映射为整数channel_names会影响归一化行为对应 map_channel_name_to_normalization.py 的实现file_ending同时定义训练与推理的文件格式可选overwrite_image_reader_writer可指定特定读写器。支持的格式包括.nii.gz、.nrrd、.mha、.png、.bmp、.tif/.tiff、带 sidecar 间距 JSON 的 3D TIFF图像与标签必须使用同一数据集级格式有损格式如.jpg不适用。已有其他格式的数据可转换MSD 数据集用 Convert MSD datasetsnnU-Net v1 数据集用nnUNetv2_convert_old_nnUNet_dataset入口见 convert_raw_dataset_from_old_nnunet_format.py。完整说明见 prepare-a-dataset.md。2. 规划与预处理Plan and Preprocess推荐命令首次运行建议加--verify_dataset_integritynnUNetv2_plan_and_preprocess -d DATASET_ID --verify_dataset_integrity该命令依次完成三件事对应 plan_and_preprocess_entrypoints.py 中的三个独立入口提取数据集指纹生成一个或多个 nnU-Net 配置为这些配置预处理数据。输出写入nnUNet_preprocessed/DatasetXXX_Name内含dataset_fingerprint.json、nnUNetPlans.json以及各配置的预处理数据目录。每个配置目录中除了预处理图像与分割分割以 int8 存储较 v1 节省磁盘与 I/O还有每个 case 的.pkl属性文件与共享的前景采样位置存储fg_sampling/详见 preprocessed-data-format.md。常用选项--no_pbar非交互环境使用-d 1 2 3一次处理多个数据集-c 3d_fullres已确定配置时直接指定-h查看全部选项。若需更细粒度控制可拆分执行nnUNetv2_extract_fingerprint -d DATASET_ID nnUNetv2_plan_experiment -d DATASET_ID nnUNetv2_preprocess -d DATASET_IDv2 的 plans 文件已全面重构为 JSONchangelog.md配置被显式命名如3d_fullres可相互继承级联阶段以next_stage/previous_stage显式列出归一化策略、重采样等大量能力都能通过 plans 修改多个配置还可共享同一预处理数据目录默认3d_fullres与3d_cascade_fullres共享数据。3. 训练模型训练命令格式nnUNetv2_train DATASET_NAME_OR_ID CONFIGURATION FOLD例如nnUNetv2_train DATASET_NAME_OR_ID 2d 0 nnUNetv2_train DATASET_NAME_OR_ID 3d_fullres 0 nnUNetv2_train DATASET_NAME_OR_ID 3d_lowres 0 nnUNetv2_train DATASET_NAME_OR_ID 3d_cascade_fullres 0级联使用前必须先训练3d_lowres。通常以5 折交叉验证训练以便后续比较配置并可选做集成。若计划使用nnUNetv2_find_best_configuration务必加--npz保存验证概率nnUNetv2_train DATASET_NAME_OR_ID CONFIGURATION FOLD --npz已训练但未开--npz时可补跑验证nnUNetv2_train DATASET_NAME_OR_ID CONFIGURATION FOLD --val --npz设备选择用-devicecpu/cuda/mps多 GPU 系统用CUDA_VISIBLE_DEVICES指定CUDA_VISIBLE_DEVICES0 nnUNetv2_train DATASET_NAME_OR_ID 3d_fullres 0 --npz推荐的多卡策略是每 GPU 一个训练任务如CUDA_VISIBLE_DEVICES0 ... 2d 0与CUDA_VISIBLE_DEVICES1 ... 2d 1并行单机 DDP 用-num_gpus X多节点或使用torchrun时不要传-num_gpus详见 multi_gpu_training.md。注意多节点 DDP 下文件写入判断应使用global_rank而非local_rankchangelog.md 的破坏性变更说明。训练输出位于nnUNet_results/DatasetXXX_Name/TRAINER__PLANS__CONFIGURATION/fold_X关键产物包括checkpoint_final.pth、checkpoint_best.pth、progress.png、validation/summary.json以及开启--npz后的validation/*.npz。4. 自动寻找最佳配置前提必须有验证概率训练时--npz或补跑--val --npz。nnUNetv2_find_best_configuration DATASET_NAME_OR_ID -c CONFIGURATIONS示例nnUNetv2_find_best_configuration 123 -c 2d 3d_fullres 3d_lowres它会评估单个配置、成对集成除非--disable_ensembling、以及基于连通域移除的后处理。输出推荐推理命令并写入inference_instructions.txt与inference_information.json位于nnUNet_results/DatasetXXX_Name。对应源码见 find_best_configuration.py。5. 推理基本预测nnUNetv2_predict -i INPUT_FOLDER -o OUTPUT_FOLDER -d DATASET_NAME_OR_ID -c CONFIGURATION需要集成多配置概率输出时加--save_probabilitiesnnUNetv2_predict -i INPUT_FOLDER -o OUTPUT_FOLDER -d DATASET_NAME_OR_ID -c CONFIGURATION --save_probabilities默认推理以 5 个训练折集成若只训练了all折想单模型推理加-f allnnUNetv2_predict -i INPUT_FOLDER -o OUTPUT_FOLDER -d DATASET_NAME_OR_ID -c CONFIGURATION -f all多配置集成nnUNetv2_ensemble -i FOLDER1 FOLDER2 -o OUTPUT_FOLDER -np NUM_PROCESSES输入目录必须含--save_probabilities产生的概率文件。应用后处理nnUNetv2_apply_postprocessing \ -i FOLDER_WITH_PREDICTIONS \ -o OUTPUT_FOLDER \ --pp_pkl_file POSTPROCESSING_FILE \ -plans_json PLANS_FILE \ -dataset_json DATASET_JSON_FILE单配置预测时plans.json与dataset.json通常会被自动拷贝集成输出需显式提供。模型迁移先用nnUNetv2_export_model_to_zip -d DATASET_NAME_OR_ID -o MODEL.zip导出再在目标机器nnUNetv2_install_pretrained_model_from_zip MODEL.zip目标机仍需兼容的 nnU-Net 安装与全部依赖若使用自定义 trainer目标机还需能导入该 trainer 类见 share-models-with-custom-trainers.md。直接基于模型文件夹推理可用nnUNetv2_predict_from_modelfolder -i INPUT_FOLDER -o OUTPUT_FOLDER -m MODEL_FOLDER。多 GPU 推理使用CUDA_VISIBLE_DEVICESX nnUNetv2_predict [...] -num_parts Y -part_id Xchangelog.md。推理输入必须与训练数据集的文件后缀与通道命名一致建议优先使用find_best_configuration生成的inference_instructions.txt中的命令run-inference.md。五、CLI 命令速查来自 pyproject.toml 入口点nnU-Net v2 的全部功能都通过命令行入口暴露pyproject.toml核心命令与对应源码如下命令对应源码模块nnUNetv2_plan_and_preprocess/nnUNetv2_extract_fingerprint/nnUNetv2_plan_experiment/nnUNetv2_preprocess/nnUNetv2_extract_sampling_locationsplan_and_preprocess_entrypoints.pynnUNetv2_trainrun_training.pynnUNetv2_train_pretrainedrun_training_from_pretrained.pynnUNetv2_predict/nnUNetv2_predict_from_modelfolderpredict_from_raw_data.pynnUNetv2_ensembleensemble.pynnUNetv2_find_best_configuration/nnUNetv2_accumulate_crossval_resultsfind_best_configuration.pynnUNetv2_determine_postprocessing/nnUNetv2_apply_postprocessingremove_connected_components.pynnUNetv2_export_model_to_zip/nnUNetv2_install_pretrained_model_from_zip/nnUNetv2_download_pretrained_model_by_urlmodel_sharing/entry_points.pynnUNetv2_convert_old_nnUNet_dataset/nnUNetv2_convert_MSD_datasetdataset_conversionnnUNetv2_evaluate_folder/nnUNetv2_evaluate_simpleevaluate_predictions.pynnUNetv2_plot_overlay_pngsoverlay_plots.py如 changelog.md 所述v2 的所有功能同时可通过 API 调用具体函数映射见setup.py中的入口点声明。六、v2 相对 v1 的关键变化统一 trainer 类nnUNetTrainer集成了级联、DDP、region-based、ignore 等全部默认功能changelog.md无需再在多个 trainer 间切换跨平台设备支持cuda、mpsApple M1/M2、cpu通过-device选择分层标签region-based支持可直接以whole tumor等目标区域训练参见 region_based_training.md 与 BraTS 2021 转换脚本 Dataset137_BraTS21.pyplans 文件 JSON 化配置显式命名、可继承、级联阶段显式列出、归一化与重采样等可经 plans 修改数据格式与存储改进预处理分割以 int8 存储、不再有nnUNet_raw_cropped目录、指纹显式保存为 JSON原生多 GPU 训练DDP推理仍建议-num_parts分片方式更多图像 I/O 格式通过基于BaseReaderWriter的 ImageIO 类扩展见 base_reader_writer.py 与 reader_writer_registry.py。七、引用与致谢使用 nnU-Net 时请引用以下论文Isensee, F., Jaeger, P. F., Kohl, S. A., Petersen, J., Maier-Hein, K. H. (2021). nnU-Net: a self-configuring method for deep learning-based biomedical image segmentation. Nature Methods, 18(2), 203-211.残差编码器预设与基准测试相关的最新工作见 nnU-Net Revisited: A Call for Rigorous Validation in 3D Medical Image Segmentation。nnU-Net 由德国癌症研究中心DKFZ医学图像计算部门与 Helmholtz Imaging 的应用计算机视觉实验室ACVL开发维护。进一步阅读新用户从 Getting Started 开始任务导向指南见 How-to Guides格式与命令细节见 Reference设计原理见 Explanation挑战赛实战记录见 Case Studies。赞分享人工智能深度学习计算机视觉医疗健康【免费下载链接】nnUNet项目地址https://gitcode.com/gh_mirrors/nn/nnUNet点击查看免费下载相关推荐nnU-Net 工作原理深度解析数据集指纹驱动的自适应语义分割流水线nnU Net 工作原理深度解析数据集指纹驱动的自适应语义分割流水线 本篇文章以 nnU Net 官方解释文档 documentation/explanat人工智能深度学习计算机视觉医疗健康nnU-Net v2 完整安装指南系统要求、路径配置与 nnUNetv2 命令行工具详解nnU Net v2 完整安装指南系统要求、路径配置与 nnUNetv2 命令行工具详解 本文面向需要在本机Linux / Windows / macOS人工智能深度学习计算机视觉医疗健康Detox CLI 命令完全指南安装、配置与端到端测试工作流Detox CLI 命令完全指南安装、配置与端到端测试工作流 Detox 是面向移动应用的灰盒端到端测试与自动化框架而 Detox CLI 是其所有命令行操测试移动开发质量保障开发工具上一篇深入解析 .NET DllMap借助 NativeLibrary 回调实现跨平台 P/Invoke 原生库名称映射下一篇minikube 故障排查实战指南调试日志、事后日志与启动卡死定位创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考