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 以處理網格配置問題。