Loading

单卡训练为何误入 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。

九、复盘与经验总结

这次问题最有价值的经验,不是记住某一条报错,而是建立一套排查路径:

  1. 不要只看日志最后一行,要沿 traceback 找到第一个“行为异常”的组件;
  2. 配置参数正确不代表进程环境正确,环境变量也会改变框架行为;
  3. 分布式错误优先检查 RANK、LOCAL_RANK、WORLD_SIZE、MASTER_*;
  4. 对在 import 时读取的环境变量,修复必须发生在 import 之前;
  5. 启动脚本负责清理环境,Python 入口负责防御性校验;
  6. 修复后应验证真正的分支行为,例如确认 sampler 类型,而不只验证“异常没有出现”;
  7. 失败运行目录应保留,新实验使用新 RunId,保证过程可追溯。

最终,这个看起来像 PyTorch 分布式初始化失败的问题,本质上只是一个残留环境变量造成的模式误判。定位清楚调用链后,修复并不复杂;真正重要的是把修复放在正确的时机,并通过 sampler 类型验证框架确实走回了单卡路径。

posted @ 2026-11-18 15:35  SaTsuki26681534  阅读(7)  评论(0)    收藏  举报