如何调试分布式训练错误 - GPU

调试分布式训练错误通常需要从环境配置、通信、数据、模型、日志等多个维度入手。下面我按常见错误类型 → 排查步骤 → 实战技巧给你一个系统性的指南。

一、先明确：错误发生在哪一类？

分布式训练错误通常分为 5 类：

环境 / 启动问题
通信错误（NCCL / Gloo / MPI）
数据与采样问题
模型与梯度问题
资源与性能问题

二、环境与启动问题（最常见）

1. 单机多卡启动失败

典型报错

RuntimeError: No devices were found
CUDA error: invalid device ordinal

排查步骤

nvidia-smi          # 看 GPU 数量
echo $CUDA_VISIBLE_DEVICES

✅ 检查：

CUDA_VISIBLE_DEVICES 是否设置正确
是否和启动脚本中 local_rank 对应
PyTorch / CUDA 版本是否匹配

正确启动方式

# PyTorch DDP
torchrun --nproc_per_node=4 train.py
# 老版本
python -m torch.distributed.launch --nproc_per_node=4 train.py

三、通信错误（NCCL / Gloo）

1. NCCL 报错（最常见）

典型报错

NCCL error: unhandled system error
NCCL WARN ... timeout

排查清单
✅ 1. 是否多机？

多机：检查 网络、端口、防火墙
单机：通常是 GPU / CUDA 问题

✅ 2. 设置 NCCL 调试信息

export NCCL_DEBUG=INFO
export NCCL_DEBUG_SUBSYS=ALL

✅ 3. 常见原因

CUDA / NCCL 版本不兼容
GPU 被其他进程占用
IB / RDMA 配置错误（多机）

✅ 4. 强制使用 Gloo（调试用）

dist.init_process_group(backend="gloo")

四、数据与采样问题（容易忽略）

1. 数据不一致导致 loss 爆炸 / NaN

检查点

dist.get_rank()
dist.get_world_size()

✅ 每个 rank 是否：

看到不同的数据？
DataLoader 是否设置了不同 seed？

✅ 正确做法：

sampler = DistributedSampler(
dataset,
num_replicas=world_size,
rank=rank,
shuffle=True
)

⚠️ 不要同时设置

DataLoader(shuffle=True, sampler=sampler)  # ❌

五、模型与梯度问题

1. 忘记用 DDP 包装模型

❌ 错误

model = MyModel()

✅ 正确

model = MyModel().to(local_rank)
model = DDP(model, device_ids=[local_rank])

2. 梯度未同步 / loss 不一致

排查

for name, param in model.named_parameters():
print(rank, name, param.grad)

✅ 检查：

是否有 detach()
是否有未参与 loss 的参数
是否使用了 find_unused_parameters=True

DDP(model, find_unused_parameters=True)

3. BatchNorm 问题

✅ 推荐：

model = torch.nn.SyncBatchNorm.convert_sync_batchnorm(model)

否则：

BN 只在单卡计算
validation 结果异常

六、日志与调试技巧（非常重要）

1. 每个 rank 单独写日志

log_file = f"log_rank{rank}.txt"

2. 打印关键信息

print(rank, "batch size:", len(batch))
print(rank, "loss:", loss.item())

3. 先跑单卡再跑多卡

✅ 调试顺序：

单卡 → 单机多卡 → 多机

七、常见错误速查表

错误现象	可能原因
loss 为 NaN	学习率、数据、BN
卡住不动	NCCL / 多机网络
loss 不一致	sampler / seed
显存爆	batch size / DDP
多机失败	端口 / 防火墙

八、推荐调试模板

import os
import torch
import torch.distributed as dist
dist.init_process_group("nccl")
rank = dist.get_rank()
print(f"Rank {rank} ready")
# 每个 rank 单独日志

九、如果你愿意，我可以进一步帮你

你可以直接贴出：

❌ 完整报错
✅ 使用的框架（PyTorch / TF / DeepSpeed / Megatron）
✅ 单卡 / 多卡 / 多机
✅ GPU 数量和模型规模

我可以帮你 精确定位错误并给出修改代码。