maxDuration 超时保护

job.maxDuration 是可选字段，面向需要在一段确定时间内持续持有 GPU 的用户：你声明计划持有多久，到点平台自动停止任务、释放 GPU、收口计费，等效于你手动执行 runwhere stop job <name>。

先说默认行为：任务到达终态（进程退出、成功或失败）后，平台本来就会自动释放 GPU 并停止计费，这是平台的既有行为，无需任何声明。 所以普通任务不需要这个字段——默认不推荐声明。

什么时候才需要

只有一种情况：你对「这块 GPU 要占多久」有明确计划，希望把计划变成对平台的声明。

• 长训练：预计 3 天的训练，声明 maxDuration: "3d"。到点必定释放、计费必定收口，最多只花声明时长的钱，中途无需值守、无需记得手动 stop。
• 有明确截止时点的占用：比如临时演示环境、截至某时的对比实验，用声明代替人脑记停。

一句话原则：默认不推荐。 只有对持有时长有明确计划时才声明，并按计划如实填写；填一个远超实际的时长（比如 "30d"）等于没声明。

字段格式

字段位于 YAML 顶层 job 段：

job:
  name: my-training-job
  maxDuration: "8h"    # 可选。缺省 = -1 = 永不超时

时长字符串必须只带一个单位；"8h30m" 这样的复合格式不支持。取值本身没有硬上限——但如前述，过大的时长失去了声明的意义，请按计划合理设置。

计时起点：从平台开始为你供给 GPU 节点起算（包含镜像拉取、环境初始化等启动时间，通常比任务进程真正开始跑早几分钟），不是从提交时刻算起。

非法取值（0、除 -1 外的负数、无法解析的字符串、复合格式）会在提交时直接拒绝，不会创建任务，报错形如：

job.maxDuration 非法: "8h30m"。期望 -1（永不超时）或正时长（如 "30m"、"8h"、"7d"，或秒数整数）

到点后会发生什么

声明时点到达时：

• 任务还在跑 → 被自动停止，与手动 runwhere stop job 的效果一致；Notebook 类型是挂起（GPU 释放、访问 URL 保留，之后用 runwhere resume <name> 可原样恢复）。任务已提前结束 → 直接释放节点。
• GPU 必定释放。超时判定每分钟执行一轮，实际释放最多比声明时点晚约 1 分钟，计费按实际释放时刻收口。
• 任务终态原因：到点时还在跑的任务标 max_duration_exceeded；提前自然结束的保留原终态原因（succeeded / failed）；手动停止标 stopped。在 runwhere describe job <name> 中可以看到。
• 声明了 storage.checkpoint 的任务，checkpoint 数据保留，可以用原 YAML 通过 runwhere resume <name> 恢复，训练代码从最近一次 checkpoint 继续（参见 Checkpoint 最佳实践）。

如果任务在声明时点之前自然到达终态（成功或失败），GPU 不会提前释放——节点为你保留到声明时点，期间照价计费；计费按实际释放时刻收口。想提前释放，随时手动 runwhere stop job <name>（手动停止优先于持有声明，立即释放）。

完整示例

一个声明了 8 小时持有上限的训练任务：

kind: Training
version: v1

job:
  name: llama3-lora-overnight
  maxDuration: "8h"

environment:
  image: pytorch/pytorch:2.4.1-cuda12.1-cudnn9-runtime
  command: python finetune.py --model_name=/models/llama3-8b --lora_r=16

resources:
  gpuNum: 8
  gpuType: a100-80g

storage:
  workdirs:
    - path: "."
  checkpoint:
    path: checkpoints/llama3-lora

这个任务最多持有 GPU 8 小时，之后平台自动停止并释放；checkpoint 保留，可以随时 resume。

常见问题