人工智能深度学习计算机视觉医疗健康【免费下载链接】nnUNet项目地址https://gitcode.com/gh_mirrors/nn/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任务 IDjob 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 属性折叠回DDPTopologynnUNetTrainer.__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:移除AllGatherGradnnunetv2/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 XnnU-Net 自己mp.spawnworker仅单节点与torchrun启动器生成进程支持单/多节点两条路径最终汇入同一代码路径推迟是因为-num_gpus是已文档化的接口、pip 安装后无需克隆仓库即可使用而 torchrun 需要run_training.py的路径让 DDP 与非 DDP 的深度监督权重完全一致见下文「分布式训练」小节中的1e-6细节。环境变量三条铁律 可选项nnU-Net 的一切定位都通过三个变量完成没有它们什么也跑不起来变量存放内容nnUNet_rawnnU-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.pynnunetv2/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_sizeddp.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.pyexit_training()只置位exit_training_flag不做任何可能死锁的操作信号处理器会在任意位置打断主线程任何持锁操作——日志、打印、文件 I/O——都可能死锁_exit_signal_received()在 DDP 下用dist.all_reduce(flag, opReduceOp.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.5nnunetTrainer.py。深度监督最低权重在 DDP 下从0变为1e-6_build_loss()正常将最低分辨率输出权重设为0指数递减1/(2**i)但 DDP 下权重恰好为0会让这些参数脱离反向图触发 DDP 的「unused parameters」报错因此 DDP 分支改用1e-6nnunetTrainer.py。代价是 DDP 与单 GPU 训练优化的并非完全相同的目标函数——这正是DEFERRED_CLEANUPS.md中 v3 清理条目之一理想方案是构建网络时不带未使用的分割头或对 DDP 传static_graphTrue但后者会硬报错于图结构随迭代变化的 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 不可见地依赖本仓库的每个公开名字→破坏性变更走 changelogdocumentation/changelog.md 的「Changes that affect custom trainers」→不得不推迟的清理进 DEFERRED_CLEANUPS.mdDEFERRED_CLEANUPS.md→DDP 相关改动逐条核对 rank 语义与全局写入守卫→最后用pytest nnunetv2/tests加速回归、用集成测试脚本验证端到端流水线。这条流程同时保护了仓库内部的稳定性与仓库外部数十万行自定义 trainer 代码的兼容性。赞分享人工智能深度学习计算机视觉医疗健康【免费下载链接】nnUNet项目地址https://gitcode.com/gh_mirrors/nn/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网络安全教程文档上一篇如何快速掌握xhr库从零开始发送HTTP请求的完整指南 下一篇LMCache 分布式 KV Cache 实战P/D 分离、P2P 共享与多服务器协调创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考