使用 Kueue、Checkpointing 和 Inference 共存的可抢占 TrainJob

当训练作业与在线 InferenceService 工作负载共享同一个集群时,你需要同时满足两点:

  • 推理得到保护。 它始终拥有所需的 GPU;队列准入是常数时间的,并且不会被训练作业阻塞。
  • 训练填补空闲。 只要推理负载低于峰值,训练就会借用空闲 GPU 并继续推进;但一旦推理重新收回配额,训练会立即让出。

本指南通过一组较少的资产 YAML,连接 Kubeflow Trainer v2 + Kueue + HuggingFace Trainer checkpointing,以实现上述行为。这里的所有内容都已在仓库 e2e harness 中的 c12_kueue_preemption.sh 用例里完成端到端验证。

前提条件

需求详情
Kubeflow Trainer v2trainer.kubeflow.org API group;参见 使用 Kubeflow Trainer v2 进行 Fine-Tuning
Kueue(v1beta2 API 需 v0.13+)参见 安装 Kueue
共享 RWX 存储checkpoint PVC 在重新准入后,必须能够从训练器可能落到的任意节点访问
GPU device plugin示例使用 Alauda Build of HAMI 的 vGPU 资源(nvidia.com/gpualloc、gpucores、gpumem);如果你使用上游 NVIDIA device plugin,则替换为 nvidia.com/gpu
Training runtime 镜像Trainer v2 runtime catalog 中任意包含你所训练框架的镜像

Cohort:一个 CQ 预留配额,另一个借用配额

核心思路是一个 双 ClusterQueue 的 cohort。推理拥有 GPU 的名义配额;训练拥有 0 配额,但在推理空闲时允许最多借用相同数量的配额。当推理工作负载收回其配额时,Kueue 会驱逐正在借用配额的训练 Workload;随后一旦有配额释放,Trainer v2 会从头重新创建 JobSet。

                     ┌──────────────────────────────┐
                     │  Cohort: c12-shared          │
                     │                              │
   inference label ──┤  c12-inference-cq            │
                     │    nominalQuota: 1 GPU       │
                     │    borrowingLimit: 0         │ ← inference never borrows
                     │    reclaimWithinCohort: Any  │
                     │                              │
   training label  ──┤  c12-training-cq             │
                     │    nominalQuota: 0 GPU       │ ← owns nothing
                     │    borrowingLimit: 1 GPU     │ ← borrows when idle
                     │                              │
                     └──────────────────────────────┘

应用 cohort 和按命名空间划分的 LocalQueue:

base=https://raw.githubusercontent.com/alauda/aml-docs/master/docs/en/training_guides/assets/kueue/preemption
NS=my-namespace  # edit to the namespace where you submit jobs

# 1. Cluster admin — one ResourceFlavor + two cohort ClusterQueues.
kubectl apply -f $base/cluster-queues.yaml

# 2. Cluster admin — Kueue WorkloadPriorityClasses for inference / training.
kubectl apply -f $base/workload-priorities.yaml

# 3. Namespace admin — LocalQueues pointing at the cohort.
curl -fsSL $base/local-queues.yaml | sed "s/<your-namespace>/$NS/" | kubectl apply -f -

这些资产文件分别是:

  • cluster-queues.yaml — 定义 cohort、两个 ClusterQueue 以及 ResourceFlavor。根据你希望借出的 GPU 数量,调整 nominalQuota 和 borrowingLimit。
  • workload-priorities.yaml — 两个 WorkloadPriorityClass:c12-inference-prio=1000、c12-training-prio=10。没有这些配置时,cohort 的回收规则仍会触发,但队列内没有优先级顺序可用。
  • local-queues.yaml — c12-inference-lq 和 c12-training-lq,每个 ClusterQueue 对应一个。

使 TrainJob 对抢占安全

被抢占的 TrainJob 的 pod 会被杀掉(先 SIGTERM,宽限期结束后再 SIGKILL)。要在这种情况下存活并且不从头开始,你需要:

  1. 在 RWX PVC 上提供 checkpoint 目录。 抢占后的 pod 可能会落到不同节点上——仅靠本地存储不够。
  2. 频繁做 checkpoint。 使用 save_strategy: steps 并设置较小的 save_steps。被抢占时你可能损失的最大工作量由这个间隔上限决定。
  3. 下次启动时恢复。 HuggingFace Trainer 的 .train(resume_from_checkpoint=<path>) 会自动从 output_dir 中拾取 checkpoint-N/ 继续训练。LlamaFactory、training_hub、mini_trainer,以及任何其他基于 Trainer 的 recipe 都可以免费继承这一能力——它们都暴露相同的 output_dir / save_strategy / resume_from_checkpoint 参数。
  4. 优雅退出。 将 terminationGracePeriodSeconds 设置得足够大,以便训练器的 signal handler 能在 SIGKILL 之前刷出最后一个 checkpoint。

training-runtime.yaml 资产把这四项打包成了一个可运行的 TrainingRuntime。trainer-script 核心如下:

spec:
  template:
    spec:
      replicatedJobs:
        - name: node
          template:
            spec:
              template:
                spec:
                  terminationGracePeriodSeconds: 60   # let final checkpoint flush
                  volumes:
                    - name: ckpt
                      persistentVolumeClaim: { claimName: c12-ckpt }
                  containers:
                    - name: node
                      env:
                        - { name: CKPT_DIR, value: /mnt/ckpt/run }
                      volumeMounts:
                        - { mountPath: /mnt/ckpt, name: ckpt }
                      command: [bash, -ec]
                      args:
                        - |
                          python - <<'PY'
                          import os, glob
                          from transformers import Trainer, TrainingArguments
                          ckpt_dir = os.environ["CKPT_DIR"]
                          # Auto-detect latest checkpoint so the first run starts clean
                          # and every subsequent (re-admitted) run resumes from it.
                          ckpts = sorted(glob.glob(f"{ckpt_dir}/checkpoint-*"),
                                         key=lambda p: int(p.rsplit("-",1)[1]))
                          resume = ckpts[-1] if ckpts else None
                          args = TrainingArguments(
                              output_dir=ckpt_dir,
                              save_strategy="steps", save_steps=4, save_total_limit=2,
                              # ... rest of your training args
                          )
                          trainer = Trainer(model=..., args=args, train_dataset=...)
                          trainer.train(resume_from_checkpoint=resume)
                          PY

同样的模式也适用于 LlamaFactory(在 lf-sft.yaml 中设置 resume_from_checkpoint: true)以及其他任何基于 Trainer 的 recipe——它们本质上都可归结为:“将 output_dir 指向 PVC,设置 save_steps,并把最新 checkpoint 传给 .train()”。

save_steps 的选择应基于你能容忍的最坏抢占情况:如果每步耗时五秒,save_steps: 100 可将损失的工作量上限控制在约 10 分钟。再配合 save_total_limit,避免 PVC 无限制增长。

创建 PVC 和 runtime:

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

提交工作负载

一个训练 TrainJob,通过标签进入训练队列并使用训练优先级:

curl -fsSL $base/trainjob-low-priority.yaml | sed "s/<your-namespace>/$NS/" | kubectl create -f -

一个参与同一 cohort、并处于推理优先级的 InferenceService:

curl -fsSL $base/inference-service.yaml | sed "s/<your-namespace>/$NS/" | kubectl create -f -

你应当观察到:

  1. 训练先启动 —— 训练 Workload 在 c12-training-cq 上变为 Admitted=True(从 cohort 中的推理 CQ 借用了 GPU 配额)。
  2. 推理到达。 它的 Workload 需要一块当前借给训练的 GPU。Kueue 的经典抢占会将训练 Workload 作为目标并将其驱逐:
    status:
      conditions:
        - type: Preempted
          status: "True"
          reason: InCohortReclamation
          message: "Preempted to accommodate a workload ... due to reclamation within the cohort"
        - type: Requeued
          status: "True"
  3. 训练 pod 终止。 JobSet 发送 SIGTERM;训练器刷出最后一个 checkpoint 并退出。
  4. 推理启动,并且不受阻塞地运行。
  5. 推理结束(或缩容)。Kueue 重新准入训练;Trainer v2 重新创建 JobSet;训练器容器在 PVC 上看到 checkpoint-N/,并从该处继续。

实时观察整个往返过程:

kubectl -n "$NS" get workload -w
kubectl -n "$NS" get trainjob,pods
kubectl -n "$NS" get workload -o jsonpath='{range .items[*]}{.metadata.name}: {range .status.conditions[*]}{.type}={.status} {end}{"\n"}{end}'

安全地与在线 InferenceService 共存

这个双 CQ 的 cohort 是关键基础。再加上一些参数,日常运行会更平稳:

  • 将推理 CQ 的大小按峰值而不是平均值来配置。 如果按平均值配置,第一个流量峰值就会挤占训练已经开始消耗的容量——每次抢占都会让训练器停顿。适当增大 nominalQuota,确保稳定态推理准入时不会触及借用配额。
  • 在推理资源上保持 borrowingLimit: 0。 borrowingLimit 是借用方侧的限制:这可以防止推理工作负载消耗其他 CQ 的名义配额。它不会阻止训练借用推理的空闲名义配额;如果你需要限制某个 CQ 向 cohort 出借多少配额,请使用 Kueue 的 lendingLimit。
  • 在推理 CQ 上使用 reclaimWithinCohort: Any,而不是 LowerPriority。 使用 LowerPriority 时,只有严格低于推理优先级类的工作负载才能被抢占;Any 则允许推理在不受训练侧优先级配置影响的情况下进行抢占。
  • 在 Kueue 配置中为训练设置 PodsReady 超时。 如果一个被抢占后重新准入的训练 pod 在拉取镜像时很慢,你不希望它永久占着借来的配额;超时后它会回到队列,并让其他工作负载继续前进。
  • 为你发布的每个 InferenceService 都设置 WorkloadPriorityClass,而不只是 cohort 中的那些。 如果缺少这个标签,Workload 的优先级就会是 0,抢占规则也无法提升它。
  • 不要在 Kueue 配置里启用 manageJobsWithoutQueueName: true。 一旦开启,所有受管命名空间中的 pod/deployment 都需要带 queue 标签,这对集群组件来说很容易踩坑。
  • 让推理 predictor 的资源请求保持为单个 workload。 如果某个 InferenceService 请求的资源超过了 cohort 的推理名义配额,再多的抢占也无法满足它。应改为拆分到多个副本。

预留并共享:用于命名空间级预留的对称 cohort

上面的双 CQ 布局是有意设计成 非对称 的——推理拥有一切,训练借用一切。使用同样原语的另一种形态,则允许每个租户 预留一个底线,同时在邻居空闲时 借用整个 cohort 的剩余容量:

                     ┌──────────────────────────────┐
                     │  Cohort: shared-pool         │
                     │                              │
   ns-a label      ──┤  ns-a-cq                     │
                     │    nominalQuota: 2 GPU       │ ← reserved for ns-a
                     │    borrowingLimit: 4 GPU     │ ← may use 6 if cohort is idle
                     │    reclaimWithinCohort: Any  │
                     │                              │
   ns-b label      ──┤  ns-b-cq                     │
                     │    nominalQuota: 4 GPU       │ ← reserved for ns-b
                     │    borrowingLimit: 2 GPU     │ ← may use 6 if cohort is idle
                     │    reclaimWithinCohort: Any  │
                     │                              │
                     └──────────────────────────────┘
                       total nominal across cohort = 6 GPU

此时每个 ClusterQueue 的配置如下——注意 nominalQuota > 0 且 borrowingLimit > 0,并设置 reclaimWithinCohort: Any,这样即使邻居借走了配额,拥有者也可以把自己的预留收回来:

apiVersion: kueue.x-k8s.io/v1beta2
kind: ClusterQueue
metadata: { name: ns-a-cq }
spec:
  cohortName: shared-pool
  namespaceSelector:
    matchLabels: { kueue.x-k8s.io/queue: ns-a }
  resourceGroups:
    - coveredResources: ["nvidia.com/gpualloc"]
      flavors:
        - name: c12-default
          resources:
            - name: nvidia.com/gpualloc
              nominalQuota: 2
              borrowingLimit: 4
  preemption:
    reclaimWithinCohort: Any
    withinClusterQueue: LowerPriority

其行为如下:

  • 两个命名空间都空闲。 Cohort 持有 6 GPU 的名义容量,但都未被使用。
  • 只有 ns-a 提交任务。 ns-a 最多可准入 6 GPU(其自身的 2 个名义配额 + 从 ns-b 的空闲名义配额借来的 4 个)。
  • 随后 ns-b 提交任务。 它的 4 GPU 预留当前正借给 ns-a。ns-b 的 Workload 触发 InCohortReclamation;Kueue 会驱逐 ns-a 的 Workload,直到 ns-b 能按其预留水平准入。ns-a 的前 2 GPU(其自身的名义配额)永远不会被触碰。
  • 两个命名空间都满载。 各自都只会准入到自己的 nominalQuota。由于没有空闲配额可借,因此不会发生借用。

实用参数

  • nominalQuota 的总和必须小于等于物理容量。 预留是保证。如果 cohort 的名义总量超过物理 GPU,那么两个命名空间可能同时命中各自预留,届时其中一个会因为 device plugin 而排队,而不是因为 Kueue。
  • borrowingLimit 按你希望获得的弹性来设置。 borrowingLimit + nominalQuota 是单个 CQ 可准入规模的上限。如果你想要最大化突发能力,就把它设为整个 cohort 减去你的预留;如果你想为后到的邻居留出余量,则可以设得更小。
  • 借来的工作负载是可抢占的——要为它做 checkpoint。 任何超过 nominalQuota 准入的工作都运行在借来的配额上,并且会在拥有者收回配额的那一刻被驱逐。来自 使 TrainJob 对抢占安全 一节的 TrainJob 形态可原样套用:共享 PVC、频繁 save_steps、terminationGracePeriodSeconds: 60。如果没有这些,每次回收都会浪费实际运行时间。
  • 使用 borrowWithinCohort 控制准入时的抢占。 当 borrowWithinCohort.policy: LowerPriority 时,借用型准入可以在出借方侧抢占严格更低优先级的工作负载。若不启用这一项,借用只会发生在真正空闲的配额上——行为更安静,但在繁忙的邻居 CQ 中,高优先级作业必须等待自然释放的容量。
  • 不要轻易在同一个 cohort 中混用非对称和对称布局。 一个 borrowingLimit: 0 的 CQ(上面的推理模式)仍然可以出借空闲名义配额,但它不会从 cohort 中把配额借回来。在对称模式下,每个 CQ 既借用也出借自己的名义配额。把这两种形态混在一个 cohort 里虽然可行,但心智模型更复杂;如果两者都需要,优先考虑两个 cohort。

何时选择哪种布局

目标布局
保护在线推理;让训练在有空闲时 opportunistically 运行非对称——推理预留,训练借用(即上面的原始章节)
给每个租户一个底线;允许它们突发使用共享容量对称——每个 CQ 都有 nominalQuota > 0 且 borrowingLimit > 0
单个命名空间内,混合不同 SLO 的作业一个 CQ + 多个 WorkloadPriorityClass 值 + withinClusterQueue: LowerPriority —— 不需要 cohort

验证配置

被抢占的 Workload 上的 condition payload 是你的事实来源:

kubectl -n "$NS" get workload \
  -o jsonpath='{range .items[?(@.status.conditions[?(@.type=="Preempted")].status=="True")]}{.metadata.name}{"\n"}{end}'

一个至少被抢占过一次的训练 Workload 会显示 reason: InCohortReclamation。它在推理结束后的替代者将是一个全新的 Workload,拥有相同的 JobSet 血缘,但 UID 不同——Trainer v2 会根据 TrainJob 确定性地为它们命名,因此在重启过程中 TrainJob 名称保持不变。

若想在一个 HAMI 集群上,对这整个流程进行可重复的端到端覆盖,可以使用仓库 e2e/ harness 中的 c12_kueue_preemption.sh 用例,它会搭建 cohort、提交 TrainJob、触发一个高优先级抢占者,并断言 InCohortReclamation condition 和 checkpoint 恢复行为。

NOTE

抢占是有状态的——它会与 SIGTERM 到来时训练器正在执行的操作发生交互。在将其用于生产之前,务必至少在一个具有代表性的 TrainingRuntime + dataset 上完整运行一次抢占-恢复循环。这个机制本身是可靠的;最坏的情况只是最后一个 checkpoint 与 SIGTERM 之间会重复少量工作。

有关完整的 Kueue 配置,请参见 Kueue docs;关于底层算法,请参见 Preemption concepts page。