debug-distributed

此技能为 AReaL 基础设施内的分布式训练问题提供系统化的诊断与解决框架。专为使用 FSDP2、张量并行 (TP)、上下文并行 (CP) 与专家并行 (EP) 的机器学习工程师与研究人员设计。本指南协助用户在训练挂起、死锁、各节点结果不一致，或遇到 CUDA 显存溢出 (OOM) 与 NCCL 通讯错误时进行故障排除。

• 最小化复现原则：提供利用较小张量大小与减少运算节点数来隔离故障的操作技巧，以加速根因分析。

• 挂起与死锁解决方案：针对进程停滞的详细分析步骤，包含启用 TORCH_DISTRIBUTED_DEBUG 与 NCCL_DEBUG_SUBSYS 环境变量，并使用 py-spy 生成火焰图或导出挂起进程的调用栈。

• 数值一致性诊断：用于验证 DTensor 配置、检查各节点梯度聚合，以及识别集合通信或进程组不匹配的工具。

• 显存优化与 OOM 管理：监控 CUDA 显存使用情况并验证 FSDP 分片覆盖范围的方法，以预防显存溢出错误。

• 通讯错误故障排除：提供常见 NCCL 与设备网格配置错误的对照表，将特定异常对应至可操作的修复步骤。

• 务必从建立最小化复现脚本开始，而非直接在完整训练循环中进行调试，以减少变量。

• 利用节点条件打印与屏障同步 (barrier) 来验证整个训练集群中的张量形状与设备网格成员身份。

• 若需性能分析，使用 py-spy 捕捉火焰图，并确保截取时间足以产生具代表性的数据。

• 处理与 torch.compile 或复杂图执行相关的问题时，确保正确设置 TORCH_LOGS=+dynamo,recompiles 等环境变量。

• 参考提供的关键文件列表以导航 AReaL 内部架构，特别是检查 parallel_dims.py 以处理网格配置问题。