弹性训练与容错: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 随之改变,代码里不能写死。
| 变量 | 含义 | 何时会变 |
|---|---|---|
RANK | worker 在 worker group 内的全局序号 | 每次重新 rendezvous |
LOCAL_RANK | 本机内的序号,通常等于 GPU 序号 | 一般稳定,但不要当全局身份 |
WORLD_SIZE | worker group 总 worker 数 | 弹性伸缩时 |
GROUP_RANK | worker 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 解析器定义(不是记忆):
| 参数 | 默认值 | 关键含义 |
|---|---|---|
--nnodes | 1:1 | 写成 min:max 才具备弹性;min 必须 >0 且 ≤max,否则直接断言失败 |
--nproc-per-node | 1 | 可写 auto/cpu/gpu/xpu 或整数;写 gpu 才是"每卡一进程" |
--rdzv-backend | static | 默认不是 c10d!static 只按 --node-rank 组固定成员,无弹性 |
--rdzv-endpoint | 空 | static 下回落到 master_addr:master_port;c10d 下必须显式给 host:port |
--rdzv-id | none | 同 id 的节点才会join 同一个 worker group |
--max-restarts | 0 | 默认不重启,这就是"整组退出"的直接原因 |
--monitor-interval | 0.1(秒) | agent 轮询 worker 状态的间隔 |
--start-method | spawn | 可选 fork/forkserver;与 CUDA 上下文的安全性相关 |
--master-addr / --master-port | 127.0.0.1 / 29500 | 只对 static rendezvous 有效,非 static 时给了会被警告忽略 |
--standalone | 关 | 打开后强制 rdzv-backend=c10d、rdzv-endpoint=localhost:0、rdzv-id=<uuid>,显式给的值被覆盖 |
由此可直接推出三个常见病症的病因:
- "我配了 4 次重启怎么还是退出"——如果用了
--standalone,rdzv-id与 endpoint 被覆盖,但max_restarts不被覆盖;如果没显式写--max-restarts,它就是 0。 - "写了
--nnodes=1:4还是不能伸缩"——--rdzv-backend若仍是默认static,成员是静态的,没有弹性可言,必须显式c10d(或 etcd)。 - "多机起不来"——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。
五、一次重启的完整时序
把上面的机制串起来,一次弹性事件是这样的:
- 某 worker 退出、或某节点 agent 消失;
- 存活节点上的 agent 感知到(
monitor-interval默认 0.1 秒轮询一次); - 所有存活 worker 被立即杀掉,不做优雅退出,也不等其他 rank 完成当前 step;
- 存活节点(弹性模式下还包括新加入的节点)重新进入 rendezvous,凑够
min后形成新 membership,其余节点登记为等待; - 新的 WorkerGroup 以新的 RANK 和 WORLD_SIZE 启动,你的脚本从
main重新执行; - 你的
main第一件事必须是读 checkpoint,否则等价于从 step 0 重跑。
第 5 步是最容易被忽略的:重启不是"从断点恢复函数栈",而是"重新起一遍进程、重新 import、重新建模型"。所以恢复逻辑必须放在训练循环之外,且对"checkpoint 不存在"(首次启动)要能优雅处理。
第 3 步和第 6 步联合起来给出一个量化关系:checkpoint 间隔 = 单次故障最大可接受损失。异步保存能让写盘不阻塞训练,但被 kill 时正在上传的那次 checkpoint 很可能不完整——判断"这次的 checkpoint 能不能用",要等上传 future 完成、且 .metadata 已落盘(详见 分布式 checkpoint 实战)。
六、脚本侧的四条契约
第一,用 @record 装饰入口。 官方行为是:worker 未捕获异常会写进 TORCHELASTIC_ERROR_FILE,agent 汇总各子进程的错误文件,取时间戳最小(即最早)的那个作为根因上报。没有装饰器时,错误摘要里只有 exitcode,没有 traceback——排障成本会翻几倍。
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>。稳妥写法是两个名字都注册:
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 突然变差)。
一个够用的状态字典长这样(字段名可自定,关键是都在):
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 Error | agent 自身故障 | 交给作业管理器 |
| Infra Error | 宿主机、网络、存储等外部故障 | 交给作业管理器/告警 |
把 max_restarts 设成很大的值,等于把"确定性 bug"变成"重启风暴":每次重启都要重新建进程组、重新 rendezvous、重新读 checkpoint,几十张卡空转几十分钟,最后还是失败。有界重试 + 错误分类 + 失败样本落盘,比"无限弹性"更接近生产可用的容错。
九、三种常用形态的参数模板
单机多卡调试——用 --standalone,端口随机、id 自动:
torchrun --standalone --nnodes=1 --nproc-per-node=gpu train.py固定规模容错(不伸缩,容忍 3 次重启)——显式给 c10d 与 id:
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 次成员变化或失败):
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 卡死。
十、排障清单:按现象找判据
- 卡在 rendezvous 不结束:先确认
--rdzv-endpoint从各节点可达、--rdzv-id全节点一致、--nnodes的min不大于实际节点数。若最终抛RendezvousTimeoutError,官方语义是"不可重试",应释放资源重提作业,而不是原地等。 Address already in use或两个作业莫名混在一起:同机多作业没隔离端口,或复用了同一个rdzv-id。改端口 + 改 id,两者都要改。- 重启后 hang 在
init_process_group:常见是旧进程残留占着MASTER_PORT、或网络策略把新连接的端口挡了。先查本机残留进程与端口占用,再看RendezvousConnectionError指向哪一端。 - 重启后 loss 突然抬高:先查是否只恢复了权重(缺优化器/调度器),再查数据位置是否重放。前者是台阶状抬升,后者是曲线出现重复段。
- 重启风暴:
TORCHELASTIC_RESTART_COUNT连续增长且每次都在同一 step 附近失败,基本是确定性 bug(数据损坏、shape 错、checkpoint 版本不匹配),应停掉作业而不是加大重启次数。 unrecognized arguments: --local-rank:脚本只注册了--local_rank,按第三节/第六节改成两个名字都注册。
十一、可复现的验收口径
这套东西不需要大集群也能验证,三条:
- 验证默认值:不写
--max-restarts,手动kill一个 worker,观察整组退出、TORCHELASTIC_RESTART_COUNT不出现(进程根本没重启)。 - 验证重启语义:加
--max-restarts=3,同样kill一个 worker,观察所有 worker 被同时杀掉、脚本从main重新执行、restart count +1、训练从 checkpoint 的 step 续上。 - 验证隔离:同机起两个
--standalone作业(各自端口随机)与两个同端口的 c10d 作业,对比 world size 与 collective 行为,亲眼确认"作业被合并"长什么样。
到这里,"弹性"的边界应该清楚了:torchrun 负责发现成员变化、整组重启、重新 rendezvous;你的脚本负责把状态从 checkpoint 里捞回来。前者是框架能力,后者是工程责任,中间那条缝——checkpoint 的完整性与数据位置——才是真正决定一次故障损失几分钟还是几天的东西。
相关阅读:分布式 checkpoint 实战:DCP 的分片布局、异步保存与重分片、FSDP2 实战:fully_shard 契约与 torch.compile 组合、数据管道调优。