更新时间:2026-11-13 GMT+08:00
分享

设置Ray作业断点续作

Ray Data Checkpoint是Ray提供的作业级断点续作能力。启用后,数据处理作业在运行过程中发生失败时,已完成部分的数据处理结果得以保留;重新提交作业后,系统自动跳过已完成的数据,仅处理剩余数据,从而避免从头重跑造成的计算资源浪费。

操作场景

Checkpoint仅对读取源数据 > 处理数据 > 写入目标数据的完整流水线生效:

  • 作业读取了外部源数据,经处理流水线后写入目标位置,具备断点续作能力。
  • 作业未读取任何源数据(数据在作业内部生成),或作业不包含写入动作时,Checkpoint不生效。此时系统会打印提示信息并自动禁用Checkpoint,作业本身照常执行,结果正确,但不具备断点续作能力。

原理介绍

Checkpoint以数据中的ID列作为记账依据,记录每条数据的处理状态。使用Checkpoint要求数据集中存在一列,每行唯一,且跨多次运行保持稳定的ID。

以某个记账表为例,如表1所示,每行数据均标记处理状态和结果。断点续作通过重新提交同一作业脚本实现,包含以下三种执行场景。

  • 场景A:首次执行,全部数据被正常处理,处理结果及ID写入Checkpoint指定路径。
  • 场景B:失败后恢复,若某次执行中途失败(如ID=1004失败),失败前已处理完成的数据(ID=1001~1003)已写入Checkpoint;重新提交后,系统从断点继续处理剩余数据(ID=1004~1006),失败前的结果不会重复计算。
  • 场景C:再次提交作业,首次执行已全部成功,读取源数据后,获取每一行数据ID对应的处理状态和结果后,过滤已执行完成的数据,直接读取数据结果,作业不再产生重复的数据写入。
图1 断点续作流程
表1 记账表

ID

处理状态

结果

1001

已处理

已写入

1002

已处理

已写入

1003

已处理

已写入

1004

失败(断点)

未写入

1005

待处理

未写入

1006

待处理

未写入

约束与限制

以下约束项需要您自行遵守,违反后可能不产生报错,但会导致作业重跑时数据重复或丢失,且难以察觉。

表2 约束与限制说明

约束项

说明

ID列取值必须唯一

若多条数据共用同一ID,断点续作时这些数据会被一并过滤,造成数据缺失。

ID必须按确定性规则生成

ID必须按确定性规则生成(如物理行号、既有主键),不得使用随机数、UUID、时间戳等每次运行结果不同的方式。否则Checkpoint中记录的ID与后续运行中数据的ID无法匹配,导致全部数据被重新处理,或部分数据被错误过滤。

ID列原样保留

数据处理逻辑(map/map_batches)不得修改ID列的取值,其他列可正常处理,ID列须原样保留。ID被修改后,后续运行中原始ID无法匹配Checkpoint,同一数据被重复处理,造成数据重复。

不得删除ID列

数据处理逻辑不得丢弃ID列(如map返回结果中缺失该列)。

Checkpoint配置须在读取数据之前设置

Checkpoint配置必须在读取源数据之前写入DataContext。若在读取数据之后才设置配置,Checkpoint不会生效,且无任何报错提示。

前提条件

已创建OBS桶,且作业脚本有权限读写OBS。具体操作,请参见通过控制台快速使用OBS和创建自定义委托。

启用Checkpoint

您可以在编写作业脚本时开启Checkpoint,示例如下:

import ray.data
from ray.data import DataContext
from ray.data.checkpoint import CheckpointConfig

 # 1. 配置Checkpoint(须在读取数据之前完成)
 ctx = DataContext.get_current()
 ctx.checkpoint_config = CheckpointConfig(
     id_column="order_id",                 # 用于记账的ID列
     checkpoint_path="obs://my-bucket/ckpt", # Checkpoint存放路径
     delete_checkpoint_on_success=True,     # 作业成功后清理Checkpoint,如果设置为False或者其他异常场景,需要用户手动清理
 )

 # 2. 原有处理流程不变
 ds = ray.data.read_parquet("obs://my-bucket/input/")
 ds = ds.map_batches(clean_row)
 ds.write_parquet("obs://my-bucket/output/")

 # 3. 作业结束,关闭配置
 ctx.checkpoint_config = None

参数说明如表3所示,关于Checkpoint的更多信息,请参见Ray官网文档。

表3 参数说明

参数

类型

说明

id_column

str | None

输入数据集中的ID列名称。ID值必须在数据集的所有行中唯一,且必须在所有操作符期间保持不变。

checkpoint_path

str | None

检查点数据存放路径。可以是云对象存储路径(如obs://bucket/ckpt)或文件系统路径;若是文件系统路径,则必须是整个集群可访问的网络挂载文件系统(如/mnt/cluster_storage/)。

delete_checkpoint_on_success

bool

为True时,数据集执行成功后自动删除检查点数据。仅支持基于批处理的后端。

override_filesystem

pyarrow.fs.FileSystem | None

覆盖用于读写检查点数据的pyarrow.fs.FileSystem对象,仅使用自定义凭据时配置。

override_backend

CheckpointBackend | None

覆盖用于访问检查点后端存储的CheckpointBackend对象。

write_num_threads

int

输入已完成行检查点文件的线程数。

checkpoint_path_partition_filter

PathPartitionFilter | None

从checkpoint_path读取时,在恢复期间加载检查点文件的过滤器。

关于提交作业的完整操作,请参见:

常见问题

相关文档