Ctrlk
Home
For the complete documentation index, see llms.txt. This page is also available as Markdown.

缓存加载

Alluxio 通过两种方式填充缓存：被动缓存（首次读取时自动触发，无需配置）和主动预加载（通过 job load 命令在作业运行前显式加载数据）。

前提条件

  • 至少有一个 Worker 的 Alluxio 集群正在运行

  • 已配置至少一个 UFS 挂载（通过 alluxio mount list 验证）

Alluxio 会根据配置的驱逐策略自动腾出空间来存放新数据，提交加载作业前无需手动清理缓存。

被动缓存

每次缓存未命中时，Alluxio 会从 UFS 获取文件，并在将数据流式传输给应用程序的同时将其写入 Worker 缓存。无需任何配置——后续读取直接从缓存提供。

这是默认行为。当无法承受首次读取延迟时，请使用主动预加载。

使用 job load 主动预加载

job load 提交一个分布式加载作业：Coordinator 将任务分发给所有 Worker，每个 Worker 直接从 UFS 拉取分配给自己的文件。调度原理、HA 配置及高级调优请参阅 Job Service。

提交与监控

--path 支持 UFS 路径（如 s3://my-bucket/dataset/）或 Alluxio 虚拟路径（如 /mnt/dataset/），详见 CLI 参考。

# 提交（立即返回）
kubectl exec -n <NAMESPACE> alluxio-cluster-coordinator-0 -- \
  alluxio job load --path <ufs-or-alluxio-path> --submit

# 查看进度
kubectl exec -n <NAMESPACE> alluxio-cluster-coordinator-0 -- \
  alluxio job load --path <ufs-or-alluxio-path> --progress

进度输出示例：

停止运行中的作业

已停止的作业可通过再次使用 --submit 提交来恢复。已缓存的文件若加上 --skip-if-exists 参数则会被跳过。

常用参数

参数
说明

--submit

异步提交作业（立即返回）

--progress

查看已提交作业的进度

--stop

停止运行中的作业

--verify

加载完成后验证所有文件均已缓存，并重新加载缺失的文件

--replicas <n>

每个文件加载 n 个副本（默认：1）；适用于高并发读取场景

--skip-if-exists

跳过已完全缓存的文件（可安全重复执行加载作业）

--load-policy IF_CHANGED

对每个已缓存文件与 UFS 元数据进行比对，仅重新加载内容发生变化的文件。适用于可变数据集的增量同步。

--metadata-only

仅加载文件元数据，不缓存文件数据

--batch-size <n>

每个 Worker 每批处理的文件数，默认值 200。小文件（< 1 MB）建议调大至 2000–5000 以提升吞吐量；大文件（> 100 MB）保持 200 或更低以避免 Worker 内存压力。

--partial-listing

在完整目录列举完成前开始加载；适用于超大目录

--index-file <ufs-path>

从 UFS 索引文件中加载指定文件列表（每行一个路径）

完整参数说明请参阅 job load CLI 文档。

从索引文件加载

适用于选择性加载，或目录树过大不适合整体遍历的场景：

索引文件格式——每行一个 UFS 路径，以 # 开头的行为注释：

目录路径须以 / 结尾才会被递归加载。

增量加载（可变数据集）

当数据集周期性更新时（例如每日模型 checkpoint、更新的训练集划分），使用 --load-policy IF_CHANGED 只同步自上次加载以来发生变化的文件：

--load-policy IF_CHANGED 会对每个已缓存文件与 UFS 元数据进行比对，仅在内容发生变化时重新加载；尚未缓存的文件会无条件加载。这使得它非常适合可变数据集的周期性同步：新文件会被缓存，已变化的文件会被刷新，未变化的文件会被跳过。

参数
已缓存文件
未缓存文件

--submit（无额外 flag）

无条件重新加载

加载

--skip-if-exists

跳过

加载

--load-policy IF_CHANGED

仅在内容变化时重新加载

加载

与 ML 训练集成

典型工作流：加载数据 → 验证 → 启动训练。

近 100% 缓存覆盖率： 对于关键数据集，建议在第一次 job 达到 SUCCEEDED 后再执行一次 --skip-if-exists 的补充加载。极少数情况下（Worker 短暂故障或哈希环边界时序问题），单次加载可能遗漏极小比例的文件。第二次执行可以填补这些空缺，且不会重复加载已缓存的数据：

故障处理

Job State: FAILED，Files Failed > 0

查看文件级别的失败列表：

常见原因：UFS 访问错误、网络超时或凭证缺失。排查根本原因后，使用 --skip-if-exists 重新提交，避免重复加载已缓存的文件。

提交后立即出现 Job State: FAILED

使用 --verbose 获取详情：

常见原因：挂载表中找不到路径（通过 alluxio mount list 验证），或缓存配额不足。

加载成功但读取仍走 UFS

验证特定文件是否已缓存：

若文件在加载成功后显示为未缓存，数据可能已被驱逐。请检查缓存容量和驱逐配置——参阅缓存驱逐。集群级缓存命中率可通过监控查看。

历史作业保留

已完成的作业记录会保留一段可配置的时间，默认为 7 天。如需调整：

相关文档

Last updated