# 设置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断点续作流程   
![](https://support.huaweicloud.com/usermanual-aidatalake/zh-cn_image_0000002783728462.png)
 表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](https://support.huaweicloud.com/qs-obs/obs_qs_0001.html)和[创建自定义委托](https://support.huaweicloud.com/usermanual-aidatalake/aidatalake_01_0078.html)。
#### 启用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官网文档](https://docs.ray.io/en/latest/data/api/doc/ray.data.checkpoint.interfaces.CheckpointConfig.html#ray.data.checkpoint.interfaces.CheckpointConfig)。
 表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读取时，在恢复期间加载检查点文件的过滤器。                                                                 |
   
关于提交作业的完整操作，请参见：
- [基于RayCluster的数据处理](https://support.huaweicloud.com/qs-aidatalake/aidatalake_01_0004.html)
- [基于RayJob的数据处理](https://support.huaweicloud.com/qs-aidatalake/aidatalake_01_0079.html)
 
#### 常见问题
#### 问题 1: 再次执行时全部数据被重新处理，未实现跳过？
可能原因:
1. Checkpoint配置在读取数据之后才设置，需要在读取数据配置之前设置。
2. 设置delete_checkpoint_on_success为True，作业成功后Checkpoint已被清理。
3. ID生成方式不具备跨运行稳定性。
 
#### 问题 2: 提示 "checkpointing will be disabled" 的含义？
该提示表明当前作业结构不支持Checkpoint（未读取源数据，或不含写入动作）。系统自动禁用Checkpoint并照常执行，作业结果正确，但不具备断点续作能力。
#### 问题 3: 报错 "ID column xxx is absent in the block" 如何处理？
该报错表明写入阶段发现ID列缺失，请检查数据处理逻辑是否删除或改写了ID列。
#### 问题 4: 处理图片、视频等文件数据时，ID 列如何选择？
建议使用文件路径作为ID：通过read_images(paths, include_paths=True) 读取后，每行数据自带path列（一个文件对应一行，且唯一），将id_column设置为 "path" 即可。
不建议使用文件内容哈希作为ID，因为图片经解码、缩放等处理后内容发生变化，哈希值每次运行不同，导致Checkpoint失效。
#### 问题 5: 数据无主键，如何生成ID列？
可通过add_column添加基于物理行号的固定序号列，或将多个既有列拼接为唯一字符串。关键在于生成规则的确定性：同一份数据在每次运行中生成的ID必须一致。
#### 问题 6: 单文件包含多行数据（如TFRecord），能否用路径作为ID？
不能。同一文件的多行数据会共用同一路径 ID，断点续作时整个文件会被一并过滤。应使用路径+行内序号拼接为唯一ID。
#### 问题 7: 作业内部任务自动重试，是否会产生重复数据？
Checkpoint防止的是作业整体重跑导致的重复，不防止作业内部单个任务自动重试导致的重复。若存在任务级重试导致重复写入的风险，需另行配置防重机制。
