在GCP用4GPU训练Detectron2出现MASTER_ADDR未设置ValueError如何解决

错误含义 #

这个报错是因为多GPU分布式训练需要PyTorch分布式框架做通信协调，而框架依赖MASTER_ADDR（主节点IP地址）和MASTER_PORT（主节点通信端口）这两个环境变量来建立GPU间的连接，但当前这两个变量未被设置。单GPU训练不需要跨GPU通信，所以不会触发这个检查。

解决方法 #

方法1：使用Detectron2官方推荐的启动方式（优先选择） #

直接通过终端调用官方的分布式启动脚本，它会自动配置好所有需要的环境变量：

# 方式A：用PyTorch自带的分布式启动工具
python -m torch.distributed.launch --nproc_per_node=4 你的训练脚本.py

# 方式B：用Detectron2内置的launch工具
python detectron2/engine/launch.py --num_gpus=4 你的训练脚本.py

注意：不要在脚本里再手动写launch(main, num_gpus_per_machine=4)，保持训练脚本的main函数逻辑即可。

方法2：手动设置环境变量（仅用于特殊场景） #

如果必须在代码内调用launch函数，需要在代码开头手动设置环境变量：

import os
# 本地训练用127.0.0.1即可
os.environ.setdefault("MASTER_ADDR", "127.0.0.1")
# 选一个未被占用的端口，比如29500
os.environ.setdefault("MASTER_PORT", "29500")

if __name__ == "__main__":
    launch(main, num_gpus_per_machine=4)

额外检查 #

确保GCP实例的GPU环境正常：

• 运行nvidia-smi确认4块GPU都被识别
• 确认PyTorch版本与CUDA驱动版本匹配，torch.cuda.is_available()返回True

内容的提问来源于stack exchange，提问作者Nitya Rakhe