TrainJob 的检查点与恢复

一个运行六小时的微调任务,最终可能会在第五小时遇到节点重启、Pod 被驱逐、抢占或 OOM。如果没有检查点,其中任何一个事件都会让整个运行前功尽弃。

Kubeflow Trainer v2 没有自己的检查点 API。TrainJob 或 TrainingRuntime 规范中的任何内容都不会写入、查找或恢复检查点。两者的职责划分如下:

Trainer v2 / JobSet 提供的功能训练脚本必须执行的操作
Pod 生命周期之外的存储(挂载的 PVC)定期将检查点写入其中
失败后重启 Pod(failurePolicy.maxRestarts)启动时检测最新检查点并从该检查点恢复
按需暂停和恢复(spec.suspend)在 SIGTERM 时干净退出,并刷新写入最终检查点

任意一列配置错误,都会导致相同且无提示的故障模式:作业重启,找不到任何内容,然后从第 0 步重新开始训练。

本指南介绍 Kubeflow Trainer v2 TrainJob 的相关机制。如果训练作业是 KubeRay RayJob,请改为参阅Checkpointing and Resuming RayJobs——KubeRay 没有 TrainJob / TrainingRuntime,恢复 API 属于 Ray Train。对于为了让 InferenceService 取回其 GPU 而主动抢占 TrainJob 的具体场景,请参阅使用 Kueue 的可抢占 TrainJob;该文档基于此处介绍的全部内容。

先决条件

要求详细信息
Kubeflow Trainer v2trainer.kubeflow.org/v1alpha1;请参阅使用 Kubeflow Trainer v2 进行微调
PVC 和存储类kubectl get storageclass。有关访问模式,请参阅选择生命周期长于 Pod 的存储
训练运行时镜像运行时目录中的任意镜像
kubectl 访问权限有权在命名空间中管理 trainjobs、trainingruntimes 和 persistentvolumeclaims

检查点必须包含的内容

“恢复”并不等于“重新加载权重”。仅包含模型权重的检查点会让优化器从零开始——动量缓冲区、学习率调度器位置和步数计数器都会丢失,并且损失曲线会在恢复处出现明显的折点。

可恢复的检查点包含:

  • 模型权重
  • 优化器状态——Adam 的矩估计。通常以 fp32 存储时约为模型大小的 2 倍,通常也是检查点中占比最大的部分。
  • LR 调度器状态——这样调度会继续进行,而不是重新预热。
  • 步数/epoch 计数器——用于确定从何处继续。
  • RNG 状态和数据加载器位置——这样恢复后的运行不会以相同顺序再次读取相同样本。

HuggingFace Trainer 的 checkpoint-N/ 目录已经包含上述所有内容。如果你手动编写训练循环,只保存 model.state_dict() 是最常见的导致“恢复”悄然损害训练运行的方式。

选择生命周期长于 Pod 的存储

检查点目录必须位于 PVC 上。emptyDir 会随 Pod 一同消失,而 hostPath 或本地存储类会将检查点困在某个节点上,重启后的 Pod 可能再也不会调度到该节点。

访问模式只取决于同时写入的训练 Pod 数量:

numNodes访问模式原因
1ReadWriteOnce 即可一次只有一个 Pod 挂载它
> 1必须使用 ReadWriteMany每个训练 Pod 同时挂载同一个 PVC
NOTE

ReadWriteOnce 表示“一次一个节点”,而不是“永久固定在一个节点上”。网络附加的 RWO 卷(Ceph RBD、EBS 及类似存储)会从旧节点卸载,并在重启后的 Pod 被调度到的位置重新挂载,因此即使单节点运行恢复到不同节点上,也能正确继续运行。只有并发的多 Pod 访问才需要 RWX。

但这不适用于 local-storage / topolvm / hostPath,因为它们在物理上固定于一个节点。

应用 PVC(checkpoint-pvc.yaml):

base=https://raw.githubusercontent.com/alauda/aml-docs/master/docs/en/train/guides/assets/checkpointing
NS=my-namespace   # edit to your namespace

curl -fsSL $base/checkpoint-pvc.yaml | sed "s/<your-namespace>/$NS/" | kubectl apply -f -

为 checkpoint size x save_total_limit 以及额外余量预留足够空间。完整权重检查点通常比人们预期的更大——带优化器状态的 7B 模型每个检查点大约需要 80 GiB。LoRA/QLoRA 适配器只有几 MB,因此同一个 PVC 可以保存更多适配器。

使运行时支持检查点

checkpoint-trainingruntime.yaml 是一个可运行的 TrainingRuntime,其中已配置完整的模式。关键部分如下:

spec:
  template:
    spec:
      failurePolicy:
        maxRestarts: 3                        # recreate trainer pods on failure
      replicatedJobs:
        - name: node
          template:
            metadata:
              labels:
                trainer.kubeflow.org/trainjob-ancestor-step: trainer   # see warning below
            spec:
              backoffLimit: 0                 # let failurePolicy own restarts
              template:
                spec:
                  terminationGracePeriodSeconds: 60   # room to flush on SIGTERM
                  volumes:
                    - name: ckpt
                      persistentVolumeClaim: { claimName: train-ckpt }
                  containers:
                    - name: node
                      env:
                        - { name: CKPT_DIR, value: /mnt/ckpt/run }
                      volumeMounts:
                        - { mountPath: /mnt/ckpt, name: ckpt }

脚本中真正执行恢复的两行如下:

# Sort numerically: a lexical sort puts checkpoint-9 after checkpoint-100
# and silently rewinds your run by 91 steps.
ckpts = sorted(glob.glob(f"{ckpt_dir}/checkpoint-*"),
               key=lambda p: int(p.rsplit("-", 1)[1]))
resume = ckpts[-1] if ckpts else None    # None on the first run = start clean

trainer.train(resume_from_checkpoint=resume)

正是这种自动检测机制,使同一个清单既适用于首次提交,也适用于之后的每次重启。将 resume_from_checkpoint=True 硬编码会导致首次运行失败(因为此时还不存在检查点);将路径硬编码则会永久固定到一个检查点。

WARNING

训练器 replicatedJob 上的 trainer.kubeflow.org/trainjob-ancestor-step: trainer 标签是必需的。如果没有该标签,控制器无法识别该 replicatedJob 是训练器步骤,并且 TrainJob 上的每个 spec.trainer.* 字段——env、resourcesPerNode、image、command、numNodes——都会被静默丢弃:没有错误、没有事件、没有警告。TrainJob 会改用运行时的默认值运行,因此,一个你以为已分配 GPU 和 CKPT_DIR 的作业,实际运行时两者都没有。

请验证这些覆盖配置确实已生效,而不要直接假定它们生效了:

kubectl -n "$NS" get pod <trainer-pod> \
  -o jsonpath='{.spec.containers[0].env}{"\n"}{.spec.containers[0].resources}{"\n"}'

应用运行时:

curl -fsSL $base/checkpoint-trainingruntime.yaml | sed "s/<your-namespace>/$NS/" | kubectl apply -f -

提交可恢复的 TrainJob

trainjob-resume.yaml 通过 podTemplateOverrides 挂载检查点 PVC,因此一个共享运行时可以为多个运行提供服务,而每个运行都可以将检查点保存到不同位置:

spec:
  trainer:
    env:
      - { name: CKPT_DIR, value: /mnt/ckpt/sft-run-1 }   # per-run directory
  podTemplateOverrides:
    - targetJobs:
        - name: node
      spec:
        volumes:
          - name: ckpt
            persistentVolumeClaim: { claimName: train-ckpt }
        containers:
          - name: node
            volumeMounts:
              - { name: ckpt, mountPath: /mnt/ckpt }
curl -fsSL $base/trainjob-resume.yaml | sed "s/<your-namespace>/$NS/" | kubectl create -f -
NOTE

podTemplateOverrides 可以添加 volumes、volumeMounts、nodeSelector、tolerations 和 affinity,但不能在训练器或初始化容器上设置 env——验证 webhook 会直接拒绝该 TrainJob:

admission webhook "validator.trainjob.trainer.kubeflow.org" denied the request:
spec.podTemplateOverrides: must not have envs for the dataset-initializer,
model-initializer, node containers

环境变量应改为放在 spec.trainer.env 中。

每种中断如何恢复

崩溃或节点故障

两个相互独立的层会重启失败的训练器,而支持检查点的脚本在这两种情况下都能正确恢复:

  trainer exits non-zero
        │
        ├─ restartPolicy: OnFailure ──► kubelet restarts the container
        │                                in place, same pod, same node
        │
        └─ backoffLimit: 0 ──► Job fails ──► JobSet failurePolicy.maxRestarts
                                              recreates the pod (possibly on
                                              another node), PVC re-attaches

无论哪种情况,新进程都会执行相同的自动检测,并从最新的 checkpoint-N 继续运行。查看 JobSet 上的 restarts 是否递增:

kubectl -n "$NS" get jobset <trainjob-name> -o jsonpath='{.status.restarts}{"\n"}'

当 maxRestarts 用尽后,TrainJob 会变为 Failed——因此应将其设置得足够高,以应对暂时性的节点波动,但不要高到让真正损坏的脚本无限循环。

抢占

Kueue 会驱逐 Workload,配额释放后 Trainer v2 会重新创建 JobSet;训练器会从 PVC 恢复。cohort/配额配置是另一个独立主题,详见 使用 Kueue 的可抢占 TrainJob。

有意暂停

spec.suspend 可以在不丢失运行状态的情况下停止运行——例如暂时将 GPU 让给紧急任务一小时:

# Pause: pods are terminated, the TrainJob object stays.
kubectl -n "$NS" patch trainjob sft-resumable --type=merge -p '{"spec":{"suspend":true}}'

# Resume: a new pod starts and picks up the newest checkpoint.
kubectl -n "$NS" patch trainjob sft-resumable --type=merge -p '{"spec":{"suspend":false}}'

恢复后的 Pod 是一个新的 Pod,名称也会改变,并且可能会被调度到不同的节点。它的第一行日志应为 [checkpoint] resuming from ...。

NOTE

暂停的 TrainJob 恢复后,activeDeadlineSeconds 会重新开始倒计时——每次暂停后,作业都会重新获得完整的截止时间,而不是从创建时开始计算。

各框架设置

每个基于 HuggingFace-Trainer 的技术栈都提供相同的三个设置,因此上述模式无需改动即可迁移:

技术栈保存频率恢复备注
HuggingFace Trainersave_strategy="steps"、save_steps=N、save_total_limit=2trainer.train(resume_from_checkpoint=path)checkpoint-N/ 保存模型 + 优化器 + 调度器 + RNG
LlamaFactoryYAML 配置中的 save_steps自动执行——它会为你调用 get_last_checkpoint(output_dir)封装了 HF Trainer。overwrite_output_dir: true 会跳过自动检测,因此运行会静默地从头开始——要支持恢复,请将其关闭
training_hubcheckpoint_at_epoch: trueaccelerate_full_state_at_epoch: true只有完整状态选项支持恢复;参见 使用 Training Hub 进行微调
MindSpeed / Megatron(NPU)--save-interval从 latest_checkpointed_iteration.txt 自动恢复Checkpoint 布局与 TP/PP 度数绑定——参见 Ascend NPU 指南
手写 PyTorch你自己的 torch.save你自己的 torch.load保存优化器 + 调度器 + step,而不只是权重

根据你可以容忍的中断选择 save_steps:最多可能丢失的工作量为 save_steps x seconds_per_step。按每步 5 秒计算,save_steps: 100 可能会丢失 ~8 分钟的工作。保存过于频繁也会带来额外开销——完整权重 Checkpoint 可能导致 GPU 停滞数十秒,因此在稳定集群上应选择较大的值,而在可抢占队列上应选择较小的值。始终将其与 save_total_limit 配合使用,以免 PVC 无限增长。

多节点运行

使用 numNodes: > 1 时,PVC 必须为 RWX,并且有两点变化:

  • 只有 rank 0 应写入标准数据并行训练的 Checkpoint,否则每个 rank 都会争相写入同一路径。HF Trainer 已经处理了这一点;手写循环必须使用 if rank == 0 进行保护。
  • 所有 rank 都必须从同一个 Checkpoint。不一致的 rank 不会崩溃,而是会静默地产生分歧。

对于分片策略(FSDP、DeepSpeed ZeRO),每个 rank 都拥有部分权重和优化器状态,将所有内容汇总到 rank 0 对大型模型而言通常是不可能的。这正是 torch.distributed.checkpoint 的用途:每个 rank 并行写入自己的分片,结果可以在不同的 world size 下重新加载——因此,在 8 个 GPU 上创建 Checkpoint 的运行可以在 4 个 GPU 上恢复。以单个汇总文件保存的 Checkpoint 无法通过这种方式重新分片。

验证它确实会恢复

不要等到真正发生故障时才发现这一点。每采用一种新的运行时,都执行一次以下演练:

# 1. Submit, and wait for a first checkpoint to appear on the PVC.
kubectl -n "$NS" exec <trainer-pod> -- ls /mnt/ckpt/sft-run-1

# 2. Force an interruption.
kubectl -n "$NS" patch trainjob sft-resumable --type=merge -p '{"spec":{"suspend":true}}'
kubectl -n "$NS" patch trainjob sft-resumable --type=merge -p '{"spec":{"suspend":false}}'

# 3. The new pod's first lines must say it resumed -- not that it started fresh.
kubectl -n "$NS" logs <new-trainer-pod> | head -3
[checkpoint] resuming from /mnt/ckpt/sft-run-1/checkpoint-150

如果第 3 步输出的是 no prior checkpoint, starting fresh,则恢复功能已损坏——在实际发生抢占时也同样无法恢复。

NOTE

通过 grep trainer 的日志来查找 HF Trainer 自己输出的 “Saving model checkpoint to” 行并不可靠:tqdm 进度条会覆盖该行。请改为检查 PVC 上的 checkpoint-* 目录;上面的日志行正是通过这种方式进行检查的。

故障排除

症状原因
重启后的作业从 step 0 开始训练Checkpoint 目录位于 emptyDir 上,或不同运行之间的 CKPT_DIR 不同,或自动检测 glob 未找到任何内容
从旧得多的 Checkpoint 恢复对 checkpoint-* 进行字典序排序(checkpoint-9 排在 checkpoint-100 之后)——应按数值排序
spec.trainer.env / resourcesPerNode 被忽略,且没有错误运行时的 trainer replicatedJob 缺少 trainer.kubeflow.org/trainjob-ancestor-step: trainer 标签
TrainJob 被拒绝:must not have envs for the ... node containersenv 设置在 podTemplateOverrides 下;将其移至 spec.trainer.env
恢复后损失曲线向上弯折Checkpoint 只有权重,没有优化器或调度器状态
Pod 在恢复时处于 Pending 状态,卷无法挂载RWO PVC 仍附加在旧节点上,或 numNodes > 1 用于非 RWX 类
运行中途 PVC 已满未设置 save_total_limit
抢占后缺少最终 CheckpointterminationGracePeriodSeconds 太短,无法完成写入