PyTorch分布式训练为何报错

PyTorch 分布式训练报错的原因非常多，不同错误对应不同根因。下面我按最常见报错类型帮你系统梳理，并给出排查思路和解决方式。。

一、初始化相关报错（最常见）

1️⃣ RuntimeError: Address already in use

原因：MASTER_PORT 被占用
✅ 解决：

export MASTER_PORT=29501

或

dist.init_process_group(
backend="nccl",
init_method="tcp://localhost:29501",
rank=rank,
world_size=world_size
)

2️⃣ ValueError: Error initializing torch.distributed

原因：

• init_process_group 调用了两次
• backend 不支持（CPU 用 gloo，GPU 用 nccl）

✅ 解决：

backend = "nccl" if torch.cuda.is_available() else "gloo"

二、NCCL 相关报错（GPU 训练高频）

3️⃣ NCCL Error: unhandled system error

常见原因：

• 多卡不在同一 NUMA 节点
• 驱动 / CUDA / NCCL 版本不兼容
• Docker 没开 GPU 权限

✅ 排查：

nvidia-smi
nvidia-smi topo -m

✅ 解决：

export NCCL_DEBUG=INFO
export NCCL_P2P_DISABLE=1

4️⃣ CUDA error: invalid device ordinal

原因：

• local_rank 没正确传入
• 使用了错误 GPU

✅ 正确写法：

torch.cuda.set_device(local_rank)
model = model.to(local_rank)

三、多进程 / 启动方式问题

5️⃣ ValueError: too many values to unpack

原因：launch 参数没传 local_rank
✅ 正确启动：

torchrun --nproc_per_node=4 train.py

或：

python -m torch.distributed.launch --nproc_per_node=4 train.py

✅ 代码中：

local_rank = int(os.environ["LOCAL_RANK"])

四、模型 / 数据并行问题

6️⃣ RuntimeError: Expected to have finished reduction in the prior iteration

原因：

• loss.backward() 前模型不是 DDP
• 有参数未参与 loss

✅ 解决：

model = DistributedDataParallel(model, device_ids=[local_rank])

并确认：

loss = loss.mean()
loss.backward()

7️⃣ DataLoader worker error

原因：

• num_workers > 0 + fork
• 多进程死锁

✅ 解决：

DataLoader(..., num_workers=4, persistent_workers=True)

或在 if __name__ == "__main__": 中启动

五、环境变量缺失

8️⃣ KeyError: MASTER_ADDR / MASTER_PORT

原因：手动启动没设环境变量
✅ 设置：

export MASTER_ADDR=127.0.0.1
export MASTER_PORT=29500

六、快速自查清单 ✅

训练前请确认：

• [ ] 使用 torchrun 或 launch
• [ ] init_process_group 只调用一次
• [ ] GPU 用 nccl，CPU 用 gloo
• [ ] local_rank 来自环境变量
• [ ] 模型用 DDP 包裹
• [ ] loss 是标量

七、如果你愿意，我可以直接帮你定位

你可以贴出：

1. 完整报错信息
2. 启动命令
3. 训练代码关键部分（init / DDP / launch）

我可以直接告诉你是哪一行导致的，以及怎么改。