Ray Tune 容错机制实战指南:实验级恢复与 Trial 级故障处理
Ray Tune 容错机制实战指南:实验级恢复与 Trial 级故障处理
导读
在分布式机器学习实验中,节点因内存溢出(OOM)、磁盘占满、网络抖动或抢占式 Spot 实例回收而宕机是常态。Ray Tune 提供了一套完整的容错体系:实验级容错通过 Tuner.restore 从断点恢复被中断的实验,Trial 级容错通过 FailureConfig 自动重调度失败的单个 Trial。读完本文,你将掌握如何在 Ray Tune 中启用实验级与 Trial 级容错,包括恢复被中断的实验、配置自动恢复(auto-resume)、处理 Ray 对象引用与 Ray Data 的恢复,以及设置单个 Trial 的最大失败重试次数。
容错机制能带来的两个直接收益:保存训练进度、节省时间与算力(即使节点失败也不会从头再来),以及在分布式场景下充分利用可抢占的 Spot 实例以降低成本。
注意:在分布式 Tune 实验中,启用容错的前提是先配置某种持久化存储,将所有 Trial 结果与检查点汇总到统一位置,参见 tune-storage-options。本文中恢复实验用到的
~/ray_results/tune_fault_tolerance_guide目录正是一个本地持久化示例。
实验级容错:恢复被中断的整个实验
实验级容错的核心 API 是 Tuner.restore(源码位于 python/ray/tune/tuner.py),它可以从上次中断的位置继续一个此前被打断的实验。
什么场景应该使用 Tuner.restore
根据 tune-fault-tolerance.rst 的说明,以下三种情况适合使用恢复机制:
- 调用
Tuner.fit()的驱动脚本出错退出(例如头节点内存耗尽或磁盘占满); - 实验被人为用
Ctrl+C中断; - 整个集群连同实验一起因瞬时错误崩溃(例如网络中断、Ray 对象存储内存耗尽)。
需要特别澄清 Tuner.restore 的边界:它不是用来"恢复一个已终止的实验然后修改超参数搜索空间或停止条件"的。实验恢复的目的是精确地重新完成之前通过 Tuner.fit() 提交的那个任务。例如,一个配置为运行 10 个训练迭代且所有 Trial 已完成的实验,你不能通过 Tuner.restore 把它改造成 20 个迭代继续训练——正确做法是开启一个新实验,并用上一个实验的检查点初始化模型权重(参见 tune-iterative-experimentation FAQ)。
另一个关键限制:用户自定义训练循环中的 bug 无法靠恢复解决。导致实验崩溃的原因必须是瞬时性(ephemeral)的,这样恢复后的重试才有成功可能。从源码看,Tuner.restore 的 docstring 也强调恢复路径必须指向可信的实验目录——实验状态使用 pickle 序列化,从不可信路径恢复会执行任意 Python 代码(见 tuner.py 的 warning)。
恢复一个 Tune 实验:完整示例
下面的训练函数演示了容错的前提条件——Trainable 必须实现检查点的保存与加载(详见 tune-trial-checkpoint),否则恢复后无法续接训练进度。完整示例代码位于 doc/source/tune/doc_code/fault_tolerance.py:
import json
import os
import tempfile
from ray import tune
def trainable(config):
# 检查点加载:恢复时从这里继续
checkpoint = tune.get_checkpoint()
start = 1
if checkpoint:
with checkpoint.as_directory() as checkpoint_dir:
with open(os.path.join(checkpoint_dir, "checkpoint.json"), "r") as f:
state = json.load(f)
start = state["epoch"] + 1
for epoch in range(start, config["num_epochs"]):
# 训练逻辑...
# 检查点保存
with tempfile.TemporaryDirectory() as temp_checkpoint_dir:
with open(os.path.join(temp_checkpoint_dir, "checkpoint.json"), "w") as f:
json.dump({"epoch": epoch}, f)
tune.report(
{"epoch": epoch},
checkpoint=tune.Checkpoint.from_directory(temp_checkpoint_dir),
)
tuner = tune.Tuner(
trainable,
param_space={"num_epochs": 10},
run_config=tune.RunConfig(
storage_path=os.path.expanduser("~/ray_results"),
name="tune_fault_tolerance_guide",
),
)
result_grid = tuner.fit()
要点解读:
- 检查点加载:通过
tune.get_checkpoint()获取最新检查点,用checkpoint.as_directory()解包到本地目录并读取其中的checkpoint.json,从而拿到上次完成的epoch,训练从epoch + 1续跑; - 检查点保存:每个 epoch 将状态写入临时目录,并通过
tune.report(..., checkpoint=tune.Checkpoint.from_directory(...))上报指标与检查点; - 结果落盘:实验的结果与检查点按照
RunConfig配置保存到~/ray_results/tune_fault_tolerance_guide(storage_path为~/ray_results,name为tune_fault_tolerance_guide)。
当实验因前述任一原因中断后,用这个路径即可恢复:
tuner = tune.Tuner.restore(
os.path.expanduser("~/ray_results/tune_fault_tolerance_guide"),
trainable=trainable,
resume_errored=True,
)
tuner.fit()
技巧:也可以从云存储桶路径恢复,只需把 path 换成 s3:// 前缀:
tuner = tune.Tuner.restore(
path="s3://cloud-bucket/tune_fault_tolerance_guide", trainable=trainable
)
从 Tuner.restore 的源码签名(tuner.py)可以看到它支持的完整参数:path、trainable、resume_unfinished、resume_errored、restart_errored、param_space、storage_filesystem,以及实验性的 _resume_config。其中 trainable 必须与初始化原 Tuner 时使用的 trainable 一致。
恢复配置:控制哪些 Trial 被恢复
Tune 允许根据实验中断时各 Trial 的状态,精细配置恢复行为:
- 中断时处于
RUNNING状态的未完成 Trial 默认会被恢复; - 处于
ERRORED状态的 Trial 可以选择从检查点恢复(resume)或从零重跑(restart); - 已经
TERMINATED的 Trial 无法被恢复。
对应源码中的三个开关(语义详见 tuner.py 的 docstring):
tuner = tune.Tuner.restore(
os.path.expanduser("~/ray_results/tune_fault_tolerance_guide"),
trainable=trainable,
resume_errored=True, # 出错 Trial:从最新检查点恢复
restart_errored=False, # 出错 Trial:若为 True 则强制从零重跑(不加载检查点)
resume_unfinished=True, # 未完成 Trial:继续运行(False 则标记为终止)
)
从源码实现看,这三个标志最终会转换为 ResumeConfig(定义在 python/ray/tune/tune_config.py):resume_unfinished=True 对应 ResumeType.RESUME,否则为 SKIP;而 resume_errored 与 restart_errored 分别映射出错 Trial 的 RESUME 与 RESTART(tuner.py)。此外,已完成的 Trial 始终会被加入结果总览表,但不会被恢复运行。
自动恢复(Auto-resume):单脚本复用
在生产环境中,往往希望一个脚本同时承担两种职责:(1) 首次运行时启动初始训练,(2) 若已有运行记录则直接恢复实验。此时可用 Tuner.can_restore 工具(源码见 tuner.py,其 docstring 中即给出了此复用模式的用法):
import os
from ray import tune
storage_path = os.path.expanduser("~/ray_results")
exp_name = "tune_fault_tolerance_guide"
path = os.path.join(storage_path, exp_name)
if tune.Tuner.can_restore(path):
tuner = tune.Tuner.restore(path, trainable=trainable, resume_errored=True)
else:
tuner = tune.Tuner(
trainable,
param_space={"num_epochs": 10},
run_config=tune.RunConfig(storage_path=storage_path, name=exp_name),
)
tuner.fit()
脚本第一次运行时 can_restore 返回 False,走新建 Tuner 的分支启动初始训练;第二次运行(首次运行已中断)时 can_restore 返回 True,自动切换到恢复分支,从第一次运行的输出续跑。can_restore 还支持传入自定义 storage_filesystem(pyarrow.fs.FileSystem),适用于自定义文件系统场景。
进阶:使用 Ray 对象引用时如何恢复实验
实验恢复通常发生在与原运行不同的 Ray session 中,此时 Ray 对象引用会被自动垃圾回收。如果在实验状态里保存了对象引用(例如保存在每个 Trial 的 config 中),恢复后去 ray.get 这些引用将无法正常工作——因为引用指向的对象已经不存在了。
解决办法是:重新创建这些对象、放入 Ray 对象存储,然后把新的对象引用传给 Tune。Tuner.restore 的 param_space 参数正是为此设计的——它期望 param_space 与原实验未修改,恢复时只使用其中更新过的对象引用(tuner.py)。
示例:对 ray.put 的大模型对象引用做网格搜索
假设我们有一批大型预训练模型(例如用于计算 Inception Score 的图像分类模型),想对"选哪个模型"做调优,每个 Trial 从对象存储中取一个模型使用。完整代码在 fault_tolerance.py:
import ray
from ray import tune
class LargeModel:
def __init__(self, model_id):
self.model_id = model_id
# Load weights based on the `model_id`...
def train_fn(config):
# 从对象存储中检索模型
model = ray.get(config["model_ref"])
print(model.model_id)
# 模型可能很大,因此用 ray.put 放入对象存储以在 Trial 间共享
model_refs = [ray.put(LargeModel(1)), ray.put(LargeModel(2))]
tuner = tune.Tuner(
train_fn,
# 对对象引用做调优!
param_space={"model_ref": tune.grid_search(model_refs)},
run_config=tune.RunConfig(
storage_path=os.path.expanduser("~/ray_results"), name="restore_object_refs"
),
)
tuner.fit()
恢复时,只需通过 param_space 重新指定对象引用——先重建对象并 ray.put,再把新引用交给 Tuner.restore:
# 重新创建对象并放入对象存储
param_space = {
"model_ref": tune.grid_search([ray.put(LargeModel(1)), ray.put(LargeModel(2))])
}
tuner = tune.Tuner.restore(
os.path.expanduser("~/ray_results/restore_object_refs"),
trainable=train_fn,
# 重新指定 param_space 以更新对象引用
param_space=param_space,
resume_errored=True,
)
tuner.fit()
对 Ray Data 做调优时的恢复
如果你调优的是 Ray Data 数据集,同样需要在 param_space 中重新指定它们——Ray Data 内部可能包含对象引用,所以上文描述的问题同样适用。示例:
ds_1 = ray.data.from_items([{"x": i, "y": 2 * i} for i in range(128)])
ds_2 = ray.data.from_items([{"x": i, "y": 3 * i} for i in range(128)])
param_space = {
"datasets": {"train": tune.grid_search([ds_1, ds_2])},
}
tuner = tune.Tuner.restore(..., param_space=param_space)
Trial 级容错:用 FailureConfig 处理单个 Trial 失败
与实验级容错针对"整个实验中断"不同,Trial 级容错处理的是集群中单个 Trial 的失败,常见诱因包括:
- 使用可抢占的 Spot 实例运行;
- 瞬时网络连接问题;
- 节点内存溢出或磁盘占满。
Ray Tune 通过 FailureConfig 配置单个 Trial 的失败处理策略(FailureConfig 在 python/ray/tune/impl/config.py 中定义)。仍以上文实现了检查点保存与加载的 trainable 为例,配置方式如下:
from ray import tune
tuner = tune.Tuner(
trainable,
param_space={"num_epochs": 10},
run_config=tune.RunConfig(
storage_path=os.path.expanduser("~/ray_results"),
name="trial_fault_tolerance",
failure_config=tune.FailureConfig(max_failures=3),
),
)
tuner.fit()
其行为语义是:
- 当某个 Trial 遇到运行时错误时,上述配置会重新调度该 Trial 最多
max_failures=3次; - 类似地,如果节点 X 发生故障(如被抢占或失去连接),该配置会把原本运行在节点 X 上的所有 Trial 重新调度,最多重试 3 次。
从底层实现看,max_failures 正是 Trial 对象的一个核心字段(见 python/ray/tune/experiment/trial.py 与 python/ray/tune/experiment/experiment.py,默认值为 0,即不重试)。其工作机制是:Trial 失败后,Tune 的执行控制器会依据 FailureConfig 决定是否将 Trial 重新入队,并在每次重试时优先加载该 Trial 最近一次保存的检查点继续训练——这正是前文 Trainable 中"检查点加载"逻辑发挥作用的地方:只有实现了 tune.get_checkpoint() 的正确读取,重试才能从断点续跑而非从头开始。
实践建议:将
FailureConfig(max_failures=N)与持久化存储(如云存储路径)结合使用,是应对 Spot 实例抢占的标准组合。抢占发生时,节点上的 Trial 自动迁移到新节点并从检查点恢复,配合较大的max_failures值,可以在不牺牲训练进度的前提下大幅降低实例成本。
总结
本指南覆盖了 Ray Tune 提供的两类容错能力:
| 容错层级 | 核心 API / 配置 | 适用场景 | 关键参数 |
|---|---|---|---|
| 实验级 | Tuner.restore / Tuner.can_restore |
驱动脚本崩溃、Ctrl+C 中断、整个集群瞬时故障 | resume_unfinished、resume_errored、restart_errored、param_space |
| Trial 级 | FailureConfig |
Spot 实例抢占、网络抖动、节点 OOM / 磁盘占满 | max_failures |
两个层级的共同前提是:Trainable 必须正确实现检查点的保存与加载,且实验配置了持久化存储。实验级容错用于把"整个实验"从断点拉回来,Trial 级容错用于在实验运行中自动消化单个 Trial 的失败;当两者配合使用时,即使面对恶劣的分布式环境,长时间运行的调优任务也能以最小的人力干预稳定跑完。
如需进一步深入,可继续阅读仓库中的相关文档:tune-storage-options(持久化存储配置)、tune-distributed-ref(分布式实验)、tune-trial-checkpoint(检查点机制),以及本文所有示例的完整可运行源码 fault_tolerance.py 和恢复逻辑核心实现 tuner.py。