PyTorch分布式训练卡住不动？手把手教你排查torch.distributed.launch的5个常见坑
PyTorch分布式训练卡住不动？手把手教你排查torch.distributed.launch的5个常见坑
当你第一次尝试在多个GPU或多个节点上运行PyTorch分布式训练时，最令人沮丧的莫过于看到程序卡在初始化阶段，既不报错也不继续执行。这种情况我遇到过太多次了——盯着终端上闪烁的光标，不知道是该继续等待还是强制终止。经过无数次调试和踩坑，我总结出了五个最常见的导致分布式训练卡住的原因，以及一套系统化的排查方法。
1. 网络连接问题：分布式训练的第一道坎
分布式训练的核心在于不同节点间的通信，而网络配置错误是最常见的"卡住"元凶。记得有一次，我们的训练脚本在两台机器上都能单独运行，但一旦尝试分布式就卡死。折腾了大半天才发现是防火墙设置的问题。
1.1 检查节点间网络连通性
首先确认所有节点之间能够互相ping通。在每台机器上执行：
ping <其他节点的IP地址>如果ping不通，检查网络配置和防火墙设置。特别要注意云环境中的安全组规则。
1.2 验证端口可访问性
分布式训练需要特定端口进行通信。使用telnet或nc检查端口是否开放：
telnet <MASTER_ADDR> <MASTER_PORT> # 或 nc -zv <MASTER_ADDR> <MASTER_PORT>如果连接失败，可能是端口被防火墙拦截或已被占用。
1.3 典型网络问题排查表
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| 节点间无法ping通 | 网络配置错误/防火墙阻止 | 检查IP配置，关闭防火墙或添加规则 |
| 能ping通但端口不可达 | 端口被防火墙拦截 | 开放指定端口或更换端口 |
| 连接时断时续 | 网络不稳定 | 检查网络设备，考虑使用更稳定的网络协议 |
| 只有部分节点能连接 | 安全组规则不一致 | 统一所有节点的安全组/防火墙规则 |
提示：在云环境中，除了实例本身的防火墙，还要检查云服务商的安全组设置。
2. MASTER_ADDR和MASTER_PORT配置错误
这两个参数的配置错误是新手最容易踩的坑。我曾经因为MASTER_ADDR设置错误浪费了一整个下午。
2.1 MASTER_ADDR的正确设置
MASTER_ADDR应该设置为rank 0节点(主节点)的IP地址。常见错误包括：
- 在所有节点上使用localhost或127.0.0.1
- 使用了错误的IP地址(如内网IP与外网IP混淆)
- 主机名解析问题(最好直接使用IP而非主机名)
2.2 MASTER_PORT的选择
端口选择也有讲究：
- 避免使用知名端口(0-1023)
- 确保端口未被其他服务占用
- 所有节点必须使用相同的端口号
- 考虑端口是否被防火墙允许
检查端口占用的方法：
netstat -tuln | grep <端口号> # 或 lsof -i :<端口号>2.3 环境变量验证技巧
在训练脚本开头添加以下代码，打印环境变量验证配置：
import os print("MASTER_ADDR:", os.environ.get('MASTER_ADDR')) print("MASTER_PORT:", os.environ.get('MASTER_PORT')) print("WORLD_SIZE:", os.environ.get('WORLD_SIZE')) print("RANK:", os.environ.get('RANK')) print("LOCAL_RANK:", os.environ.get('LOCAL_RANK'))3. nnodes与实际节点数不匹配
这个错误相当隐蔽——当你在启动时指定的nnodes与实际运行的节点数不一致时，程序会一直等待缺失的节点加入。
3.1 典型场景分析
假设你设置--nnodes=2但只启动了一个节点，或者第二个节点由于配置错误未能成功加入。PyTorch会一直等待第二个节点连接，导致看起来像是卡住了。
3.2 解决方案
- 确保
--nnodes参数与实际参与训练的节点数一致 - 每个节点的
--node_rank必须唯一且从0开始连续 - 所有节点上的
--nnodes值必须相同
3.3 节点启动顺序建议
为了避免竞争条件，建议按照以下顺序启动节点：
- 首先启动rank 0节点(主节点)
- 等待主节点完全启动后，再依次启动其他节点
- 可以在主节点上添加简单的日志，确认它已准备好接收连接
4. 多机环境变量未正确传递
在多机环境中，环境变量的传递经常出问题，特别是当通过某些作业调度系统提交任务时。
4.1 必须传递的环境变量
以下环境变量必须正确传递到所有进程：
- MASTER_ADDR
- MASTER_PORT
- WORLD_SIZE
- RANK
- LOCAL_RANK
4.2 使用--use_env的正确姿势
在较新版本的PyTorch中，推荐使用--use_env参数，让launch脚本自动处理环境变量：
python -m torch.distributed.launch --nproc_per_node=4 --nnodes=2 --node_rank=0 --master_addr=192.168.1.100 --master_port=29500 --use_env train.py4.3 环境变量检查清单
在代码中验证环境变量是否设置正确：
def validate_env_vars(): required_vars = ['MASTER_ADDR', 'MASTER_PORT', 'WORLD_SIZE', 'RANK', 'LOCAL_RANK'] for var in required_vars: if var not in os.environ: raise RuntimeError(f"环境变量{var}未设置!") print(f"{var}: {os.environ[var]}")5. PyTorch版本差异与API变更
PyTorch的分布式API在不同版本间有所变化，这也是导致问题的常见原因。
5.1 launch.py与torchrun的演进
- PyTorch 1.x: 使用
torch.distributed.launch - PyTorch 2.0+: 推荐使用
torchrun(向后兼容)
新版本的推荐命令：
torchrun --nproc_per_node=4 --nnodes=2 --node_rank=0 --master_addr=192.168.1.100 --master_port=29500 train.py5.2 版本兼容性处理技巧
在代码中添加版本检查逻辑：
import torch if torch.__version__ >= '2.0.0': # 使用新API else: # 兼容旧版本5.3 常见版本问题及解决方案
| 问题现象 | 影响版本 | 解决方案 |
|---|---|---|
| 缺少--use_env报错 | PyTorch 2.0+ | 添加--use_env或改用torchrun |
| launch.py弃用警告 | PyTorch 2.0+ | 迁移到torchrun |
| NCCL版本不兼容 | 多种版本 | 确保所有节点使用相同版本的NCCL |
系统化排查流程
当分布式训练卡住时，按照以下步骤排查：
- 检查网络连接：确认节点间可以互相通信
- 验证端口可用性：确保指定端口未被占用且可访问
- 检查环境变量：确认所有必要环境变量正确设置
- 验证节点配置：确保nnodes和node_rank设置正确
- 检查PyTorch版本：确认所有节点使用相同版本的PyTorch
调试技巧与工具
日志记录建议
在训练脚本中添加详细日志，特别是在初始化阶段：
import logging logging.basicConfig(level=logging.INFO) logger = logging.getLogger(__name__) logger.info(f"开始初始化进程组，rank={rank}") dist.init_process_group(backend='nccl') logger.info("进程组初始化成功")NCCL调试
NCCL是PyTorch分布式常用的后端，可以启用其调试日志：
export NCCL_DEBUG=INFO export NCCL_DEBUG_SUBSYS=ALL小型测试脚本
创建一个最小化的测试脚本，排除模型代码的影响：
import torch import torch.distributed as dist import os def main(): dist.init_process_group('nccl') rank = dist.get_rank() print(f"Rank {rank} 初始化成功") dist.barrier() print(f"Rank {rank} 通过barrier") dist.destroy_process_group() if __name__ == "__main__": main()分布式训练虽然初期配置复杂，但一旦掌握了这些排查技巧，就能快速定位和解决问题。记住，当程序卡住时，不要盲目等待——系统化地检查每个环节，你一定能找到问题的根源。