Skip to content

弹性训练与容错:torchrun elastic 的 rendezvous、重启语义与状态恢复 ​

训练跑到第 3 天,64 张卡里有一张报了 ECC 错误,进程退出。多数人的直觉是"torchrun 会把这台机器换掉、从上一个 checkpoint 接着跑"。实际发生的是:整个 worker group 被立即杀掉,作业直接终止——因为 --max-restarts 的默认值是 0。

弹性训练常被误解成"自动续跑"。它不是。它做的是三件事:检测成员变化、把所有存活 worker 一起重启、重新组一个 worker group。至于"从哪一步接着跑",框架不管,得由你的脚本从 checkpoint 里恢复。这篇把这个边界讲清楚:谁重启、重启后哪些量会变、状态里必须存什么、出问题按什么判据查。

一、重启的单位是 worker group,不是单个进程 ​

官方对失败模式的描述只有三条,但每条都决定你的运维动作:

失败类型官方行为对你的含义
Worker 失败n 个 worker 中 k≤n 个失败,所有 worker 被停止并重启,最多重启 max_restarts 次单卡 OOM 也会让整组重来,不是热替换
Agent 失败本机 worker group 失败,由作业管理器决定 gang 终止还是替换节点torchrun 不替你决定,Slurm/K8s 才决定
节点失败与 agent 失败同构节点掉线等价于该机 agent 消失

再加一条容易被忽略的硬约束:发生失败或成员变化时,所有存活 worker 会被立即杀掉,不做优雅退出。所以"失败瞬间正在写的 checkpoint"很可能只写了一半——这一点决定了后面第六节的成功判据。

二、重启后 rank 和 world size 都不可信 ​

torchrun 的术语里,一个 node 上跑 LOCAL_WORLD_SIZE 个 worker,构成一个 LocalWorkerGroup;所有节点的 LocalWorkerGroup 并起来才是 WorkerGroup。弹性语义下有两个官方明示的警告:

  • RANK 不稳定:两次重启之间,同一台机器上的 worker 可能拿到完全不同的 rank 区间,任何"rank 7 一定在 node 3 上"的假设都会失效。
  • WORLD_SIZE 会变:--nnodes=min:max 且 min≠max 时,节点可以加入或离开,world size 随之改变,代码里不能写死。
变量含义何时会变
RANKworker 在 worker group 内的全局序号每次重新 rendezvous
LOCAL_RANK本机内的序号,通常等于 GPU 序号一般稳定,但不要当全局身份
WORLD_SIZEworker group 总 worker 数弹性伸缩时
GROUP_RANKworker group 的序号(0..max_nnodes)多 worker group/节点时
TORCHELASTIC_RESTART_COUNT已发生的 worker group 重启次数每次重启 +1
TORCHELASTIC_MAX_RESTARTS配置的上限由 --max-restarts 决定
TORCHELASTIC_RUN_ID本次作业的 rendezvous run id与 --rdzv-id 一致

实践含义:凡是写进日志、写进文件名、写进外部系统的"身份",用 TORCHELASTIC_RUN_ID + step,而不是 rank。rank 只用于当次运行内选设备。

三、八个参数的真实默认值,解释了大部分"没生效" ​

以下默认值取自 PyTorch v2.11.0 的 torch/distributed/run.py 解析器定义(不是记忆):

参数默认值关键含义
--nnodes1:1写成 min:max 才具备弹性;min 必须 >0 且 ≤max,否则直接断言失败
--nproc-per-node1可写 auto/cpu/gpu/xpu 或整数;写 gpu 才是"每卡一进程"
--rdzv-backendstatic默认不是 c10d!static 只按 --node-rank 组固定成员,无弹性
--rdzv-endpoint空static 下回落到 master_addr:master_port;c10d 下必须显式给 host:port
--rdzv-idnone同 id 的节点才会join 同一个 worker group
--max-restarts0默认不重启,这就是"整组退出"的直接原因
--monitor-interval0.1(秒)agent 轮询 worker 状态的间隔
--start-methodspawn可选 fork/forkserver;与 CUDA 上下文的安全性相关
--master-addr / --master-port127.0.0.1 / 29500只对 static rendezvous 有效,非 static 时给了会被警告忽略
--standalone关打开后强制 rdzv-backend=c10d、rdzv-endpoint=localhost:0、rdzv-id=<uuid>,显式给的值被覆盖

由此可直接推出三个常见病症的病因:

  1. "我配了 4 次重启怎么还是退出"——如果用了 --standalone,rdzv-id 与 endpoint 被覆盖,但 max_restarts 不被覆盖;如果没显式写 --max-restarts,它就是 0。
  2. "写了 --nnodes=1:4 还是不能伸缩"——--rdzv-backend 若仍是默认 static,成员是静态的,没有弹性可言,必须显式 c10d(或 etcd)。
  3. "多机起不来"——static 模式下每台机器必须给不同的 --node-rank;c10d 模式下所有节点跑同一条命令,由 --rdzv-endpoint 指向的节点充当协调者。

四、rendezvous 在做什么:四个不变量 ​

rendezvous 不是"连一下 master",而是把"成员发现 + 分布式同步 + 一致决策"合在一起。它有四个不变量,理解了这四个,排障就有分类依据:

  • Barrier(栅栏):所有节点阻塞,直到至少 min 个节点到齐才算完成;到达 min 后还会多等一个很小的 last-call 窗口,避免"关得太快"把几乎同时到达的节点排除在外;一旦达到 max 立即放行;另有一个整体超时,min 一直没到就失败,且官方明确定义为不可重试。
  • Exclusivity(排他):已经完成的 rendezvous 未销毁前,迟到的节点只能"登记为等待",不能自组一个平行 worker group。这就是为什么"两个作业共用一个 endpoint"会互相卡死或被合并。
  • Consistency(一致):完成后全体对成员集合与各自 rank 达成一致;但 rank 不跨轮次稳定。
  • Shared store(共享 KV):rendezvous 完成后返回一个 torch.distributed.Store(c10d 后端默认是 TCPStore),后续控制面信息靠它交换。

对应的四类异常也正好是排障四条路:RendezvousClosedError(rendezvous 已被关闭,重试无意义)、RendezvousConnectionError(连不上后端)、RendezvousStateError(状态损坏)、RendezvousTimeoutError(没在超时内凑齐)。看到哪一种,就知道该查网络、查 id、还是查节点数。

后端选择上只有三种:c10d(用 C10d store,默认 TCPStore,无第三方依赖,官方推荐)、etcd-v2、etcd(legacy,维护模式,后续会移除)。用 etcd 系必须让 etcd 打开 v2 API;官方测试基线是 etcd v3.4.3。endpoint 要挑一台带宽好的节点,host 不带端口时默认 29400。

五、一次重启的完整时序 ​

三种失败如何收敛到同一个结果、一次弹性事件的时序,与 rendezvous 的四个不变量

把上面的机制串起来,一次弹性事件是这样的:

  1. 某 worker 退出、或某节点 agent 消失;
  2. 存活节点上的 agent 感知到(monitor-interval 默认 0.1 秒轮询一次);
  3. 所有存活 worker 被立即杀掉,不做优雅退出,也不等其他 rank 完成当前 step;
  4. 存活节点(弹性模式下还包括新加入的节点)重新进入 rendezvous,凑够 min 后形成新 membership,其余节点登记为等待;
  5. 新的 WorkerGroup 以新的 RANK 和 WORLD_SIZE 启动,你的脚本从 main 重新执行;
  6. 你的 main 第一件事必须是读 checkpoint,否则等价于从 step 0 重跑。

第 5 步是最容易被忽略的:重启不是"从断点恢复函数栈",而是"重新起一遍进程、重新 import、重新建模型"。所以恢复逻辑必须放在训练循环之外,且对"checkpoint 不存在"(首次启动)要能优雅处理。

第 3 步和第 6 步联合起来给出一个量化关系:checkpoint 间隔 = 单次故障最大可接受损失。异步保存能让写盘不阻塞训练,但被 kill 时正在上传的那次 checkpoint 很可能不完整——判断"这次的 checkpoint 能不能用",要等上传 future 完成、且 .metadata 已落盘(详见 分布式 checkpoint 实战)。

六、脚本侧的四条契约 ​

第一,用 @record 装饰入口。 官方行为是:worker 未捕获异常会写进 TORCHELASTIC_ERROR_FILE,agent 汇总各子进程的错误文件,取时间戳最小(即最早)的那个作为根因上报。没有装饰器时,错误摘要里只有 exitcode,没有 traceback——排障成本会翻几倍。

python
import os
import torch
import torch.distributed as dist
from torch.distributed.elastic.multiprocessing.errors import record

@record
def main():
    local_rank = int(os.environ["LOCAL_RANK"])
    torch.cuda.set_device(local_rank)          # 必须在 init_process_group 之前
    dist.init_process_group(backend="nccl")    # RANK/WORLD_SIZE/MASTER_* 由 torchrun 注入
    train()

if __name__ == "__main__":
    main()

第二,不要自己解析 rank。 torchrun 已经注入 RANK/WORLD_SIZE/MASTER_ADDR/MASTER_PORT,init_process_group 默认从环境变量读,不需要手动传。

第三,注意 --local-rank 的拼写变化。 从 PyTorch 2.0 起,torchrun 传给脚本的是 --local-rank=<rank>(连字符),旧的 --local_rank(下划线)只保留兼容。如果脚本的 argparse 只注册了下划线版本,会直接报 error: unrecognized arguments: --local-rank=<rank>。稳妥写法是两个名字都注册:

python
parser.add_argument("--local-rank", "--local_rank", type=int)

第四,构造顺序要固定。 每次重启都是从零建对象:set_device → init_process_group → 建模型 → 包 DDP/FSDP → 建优化器 → 加载状态 → 建 dataloader(set_epoch 后再迭代)。顺序错了会出现"加载了权重但优化器动量是新的""sampler 的 shuffle 与 checkpoint 不一致"这类静默偏差。

另外,rank==0 分支里的副作用必须幂等:清理旧 checkpoint、删共享临时目录、往外部系统写一条"训练开始",在重启后都会再执行一遍。

七、要恢复的到底是什么 ​

"存了模型权重"远不够。一次可续训的 checkpoint 至少包含六类状态,缺哪一类,重启后就会看到对应的症状:

状态缺了会怎样备注
模型权重从头开始用 DCP 存分片,支持跨拓扑重分片
优化器状态(含 step)Adam 动量归零,loss 出现台阶优化器 step 也决定 scheduler 位置
学习率调度器重启后 LR 跳回初值若由 step 推导则可省
数据进度(epoch + 批内偏移)重放或跳过样本DistributedSampler.set_epoch 只解决 epoch 级 shuffle
RNG 状态(torch/cuda/python/numpy)dropout、数据增强不可复现影响"同一次实验能不能对齐"
梯度累积边界累积窗口错位,等效 batch 变化累积中重启必须丢弃未完成的窗口

数据进度这块值得单独强调:DistributedSampler 的 set_epoch(epoch) 只能保证"第 N 个 epoch 的 shuffle 顺序一致",它不提供"epoch 中间第 137 个 batch"的位置。如果 checkpoint 是按 step 存的,就必须自己记录已消费样本数,并在重建 dataloader 后跳过对应数量;不跳过就是重放(loss 曲线出现重复段),跳过方式错了就是丢样本(loss 突然变差)。

一个够用的状态字典长这样(字段名可自定,关键是都在):

python
ckpt = {
    "model": model.state_dict(),          # 或 DCP 分片保存
    "optim": optim.state_dict(),
    "sched": sched.state_dict(),
    "step": global_step,
    "epoch": epoch,
    "samples_consumed": samples_seen,     # 用于批内恢复
    "rng": {
        "torch": torch.get_rng_state(),
        "cuda": torch.cuda.get_rng_state_all(),
    },
}

八、max_restarts 计的是"重启次数",不是"失败次数" ​

这一点直接影响容量规划。--max-restarts=3 的含义是"worker group 最多被重启 3 次",不是"最多容忍 3 张卡坏"。一次重启可能由 1 个 worker 失败触发,也可能由 8 个同时失败触发,计数只 +1。观测手段是 TORCHELASTIC_RESTART_COUNT 与 TORCHELASTIC_MAX_RESTARTS 两个环境变量。

官方把错误分成四类,重试策略应该按类分流:

类别典型来源该不该重试
User Error参数非法(如 min>max)、配置写错不该,重试只会重复失败
Worker Failure训练进程内的异常、OOM、NCCL 报错可重试,但要限次
Platform Erroragent 自身故障交给作业管理器
Infra Error宿主机、网络、存储等外部故障交给作业管理器/告警

把 max_restarts 设成很大的值,等于把"确定性 bug"变成"重启风暴":每次重启都要重新建进程组、重新 rendezvous、重新读 checkpoint,几十张卡空转几十分钟,最后还是失败。有界重试 + 错误分类 + 失败样本落盘,比"无限弹性"更接近生产可用的容错。

九、三种常用形态的参数模板 ​

单机多卡调试——用 --standalone,端口随机、id 自动:

bash
torchrun --standalone --nnodes=1 --nproc-per-node=gpu train.py

固定规模容错(不伸缩,容忍 3 次重启)——显式给 c10d 与 id:

bash
torchrun \
  --nnodes=$NUM_NODES --nproc-per-node=8 \
  --max-restarts=3 \
  --rdzv-backend=c10d --rdzv-id=$JOB_ID \
  --rdzv-endpoint=node1.example.com:29400 \
  train.py

弹性伸缩(1 到 4 节点,容忍 3 次成员变化或失败):

bash
torchrun \
  --nnodes=1:4 --nproc-per-node=8 \
  --max-restarts=3 \
  --rdzv-backend=c10d --rdzv-id=$JOB_ID \
  --rdzv-endpoint=node1.example.com:29400 \
  train.py

多机场景下,所有节点跑同一条命令(static 模式例外,需要各自的 --node-rank)。由作业管理器把 torchrun 作为入口启动,不要在每个节点上各起一个 torchrun 去抢同一个 rdzv-id——那不是分布式训练,是两拨进程在同一个栅栏上互相等待。

同机跑多个独立作业时,必须用不同端口(或 --rdzv-endpoint=localhost:0 让系统挑一个空闲端口),否则两个作业会被合并成一个 worker group,症状是 world size 翻倍、collective 卡死。

十、排障清单:按现象找判据 ​

  1. 卡在 rendezvous 不结束:先确认 --rdzv-endpoint 从各节点可达、--rdzv-id 全节点一致、--nnodes 的 min 不大于实际节点数。若最终抛 RendezvousTimeoutError,官方语义是"不可重试",应释放资源重提作业,而不是原地等。
  2. Address already in use 或两个作业莫名混在一起:同机多作业没隔离端口,或复用了同一个 rdzv-id。改端口 + 改 id,两者都要改。
  3. 重启后 hang 在 init_process_group:常见是旧进程残留占着 MASTER_PORT、或网络策略把新连接的端口挡了。先查本机残留进程与端口占用,再看 RendezvousConnectionError 指向哪一端。
  4. 重启后 loss 突然抬高:先查是否只恢复了权重(缺优化器/调度器),再查数据位置是否重放。前者是台阶状抬升,后者是曲线出现重复段。
  5. 重启风暴:TORCHELASTIC_RESTART_COUNT 连续增长且每次都在同一 step 附近失败,基本是确定性 bug(数据损坏、shape 错、checkpoint 版本不匹配),应停掉作业而不是加大重启次数。
  6. unrecognized arguments: --local-rank:脚本只注册了 --local_rank,按第三节/第六节改成两个名字都注册。

十一、可复现的验收口径 ​

这套东西不需要大集群也能验证,三条:

  1. 验证默认值:不写 --max-restarts,手动 kill 一个 worker,观察整组退出、TORCHELASTIC_RESTART_COUNT 不出现(进程根本没重启)。
  2. 验证重启语义:加 --max-restarts=3,同样 kill 一个 worker,观察所有 worker 被同时杀掉、脚本从 main 重新执行、restart count +1、训练从 checkpoint 的 step 续上。
  3. 验证隔离:同机起两个 --standalone 作业(各自端口随机)与两个同端口的 c10d 作业,对比 world size 与 collective 行为,亲眼确认"作业被合并"长什么样。

到这里,"弹性"的边界应该清楚了:torchrun 负责发现成员变化、整组重启、重新 rendezvous;你的脚本负责把状态从 checkpoint 里捞回来。前者是框架能力,后者是工程责任,中间那条缝——checkpoint 的完整性与数据位置——才是真正决定一次故障损失几分钟还是几天的东西。

相关阅读:分布式 checkpoint 实战:DCP 的分片布局、异步保存与重分片、FSDP2 实战:fully_shard 契约与 torch.compile 组合、数据管道调优。

相关文章 ​

AI-HPC 智算超算专家 · Contact: openaihpc@gmail.com