TrainJob 的检查点与恢复
一个运行六小时的微调任务,最终可能会在第五小时遇到节点重启、Pod 被驱逐、抢占或 OOM。如果没有检查点,其中任何一个事件都会让整个运行前功尽弃。
Kubeflow Trainer v2 没有自己的检查点 API。TrainJob 或 TrainingRuntime 规范中的任何内容都不会写入、查找或恢复检查点。两者的职责划分如下:
任意一列配置错误,都会导致相同且无提示的故障模式:作业重启,找不到任何内容,然后从第 0 步重新开始训练。
本指南介绍 Kubeflow Trainer v2 TrainJob 的相关机制。如果训练作业是 KubeRay RayJob,请改为参阅Checkpointing and Resuming RayJobs——KubeRay 没有 TrainJob / TrainingRuntime,恢复 API 属于 Ray Train。对于为了让 InferenceService 取回其 GPU 而主动抢占 TrainJob 的具体场景,请参阅使用 Kueue 的可抢占 TrainJob;该文档基于此处介绍的全部内容。
先决条件
检查点必须包含的内容
“恢复”并不等于“重新加载权重”。仅包含模型权重的检查点会让优化器从零开始——动量缓冲区、学习率调度器位置和步数计数器都会丢失,并且损失曲线会在恢复处出现明显的折点。
可恢复的检查点包含:
- 模型权重
- 优化器状态——Adam 的矩估计。通常以 fp32 存储时约为模型大小的 2 倍,通常也是检查点中占比最大的部分。
- LR 调度器状态——这样调度会继续进行,而不是重新预热。
- 步数/epoch 计数器——用于确定从何处继续。
- RNG 状态和数据加载器位置——这样恢复后的运行不会以相同顺序再次读取相同样本。
HuggingFace Trainer 的 checkpoint-N/ 目录已经包含上述所有内容。如果你手动编写训练循环,只保存 model.state_dict() 是最常见的导致“恢复”悄然损害训练运行的方式。
选择生命周期长于 Pod 的存储
检查点目录必须位于 PVC 上。emptyDir 会随 Pod 一同消失,而 hostPath 或本地存储类会将检查点困在某个节点上,重启后的 Pod 可能再也不会调度到该节点。
访问模式只取决于同时写入的训练 Pod 数量:
ReadWriteOnce 表示“一次一个节点”,而不是“永久固定在一个节点上”。网络附加的 RWO 卷(Ceph RBD、EBS 及类似存储)会从旧节点卸载,并在重启后的 Pod 被调度到的位置重新挂载,因此即使单节点运行恢复到不同节点上,也能正确继续运行。只有并发的多 Pod 访问才需要 RWX。
但这不适用于 local-storage / topolvm / hostPath,因为它们在物理上固定于一个节点。
应用 PVC(checkpoint-pvc.yaml):
为 checkpoint size x save_total_limit 以及额外余量预留足够空间。完整权重检查点通常比人们预期的更大——带优化器状态的 7B 模型每个检查点大约需要 80 GiB。LoRA/QLoRA 适配器只有几 MB,因此同一个 PVC 可以保存更多适配器。
使运行时支持检查点
checkpoint-trainingruntime.yaml 是一个可运行的 TrainingRuntime,其中已配置完整的模式。关键部分如下:
脚本中真正执行恢复的两行如下:
正是这种自动检测机制,使同一个清单既适用于首次提交,也适用于之后的每次重启。将 resume_from_checkpoint=True 硬编码会导致首次运行失败(因为此时还不存在检查点);将路径硬编码则会永久固定到一个检查点。
训练器 replicatedJob 上的 trainer.kubeflow.org/trainjob-ancestor-step: trainer 标签是必需的。如果没有该标签,控制器无法识别该 replicatedJob 是训练器步骤,并且 TrainJob 上的每个 spec.trainer.* 字段——env、resourcesPerNode、image、command、numNodes——都会被静默丢弃:没有错误、没有事件、没有警告。TrainJob 会改用运行时的默认值运行,因此,一个你以为已分配 GPU 和 CKPT_DIR 的作业,实际运行时两者都没有。
请验证这些覆盖配置确实已生效,而不要直接假定它们生效了:
应用运行时:
提交可恢复的 TrainJob
trainjob-resume.yaml 通过 podTemplateOverrides 挂载检查点 PVC,因此一个共享运行时可以为多个运行提供服务,而每个运行都可以将检查点保存到不同位置:
podTemplateOverrides 可以添加 volumes、volumeMounts、nodeSelector、tolerations 和 affinity,但不能在训练器或初始化容器上设置 env——验证 webhook 会直接拒绝该 TrainJob:
环境变量应改为放在 spec.trainer.env 中。
每种中断如何恢复
崩溃或节点故障
两个相互独立的层会重启失败的训练器,而支持检查点的脚本在这两种情况下都能正确恢复:
无论哪种情况,新进程都会执行相同的自动检测,并从最新的 checkpoint-N 继续运行。查看 JobSet 上的 restarts 是否递增:
当 maxRestarts 用尽后,TrainJob 会变为 Failed——因此应将其设置得足够高,以应对暂时性的节点波动,但不要高到让真正损坏的脚本无限循环。
抢占
Kueue 会驱逐 Workload,配额释放后 Trainer v2 会重新创建 JobSet;训练器会从 PVC 恢复。cohort/配额配置是另一个独立主题,详见 使用 Kueue 的可抢占 TrainJob。
有意暂停
spec.suspend 可以在不丢失运行状态的情况下停止运行——例如暂时将 GPU 让给紧急任务一小时:
恢复后的 Pod 是一个新的 Pod,名称也会改变,并且可能会被调度到不同的节点。它的第一行日志应为 [checkpoint] resuming from ...。
暂停的 TrainJob 恢复后,activeDeadlineSeconds 会重新开始倒计时——每次暂停后,作业都会重新获得完整的截止时间,而不是从创建时开始计算。
各框架设置
每个基于 HuggingFace-Trainer 的技术栈都提供相同的三个设置,因此上述模式无需改动即可迁移:
根据你可以容忍的中断选择 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 无法通过这种方式重新分片。
验证它确实会恢复
不要等到真正发生故障时才发现这一点。每采用一种新的运行时,都执行一次以下演练:
如果第 3 步输出的是 no prior checkpoint, starting fresh,则恢复功能已损坏——在实际发生抢占时也同样无法恢复。
通过 grep trainer 的日志来查找 HF Trainer 自己输出的 “Saving model checkpoint to” 行并不可靠:tqdm 进度条会覆盖该行。请改为检查 PVC 上的 checkpoint-* 目录;上面的日志行正是通过这种方式进行检查的。