distributed-training-troubleshooting

分布式训练排障：从挂起、NCCL 报错、OOM 到 straggler 的定位顺序

补充说明

分布式训练失败通常不是单一原因：进程组没建起来、NCCL 选错网卡、共享内存不足、某个 rank OOM、数据读取卡住、checkpoint 写爆磁盘，都会表现成“训练挂了”或“loss 不动”。排障顺序应该是：先确认单机能跑，再扩到 2 卡，最后上多机；先排除环境/网络，再怀疑算法。

常见症状：启动即报 NCCL error、训练几分钟后 hang、某个 rank OOM、GPU 利用率周期性掉零、loss 突然 NaN、checkpoint 保存失败。每一类都有对应的日志和工具，不要一上来就改 batch size 或重启。

常用示例

# 单机 8 卡最小复现
torchrun --standalone --nproc_per_node=8 train.py

# 打开分布式与 NCCL 调试日志
NCCL_DEBUG=INFO NCCL_DEBUG_SUBSYS=ALL \
TORCH_DISTRIBUTED_DEBUG=DETAIL \
torchrun --standalone --nproc_per_node=8 train.py

# 先验证多卡通信本身
./build/all_reduce_perf -b 8 -e 1G -f 2 -g 8

# 卡住时抓取进程栈（Python）
py-spy dump --pid <PID>

# 查看 GPU、进程和共享内存
nvidia-smi
df -h /dev/shm
ipcs -m
ulimit -a

# 查看内核 OOM/网络错误
dmesg -T | tail -50
journalctl -k --since '30 min ago' | grep -i -E 'oom|nvrm|xid|ib|mlx'

多机时先确认所有节点能互相解析、时间同步、MTU 一致、IB/RoCE 网卡可见，再检查 MASTER_ADDR/PORT 和防火墙。

易错点与排错

• 一上来就多机复现：先用单机单卡、单机多卡、双机逐步放大；每一步都确认能跑，才能定位是代码还是环境。
• 只看 rank 0 日志：错误可能只出现在某个 worker；收集所有 rank 的日志，按 rank 和时间对齐。
• NCCL_DEBUG=INFO 开太晚：启动阶段就失败时，日志要在进程启动前设置；容器里还要确认环境变量透传。
• 共享内存不足：PyTorch DataLoader/多进程默认用 /dev/shm，容器里常只有 64MB；增大 --shm-size 或减少 workers。
• 网卡/拓扑选错：NCCL 可能走管理网或 Docker bridge；用 NCCL_SOCKET_IFNAME、NCCL_IB_HCA 指定，并看 nvidia-smi topo -m。
• 某个 rank OOM：其他 rank 可能还在等集合通信，表现为 hang；先看每个 rank 的显存峰值和 traceback。
• straggler：某个 GPU/节点慢会拖住整个集合通信；用 nsys 看时间线，检查 ECC、降频、数据读取和 NUMA。
• 超时设置太短：大模型初始化/编译/首个 checkpoint 可能超过默认超时；按阶段调整 timeout，不要盲目无限等待。
• 文件系统瓶颈：所有 rank 同时读同一个大文件或写 checkpoint，会拖慢甚至卡死；分片读取、错峰保存、使用本地缓存。
• 容器 IPC/网络配置：--ipc=host、共享内存、IB 设备、网络模式要满足 NCCL 要求；K8s 里检查 device plugin 和 CNI。

相关命令

• nccl-tests — 先验证通信带宽与正确性。
• nsys — 看训练时间线、通信与数据加载空档。
• ncu — 单 kernel 性能下钻。
• fsdp — 分片训练配置。
• torchrun — 分布式启动参数。
• slurm — 集群作业与 GPU 分配。

参考链接

• PyTorch 分布式训练文档
• NCCL 故障排查
• PyTorch 分布式排障指南

读完自测

合上页面，先回答，再展开对照。

1. 分布式训练挂起时，第一步应该做什么？
2. NCCL_DEBUG=INFO 主要能帮助定位什么？
3. 容器里训练卡住，为什么要检查 /dev/shm？