当使用 nnUNetv2_plan_and_preprocess 处理大规模数据集（如704例）时，程序常因多线程加载死锁而停滞；根本原因是默认线程数过高导致资源竞争或I/O阻塞，降低 --num_processes 参数可有效规避该问题。
当使用 `nnunetv2_plan_and_preprocess` 处理大规模数据集（如704例）时，程序常因多线程加载死锁而停滞；根本原因是默认线程数过高导致资源竞争或i/o阻塞，降低 `--num_processes` 参数可有效规避该问题。
在实际使用 nnU-Net v2 进行医学图像分割项目时，预处理阶段（尤其是 nnUNetv2_plan_and_preprocess）是关键且易出错的环节。用户反馈：当数据集包含 704 个样本时，命令 nnUNetv2_plan_and_preprocess -d 201 --verify_integrity 在加载阶段长期无响应（表现为终端卡在“Loading dataset…”或类似日志后静止），但将样本量降至 600 后可正常运行——这明确指向并发资源瓶颈，而非数据格式或路径错误。
根本原因在于：nnU-Net v2 默认启用多进程并行加载与预处理（通常为 --num_processes 默认值 ≈ CPU核心数），当数据量大、磁盘 I/O 性能有限（如HDD或网络存储）、或单样本体积较大（如高分辨率3D MRI）时，过多进程会引发：
- 文件句柄耗尽（OSError: Too many open files 隐式触发）
- 磁盘读取竞争导致进程阻塞
- Python multiprocessing 的 spawn/fork 机制在特定环境下产生死锁（尤其在Linux+某些CUDA环境）
✅ 推荐解决方案：显式限制并行线程数
# 推荐起始值：4~8（根据硬件调整） nnUNetv2_plan_and_preprocess -d 201 --verify_integrity --num_processes 4 # 若仍卡顿，逐步降低至2；若机器配置高（32GB RAM + SSD + ≥16核），可尝试6 nnUNetv2_plan_and_preprocess -d 201 --verify_integrity --num_processes 6
? 关键注意事项：
- --num_processes 仅控制数据加载与基础预处理的并行度，不影响后续训练阶段的GPU batch size 或分布式训练设置；
- 勿盲目设为 1：虽可避免死锁，但会显著延长预处理时间（尤其对千级样本）；建议先试 4，再按需微调；
- 确保 nnUNet_preprocessed 目录有充足磁盘空间（通常需原始数据 3–5 倍容量）；
- 若使用 NFS 或云存储，强烈建议将数据集本地缓存后再运行预处理；
- 可配合 --verbose 查看详细日志定位卡点（例如是否停在某特定 case 加载）。
? 补充验证技巧：
运行前执行完整性校验：
nnUNetv2_extract_dataset -d 201 # 检查JSON结构与文件路径
python -c "import nibabel as nib; nib.load('path/to/one_case.nii.gz')" # 验证单样本可读性通过合理约束并发规模，既可稳定处理完整704例数据集，又能兼顾效率与鲁棒性——这是部署 nnU-Net v2 生产级流程的必备调优实践。
