Ray Tune 容错机制实战指南:实验级恢复与 Trial 级故障处理

原创2026-09-20 12:26:341,750 阅读
文章标签:人工智能后端分布式训练强化学习任务调度模型推理服务

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 的说明,以下三种情况适合使用恢复机制:

  1. 调用 Tuner.fit() 的驱动脚本出错退出(例如头节点内存耗尽或磁盘占满);
  2. 实验被人为用 Ctrl+C 中断;
  3. 整个集群连同实验一起因瞬时错误崩溃(例如网络中断、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。

登录后查看全文
ray