- 人工智能
- 深度学习
- 计算机视觉
- 医疗健康
【免费下载链接】nnUNet
本文是 nnU-Net 仓库中面向「编码 Agent 与代码贡献者」的工作手册（对应仓库根目录 CLAUDE.md）：它不是用户文档，而是回答「如何在不破坏海量第三方使用者的前提下，安全地修改这套代码库」。读完你将掌握 nnU-Net 的三条环境变量铁律、各模块目录职责、合并分支前的清理流程、自定义 trainer 兼容性红线，以及分布式训练（DDP）中local_rank/global_rank等极易出错的关键语义，并学会用单元测试与集成测试验证改动。
文档定位：先分清「用户文档」与「改造手册」
仓库根目录有三份入口文档，分工不同，读之前先分清：
- 普通用户从这里开始：readme.md 与 documentation/——它们介绍 nnU-Net 的安装、数据集准备、规划预处理、训练推理等使用方法；
- 贡献者从这里开始：CONTRIBUTING.md——说明仓库接受什么、不接受什么；
- 被刻意推迟的简化项：DEFERRED_CLEANUPS.md——记录「我们明知该做、但做了会破坏现有用户/自定义 trainer、只能留到未来大版本再执行的清理」。
CLAUDE.md只谈如何安全地改动这套代码库，与用户文档刻意不重复。这一点决定了后续所有规则的出发点：任何修改的第一优先考虑，是它会不会在仓库之外的用户代码中无声地裂开。
合并分支到 master 之前：先清理「分支痕迹」
CLAUDE.md会随仓库分发到每一个克隆者手中，因此它必须读起来像「关于代码库本身的指南」，而不是某条分支的记录。功能分支在存活期间往往会积累一类绝不能进入 master的内容：
- 集群与主机名（cluster / host names）；
- 任务 ID（job ids）；
- 某台机器上的绝对路径；
- 指向内部报告的链接；
- 关于「进行中工作」的状态备注。
这些内容在分支存活期是合理的——它正是笔记随机器流转的方式。但合并前必须清理：重新通读CLAUDE.md（若存在AGENTS.md也一并检查），把路径、基础设施名、内部链接、以及「只对某一次实验成立」的说明全部剔除。若某条笔记只对自己的分支成立，它就该留在分支上；同时也要处理分支历史——建议squash 或丢弃携带内部笔记的 commit，因为「清理了文件」并不等于「清理了引入它的提交历史」。
最重要的规则：改动必须是「加法优先」，因为大量代码在仓库之外
CLAUDE.md用一句话点出这条红线：
nnU-Net 被大量人使用，而其中很大一部分使用发生在自定义 trainer 和位于本仓库之外的自定义代码中。他们继承
nnUNetTrainer、读取它的属性、导入我们的工具函数、解析我们的输出文件。
这意味着一个「看起来无害」的重命名或签名变更，会在仓库内部一切测试通过的情况下，让外部用户在训练开始数小时后才崩溃。因此：
- 优先做加法（additive changes）——新增参数、新增方法、保留旧入口；
- 若确实会破坏第三方代码，必须在 documentation/changelog.md 的「Changes that affect custom trainers」一节登记，写清旧写法与新写法；
- 如果正确的清理无法在不破坏用户的前提下完成——不要悄悄做、也不要只留在 commit message 里——应把它写进 DEFERRED_CLEANUPS.md，归入能够执行它的那个 release 之下，并说清三件事：做什么、为什么推迟、会破坏什么（最后一项是未来的读者无法自行重建的信息）。
从源码可以印证这个生态位：nnunetv2/training/nnUNetTrainer/nnUNetTrainer.py中，build_network_architecture的新旧两套签名并存，旧签名会触发DeprecationWarning并提示迁移到新签名（nnUNetTrainer.py），这正是「加法优先 + 显式警告」策略的典型实例。
用 DEFERRED_CLEANUPS.md 理解「推迟」的完整形态
DEFERRED_CLEANUPS.md开篇强调：这不是 TODO 清单。只有「刻意推迟」的条目才属于这里——知道正确形态是什么、知道为什么现在不做、知道会破坏什么；普通 bug 与未完成工作应进 issue 跟踪。条目要随产生技术债的同一个 PR 一起添加，并在可执行它的 release 下登记；执行时自上而下处理，落地一条删除一条，并在 changelog 中说明删除。文档针对 nnU-Net v3 记录了四个典型案例，每条都能与当前源码一一对上：
- 把四个 DDP rank 属性折叠回
DDPTopology：nnUNetTrainer.__init__目前把get_ddp_topology()解包成self.local_rank、self.global_rank、self.world_size、self.local_world_size四个属性——它们本质上就是DDPTopology这个 NamedTuple 被逐字段摊开。推迟原因是self.local_rank先于一切存在，仓库外大量自定义 trainer 直接读它（如if self.local_rank == 0:）； - 移除
AllGatherGrad：nnunetv2/utilities/ddp_allgather.py 中的AllGatherGrad在 nnU-Net 内部已无任何使用，损失函数改用nnunetv2/utilities/ddp.py中的AllReduceGrad——后者前向与反向计算等价（AllGatherGrad.apply(x).sum(0)恰好等于AllReduceGrad.apply(x)），但通信数据量减少world_size倍；推迟是因为外部自定义损失与 trainer 仍在导入它（当前版本已通过DeprecationWarning指向替代品）； - 决定
-num_gpus是否存活：-num_gpus X（nnU-Net 自己mp.spawnworker，仅单节点）与torchrun（启动器生成进程，支持单/多节点）两条路径最终汇入同一代码路径；推迟是因为-num_gpus是已文档化的接口、pip 安装后无需克隆仓库即可使用，而 torchrun 需要run_training.py的路径； - 让 DDP 与非 DDP 的深度监督权重完全一致：见下文「分布式训练」小节中的
1e-6细节。
环境变量：三条铁律 + 可选项
nnU-Net 的一切定位都通过三个变量完成，没有它们什么也跑不起来：
| 变量 | 存放内容 |
|---|---|
nnUNet_raw | nnU-Net 原始格式的数据集 |
nnUNet_preprocessed | 指纹（fingerprints）、plans、预处理后的数据 |
nnUNet_results | 训练好的模型、日志、检查点、验证输出 |
完整说明见 documentation/set_environment_variables.md 与 documentation/setting_up_paths.md。此外nnUNet_compile、nnUNet_n_proc_DA等变量是可选的，同样在上述文档中说明。
注意三者分工的实质差异：nnUNet_raw是输入侧（原始数据集），nnUNet_preprocessed是中间产物（由 plan_and_preprocess 生成），nnUNet_results是输出侧（训练与验证产物）。集成测试也需要这三个变量（见下文「测试」节）。
目录布局：改代码前先找对位置
| 路径 | 职责 |
|---|---|
nnunetv2/experiment_planning/ | 指纹提取、planner、预处理 |
nnunetv2/training/nnUNetTrainer/ | nnUNetTrainer及其变体。大部分扩展发生在这里 |
nnunetv2/training/ | 损失函数、数据加载、数据增强、LR 调度 |
nnunetv2/inference/ | 滑窗推理、结果导出 |
nnunetv2/evaluation/ | 指标、最佳配置选择 |
nnunetv2/run/ | nnUNetv2_train与 DDP 启动路径 |
nnunetv2/utilities/ | 共享工具，包括ddp.py |
nnunetv2/tests/ | 单元测试与integration_tests/ |
一个极其实用的找路技巧：每个面向用户的命令都是一个 console entry point，声明在pyproject.toml的[project.scripts]表中——那张表是「从命令名到其背后代码」的最快地图。例如nnUNetv2_train = "nnunetv2.run.run_training:run_training_entry"、nnUNetv2_plan_and_preprocess = "nnunetv2.experiment_planning.plan_and_preprocess_entrypoints:plan_and_preprocess_entry"（见 pyproject.toml）。要追踪任何命令，先查这张表即可定位入口函数。
分布式训练：rank 语义与四条避坑铁律
DDP 有两种启动方式，最终汇入同一条代码路径：
- 单节点：
-num_gpus X，由 nnU-Net 自己 spawn 各 worker； - 多节点：
torchrun，由启动器 spawn 进程。
因为启动器之下的代码永远无需知道是谁启动了它，所以「launcher 之下」的实现可以统一。这一点在源码中有完整闭环：nnunetv2/run/run_training.py的launch_training()是三种启动方式（外部 launcher /-num_gpus/ 单进程）共享的唯一入口，run_intranode_ddp()在被-num_gpus触发时模拟 torchrun 的四个环境变量（RANK、WORLD_SIZE、LOCAL_RANK、LOCAL_WORLD_SIZE），从而让下游代码只读这四个变量即可（run_training.py）。外部启动器检测则看TORCHELASTIC_RUN_ID（只有 torchrun 会设置）或完整的RANK + WORLD_SIZE + LOCAL_RANK三元组——后者要求三者齐全，防止 shell 里残留的RANK把-num_gpus 4静默变成单进程任务（run_training.py）。
四个拓扑属性：含义与「承重墙」
nnunetv2/utilities/ddp.py中的get_ddp_topology()提供四个值，它们之间的区分是承重墙（load-bearing）：
| 属性 | 含义 |
|---|---|
self.local_rank | 本进程在节点内的索引 →CUDA 设备索引 |
self.global_rank | 本进程在整个任务内的索引 →决定谁写文件 |
self.world_size | 任务中的进程总数 |
self.local_world_size | 本节点上的进程数 |
源码层面，DDPTopology是一个 NamedTuple，四个字段的注释直接写明了用途（local_rank的注释就是「this is the CUDA device index!」，ddp.py）。get_ddp_topology()要求进程组已初始化，读取优先级为：先读torchrun/-num_gpus设置的四个环境变量（这是权威来源，因为torch.distributed本身没有「节点」概念，local_rank无法从进程组读出）→ 回退到 SLURM/MPI 常见调度变量（如SLURM_LOCALID、OMPI_COMM_WORLD_LOCAL_RANK）→ 最后通过dist.all_gather_object收集各 rank 的主机名来推导local_rank/local_world_size（ddp.py）。
铁律一：所有写入nnUNet_results的操作必须用global_rank == 0守卫
单节点时local_rank与global_rank恰好重合，所以这里的错误在单节点上完全不可见——直到有人跨节点训练才会爆发：每个节点都有一个local_rank == 0，在共享文件系统上它们会同时写同一个日志文件、同一批检查点和同一个进度图。local_rank只应在「你真的指 GPU」时使用。
铁律二：collective 必须被所有 rank 到达
某个 rank-0 分支里的return或异常若跳过了 barrier/collective，会挂起整个任务直到 NCCL watchdog 触发。任何dist.*调用都必须保证全进程组同步到达。
铁律三：barrier 的等待顺序
让 rank 们在读取其他 rank 写入的内容之前等待，而不是之后——顺序颠倒会造成读时数据尚未就绪的竞态。
铁律四：SIGUSR1的跨进程语义
SIGUSR1只设置一个标志，该标志在epoch 边界处跨任务做规约（reduce），因此只要一个 rank 收到信号，所有 rank 都会一起停止。不要在信号处理器里打日志。源码实现了这一整套逻辑：nnUNetTrainer.__init__在hasattr(signal, 'SIGUSR1')时注册exit_training处理器（Windows 无此信号，nnUNetTrainer.py）；exit_training()只置位exit_training_flag，不做任何可能死锁的操作（信号处理器会在任意位置打断主线程，任何持锁操作——日志、打印、文件 I/O——都可能死锁）；_exit_signal_received()在 DDP 下用dist.all_reduce(flag, op=ReduceOp.MAX)把标志规约到整个任务，并处理「别的 rank 收到信号而自己没有」的情形（nnUNetTrainer.py）。这也解释了为何「不要从信号处理器打日志」——日志发生在 epoch 边界由_exit_signal_received()统一完成。
与 DDP 相关的两个实现细节
batch size 与 oversample 的按 rank 分摊：_set_batch_size_and_oversample()在 DDP 下把计划的全局 batch size 按world_size均分（余数逐个 rank 加 1，保证sum == global_batch_size），并且为每个 worker 重新计算oversample_foreground_percent——因为 oversample 是「全局 batch 内取整」的，简单数值换算会失真（例如 0.33 的 oversample、batch size 2，会被取整成 0.5）（nnunetTrainer.py）。
深度监督最低权重在 DDP 下从0变为1e-6：_build_loss()正常将最低分辨率输出权重设为0（指数递减1/(2**i)），但 DDP 下权重恰好为0会让这些参数脱离反向图，触发 DDP 的「unused parameters」报错；因此 DDP 分支改用1e-6（nnunetTrainer.py）。代价是 DDP 与单 GPU 训练优化的并非完全相同的目标函数——这正是DEFERRED_CLEANUPS.md中 v3 清理条目之一（理想方案是构建网络时不带未使用的分割头，或对 DDP 传static_graph=True，但后者会硬报错于图结构随迭代变化的 trainer）。
测试：单元测试快、集成测试慢，各有分工
pytest nnunetv2/tests # 单元测试，快 nnunetv2/tests/integration_tests/run_integration_test.sh # 全流程集成测试，慢 nnunetv2/tests/integration_tests/run_integration_test_trainingOnly_DDP.sh # DDP 路径- 单元测试覆盖不了端到端流水线；
- 集成测试需要上文的三条环境变量和真实数据，细节见 nnunetv2/tests/integration_tests/readme.md；
- 任何触及 planning、preprocessing 或 training 的改动都应跑集成测试验证——
nnunetv2/tests/下另有test_find_objects.py、test_foreground_locations.py、test_resampling.py等单元测试文件可快速回归具体模块。
编码约定：风格、可复现性、性能声明
- 风格跟从周边代码，不要强行引入新风格。代码库先于大多数现行 formatter 存在，顺手做一次「路过式重排」会把真实改动淹没在大 diff 里；
- 训练必须保持可复现：种子、plans 与预处理数据共同决定结果。一项会改变分割质量的改动，需要拿出与旧行为对比的数字，而不是「理论上应该等价」的论证；
- 性能声明必须有测量。documentation/benchmarking.md 与
nnUNetTrainerBenchmark_5epochs（见 nnunetv2/training/nnUNetTrainer/variants/benchmarking/nnUNetTrainerBenchmark_5epochs.py）就是为此而存在的：比较时用最快的 epoch（而非均值），并且绝不在不同 GPU 型号之间比较。
结语：一句话工作流
对任何一次改动，CLAUDE.md给出了一条可执行的心智模型：先定位（pyproject.toml的 entry point 表 → 对应模块）→优先加法（外部自定义 trainer 不可见地依赖本仓库的每个公开名字）→破坏性变更走 changelog（documentation/changelog.md 的「Changes that affect custom trainers」）→不得不推迟的清理进 DEFERRED_CLEANUPS.md（DEFERRED_CLEANUPS.md）→DDP 相关改动逐条核对 rank 语义与全局写入守卫→最后用pytest nnunetv2/tests加速回归、用集成测试脚本验证端到端流水线。这条流程同时保护了仓库内部的稳定性与仓库外部数十万行自定义 trainer 代码的兼容性。
- 人工智能
- 深度学习
- 计算机视觉
- 医疗健康
【免费下载链接】nnUNet
相关推荐
Security-101 仓库协作指南：面向贡献者与 AI 编码代理的文档课程维护手册
Security 101 仓库协作指南：面向贡献者与 AI 编码代理的文档课程维护手册 Security 101 是一个由微软出品的入门级网络安全课程仓库，其全
网络安全教程文档InstallerX Revived 代码贡献全指南：面向 AI 编码 Agent 的仓库协作规范与构建流程
InstallerX Revived 代码贡献全指南：面向 AI 编码 Agent 的仓库协作规范与构建流程 InstallerX Revived 是一个社区维
原生移动Security-101 仓库协作指南：面向贡献者与 AI 编码代理的 AGENTS.md 全解读
Security 101 仓库协作指南：面向贡献者与 AI 编码代理的 AGENTS.md 全解读 本文以仓库中的 translations/hr/AGENTS
网络安全教程文档
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
