单卡训练为何误入 DDP:一次 Ultralytics Default process group has not been initialized 故障复盘
单卡训练为何误入 DDP:一次 Ultralytics Default process group has not been initialized 故障复盘
日期:2026-11-18 环境:Windows 11、PowerShell、Python 3.9、PyTorch 2.0.1 + CUDA 11.8、Ultralytics 8.3.222、NVIDIA RTX 4060 8GB
一、问题背景
在一个无人机俯视车辆检测项目中,我们需要用自有数据集继续训练 YOLO26m。训练配置明确指定单张 GPU:
train:
device: 0
batch: 4
imgsz: 1280
amp: false
classes: [0, 4, 5]
其中只训练原始标签中的 car、truck、bus 三类。由于当前 YOLO26m 权重对 FP16 较敏感,因此关闭了 AMP。
训练启动后,模型、数据集和 GPU 都能被正常识别:
Ultralytics 8.3.222
Python-3.9.21 torch-2.0.1+cu118
CUDA:0 (NVIDIA GeForce RTX 4060, 8188MiB)
classes=[0, 4, 5], amp=False, device=0
模型也完成了类别头调整和预训练权重迁移:
Overriding model.yaml nc=80 with nc=6
Transferred 756/768 items from pretrained weights
数据集扫描同样成功:
train: Scanning ... 3982 images, 0 backgrounds, 0 corrupt
train: New cache created: ...\labels\train.cache
但就在进入第一个 epoch 前,程序突然退出:
RuntimeError: Default process group has not been initialized,
please make sure to call init_process_group.
这类错误很容易让人误以为是 YOLO26、显存、数据集缓存或 Windows 多进程导致的。实际上,它们都不是根因。
二、从 traceback 还原真实调用链
完整 traceback 的核心路径如下:
model.train()
-> trainer.train()
-> trainer._do_train()
-> trainer._setup_train()
-> get_dataloader(..., rank=LOCAL_RANK)
-> build_dataloader(...)
-> torch.utils.data.distributed.DistributedSampler(...)
-> dist.get_world_size()
-> _get_default_group()
-> RuntimeError: Default process group has not been initialized
关键点是:一个明确配置为单 GPU 的训练任务,竟然创建了 DistributedSampler。
Ultralytics 的数据加载器会根据 rank 决定使用哪种 sampler。逻辑可以简化为:
sampler = (
None
if rank == -1
else DistributedSampler(dataset, shuffle=shuffle)
)
单进程、单 GPU 模式下,rank 应当是 -1,此时使用普通的 RandomSampler。只有真正由 torchrun 启动的分布式训练,rank 才应当是 0、1、2...。
继续检查 Ultralytics 的常量定义:
RANK = int(os.getenv("RANK", -1))
LOCAL_RANK = int(os.getenv("LOCAL_RANK", -1))
于是问题变得非常清楚:Ultralytics 在导入时读取到了一个不该存在的 LOCAL_RANK。
三、根因:残留的 LOCAL_RANK=0
在出错的 PowerShell 环境中检查分布式相关变量:
$names = "RANK", "LOCAL_RANK", "WORLD_SIZE", "MASTER_ADDR", "MASTER_PORT"
foreach ($name in $names) {
Get-Item ("Env:" + $name) -ErrorAction SilentlyContinue
}
结果为:
RANK=<unset>
LOCAL_RANK=0
WORLD_SIZE=<unset>
MASTER_ADDR=<unset>
MASTER_PORT=<unset>
这是一组不完整且自相矛盾的分布式环境:
LOCAL_RANK=0告诉 Ultralytics:“当前是一个分布式训练子进程”;- 但程序并非由
torchrun启动; RANK、WORLD_SIZE、MASTER_ADDR、MASTER_PORT均未正确设置;- PyTorch 没有执行
torch.distributed.init_process_group()。
因此,Ultralytics 根据 LOCAL_RANK=0 创建了 DistributedSampler,而 DistributedSampler 初始化时会调用 dist.get_world_size()。此时默认进程组不存在,于是抛出异常。
可以把整个问题概括为:
残留 LOCAL_RANK=0
↓
Ultralytics 在 import 时误判为 DDP
↓
单卡 DataLoader 使用 DistributedSampler
↓
DistributedSampler 查询 world size
↓
默认分布式进程组未初始化
↓
训练在第一个 epoch 前失败
四、为什么排查时容易走弯路
1. 报错出现在数据扫描之后
日志最后显示的是 train.cache 创建成功,很容易怀疑数据集缓存损坏。但 traceback 表明异常发生在 cache 之后的 sampler 构造阶段,缓存并不是根因。
2. YOLO26m 的确有额外兼容性约束
该权重需要匹配指定的 Ultralytics 版本,并使用 FP32。配置里已经正确设置 amp: false,模型也以 end-to-end 模式加载成功。这些要求与本次 DDP 异常没有直接关系。
3. device: 0 不足以覆盖环境变量
很多人认为设置 device=0 就一定会进入单卡模式,但 Ultralytics 还会在模块导入时读取 LOCAL_RANK。如果环境变量与命令参数冲突,残留的分布式变量仍可能改变内部数据加载逻辑。
五、修复方案
第一层:在 PowerShell 启动器中清理环境
在启动 Python 前清理可能残留的 torchrun 变量:
foreach ($DistributedVar in @(
"RANK",
"LOCAL_RANK",
"WORLD_SIZE",
"MASTER_ADDR",
"MASTER_PORT"
)) {
Remove-Item ("Env:" + $DistributedVar) -ErrorAction SilentlyContinue
}
这样,子进程导入 Ultralytics 时会得到默认值:
LOCAL_RANK == -1
第二层:在 Python 入口中做防御性清理
只依靠 PowerShell 脚本还不够,因为开发者可能绕过启动器,直接运行 python train.py。因此在导入 Ultralytics 前再做一次保护:
DDP_ENV_VARS = (
"RANK",
"LOCAL_RANK",
"WORLD_SIZE",
"MASTER_ADDR",
"MASTER_PORT",
)
def prepare_single_process_environment(device):
if isinstance(device, (list, tuple)):
single_device = len(device) <= 1
else:
single_device = "," not in str(device).strip()
if not single_device:
return []
removed = [name for name in DDP_ENV_VARS if name in os.environ]
for name in DDP_ENV_VARS:
os.environ.pop(name, None)
return removed
调用位置必须在导入 Ultralytics 之前:
removed = prepare_single_process_environment(train_config.get("device", 0))
if removed:
print(f"[ENV] cleared stale distributed variables: {removed}")
from ultralytics import YOLO
“导入之前”非常重要,因为 Ultralytics 的 LOCAL_RANK 是模块级常量,导入完成后再修改环境变量通常已经太晚。
为什么要做两层保护
- PowerShell 层保证标准启动路径干净;
- Python 层保证直接调用也安全;
- 两层都只针对单设备配置;
- 如果配置为
device: 0,1等多设备模式,则不清理变量,避免破坏合法 DDP。
六、如何验证修复有效
1. 防回归单元测试
人为注入错误环境,再调用清理函数:
stale = {"LOCAL_RANK": "0", "RANK": "0", "WORLD_SIZE": "1"}
with mock.patch.dict(os.environ, stale, clear=False):
removed = prepare_single_process_environment(0)
assert set(stale).issubset(removed)
assert all(name not in os.environ for name in stale)
2. 验证 Ultralytics 的 sampler 选择
清理后,用内存数据集构建 DataLoader,实际结果为:
LOCAL_RANK -1
SAMPLER RandomSampler
DIST_INITIALIZED False
DATALOADER_FIX_OK
这个结果直接证明:
- Ultralytics 不再认为当前进程属于 DDP;
- 单卡训练使用普通
RandomSampler; - 即使分布式进程组未初始化,也不会再触发原异常。
3. 重新启动训练
由于失败的运行目录会被保留用于审计,应使用新的 RunId:
.\run_train.ps1 `
-Config configs\train_yolo26m.yaml `
-RunId yolo26m_exp02
保留失败目录是个好习惯:原始配置、manifest 和 traceback 可以用于比较修复前后的行为,而不必覆盖证据。
七、哪些日志不是错误
本次日志里还有几条容易引起误解的信息:
Creating new Ultralytics Settings
New cache created: ...\labels\train.cache
Overriding model.yaml nc=80 with nc=6
Transferred 756/768 items from pretrained weights
它们都属于正常行为:
Creating new Ultralytics Settings:首次在指定配置目录启动;New cache created:建立标签索引以加速后续训练;nc=80 with nc=6:将 COCO 预训练模型的分类头适配到数据集声明的 6 个原始类别;Transferred 756/768:除分类头等形状不同的参数外,其余预训练参数成功迁移。
虽然数据集声明了 6 类,但训练参数 classes=[0,4,5] 会过滤标签,只让 car、truck、bus 参与训练。这也不是本次异常的来源。
八、如果确实要做多卡训练
本文的修复针对“单卡任务被残留变量误判为 DDP”。真正的多卡训练不能简单清除环境变量后直接运行,而应由 Ultralytics 或 torchrun 正确创建多个进程并初始化进程组,例如:
torchrun --nproc_per_node=2 train.py --device 0,1 ...
合法的 DDP 环境应同时具备一致的 RANK、LOCAL_RANK、WORLD_SIZE、MASTER_ADDR、MASTER_PORT,并确保每个进程完成 init_process_group()。
核心原则是:
- 单卡训练:
LOCAL_RANK=-1,不使用DistributedSampler; - 多卡训练:由分布式启动器完整初始化,不能只手工设置一个
LOCAL_RANK。
九、复盘与经验总结
这次问题最有价值的经验,不是记住某一条报错,而是建立一套排查路径:
- 不要只看日志最后一行,要沿 traceback 找到第一个“行为异常”的组件;
- 配置参数正确不代表进程环境正确,环境变量也会改变框架行为;
- 分布式错误优先检查
RANK、LOCAL_RANK、WORLD_SIZE、MASTER_*; - 对在 import 时读取的环境变量,修复必须发生在 import 之前;
- 启动脚本负责清理环境,Python 入口负责防御性校验;
- 修复后应验证真正的分支行为,例如确认 sampler 类型,而不只验证“异常没有出现”;
- 失败运行目录应保留,新实验使用新 RunId,保证过程可追溯。
最终,这个看起来像 PyTorch 分布式初始化失败的问题,本质上只是一个残留环境变量造成的模式误判。定位清楚调用链后,修复并不复杂;真正重要的是把修复放在正确的时机,并通过 sampler 类型验证框架确实走回了单卡路径。

浙公网安备 33010602011771号