LLM 训练故障排查手册：30 个真实案例与解决方案

千卡集群训练，故障是常态。本文汇总 30 个真实案例，帮你快速定位和解决。

---

一、NCCL 通信问题（最高发）

案例 1：NCCL 超时

现象： 训练中途报错 "NCCL watchdog timeout"

排查步骤：

检查网络连接：ibstat 看 IB 状态

确认 GPU 拓扑：nvidia-smi topo -m

查看 NCCL 日志：NCCL_DEBUG=INFO

解决方案：

bash
# 增加超时时间
export NCCL_TIMEOUT=3600

# 关闭 P2P（某些场景）
export NCCL_P2P_DISABLE=1

# 调整 socket 缓冲区
export NCCL_SOCKET_BUFFSIZE=262144

案例 2：多机训练卡住

现象： 单机正常，多机训练卡在第一步

原因： 防火墙阻止 NCCL 通信

解决： 开放 NCCL 端口（默认 30000+）

bash
# 确认主节点 IP
export NCCL_SOCKET_IFNAME=eth0

# 指定端口范围
export NCCL_NET_PLUGIN=none

---

二、显存问题

案例 3：OOM 错误

现象： "CUDA out of memory"

排查：

python
print(f"Allocated: {torch.cuda.memory_allocated()/1e9:.2f}GB")
print(f"Max allocated: {torch.cuda.max_memory_allocated()/1e9:.2f}GB")

解决方案（按优先级）：

减小 batch size

启用梯度累积

启用混合精度

使用 ZeRO-3

启用激活重计算

案例 4：显存泄漏

现象： 显存使用持续增长

排查：

python
import gc
gc.collect()
torch.cuda.empty_cache()

常见原因：

• 未 detach 的 tensor 被保留
• 循环中累积 loss（要用 loss.item()）
• 数据加载器未正确释放

---

三、梯度问题

案例 5：梯度爆炸

现象： loss 突然飙升到 NaN

解决：

python
# 梯度裁剪
torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm=1.0)

# 检查梯度
for name, param in model.named_parameters():
    if param.grad is not None:
        print(f"{name}: {param.grad.norm()}")

案例 6：梯度不更新

现象： loss 不下降，参数不变

排查：

python
# 检查 requires_grad
for name, param in model.named_parameters():
    print(f"{name}: {param.requires_grad}")

# 检查 optimizer 参数
print(optimizer.param_groups[0]['params'])

常见原因：

• 参数 requires_grad=False
• optimizer 未包含所有参数
• 忘记调用 optimizer.step()

---

四、数据问题

案例 7：数据加载慢

现象： GPU 利用率低（<50%）

解决：

python
dataloader = DataLoader(
    dataset,
    num_workers=8,
    pin_memory=True,
    prefetch_factor=2,
    persistent_workers=True
)

案例 8：数据分布不均

现象： 某些 batch loss 异常高

排查：

python
# 检查序列长度分布
lengths = [len(x) for x in dataset]
print(f"Min: {min(lengths)}, Max: {max(lengths)}, Mean: {sum(lengths)/len(lengths)}")

解决： 按长度排序或分桶

---

五、分布式训练问题

案例 9：多机不同步

现象： 各卡 loss 不一致

原因： 随机种子未统一

解决：

python
import random
import numpy as np
import torch

seed = 42
random.seed(seed)
np.random.seed(seed)
torch.manual_seed(seed)
torch.cuda.manual_seed_all(seed)

案例 10：主节点挂掉

现象： rank 0 崩溃，全部重启

解决： 启用弹性训练（Elastic Training）

bash
torchrun --nnodes=1:8 --nproc_per_node=8 train.py

---

六、快速排查清单

训练前检查：

• [ ] GPU 状态正常（nvidia-smi）
• [ ] NCCL 测试通过（nccl-tests）
• [ ] 显存充足
• [ ] 数据可访问
• [ ] 随机种子设置

训练中监控：

• [ ] GPU 利用率 > 80%
• [ ] 显存使用稳定
• [ ] loss 正常下降
• [ ] 梯度范数正常（0.1-10）

故障时排查：

看报错信息（最后一行）

查日志（NCCL_DEBUG=INFO）

监控数据（nvidia-smi, nvtop）

最小复现（单卡单数据）

---

七、学习大鳄的经验

"80% 的训练故障是通信和数据问题，15% 是显存问题，5% 是代码 bug。按这个顺序排查，效率最高。"

必备工具：

• nvidia-smi / nvtop（GPU 监控）
• NCCL_DEBUG=INFO（通信调试）
• PyTorch Profiler（性能分析）
• WandB（训练监控）

---

*生成时间：2026-04-05 | 模板：故障排查 | 学习大鳄出品*