# 缓存加载 Alluxio 通过两种方式填充缓存：**被动缓存**（首次读取时自动触发，无需配置）和**主动预加载**（通过 `job load` 命令在作业运行前显式加载数据）。 ## 前提条件 * 至少有一个 Worker 的 Alluxio 集群正在运行 * 已配置至少一个 UFS 挂载（通过 `alluxio mount list` 验证） {% hint style="info" %} Alluxio 会根据配置的驱逐策略自动腾出空间来存放新数据，提交加载作业前无需手动清理缓存。 {% endhint %} ## 被动缓存 每次缓存未命中时，Alluxio 会从 UFS 获取文件，并在将数据流式传输给应用程序的同时将其写入 Worker 缓存。无需任何配置——后续读取直接从缓存提供。 这是默认行为。当无法承受首次读取延迟时，请使用主动预加载。 ## 使用 `job load` 主动预加载 `job load` 提交一个分布式加载作业：Coordinator 将任务分发给所有 Worker，每个 Worker 直接从 UFS 拉取分配给自己的文件。调度原理、HA 配置及高级调优请参阅 [Job Service](/ee-ai-cn/administration/managing-job-service.md)。 ### 提交与监控 `--path` 支持 UFS 路径（如 `s3://my-bucket/dataset/`）或 Alluxio 虚拟路径（如 `/mnt/dataset/`），详见 [CLI 参考](/ee-ai-cn/reference/user-cli.md#job-load)。 {% tabs %} {% tab title="Kubernetes (Operator)" %} ```shell # 提交（立即返回） kubectl exec -n alluxio-cluster-coordinator-0 -- \ alluxio job load --path --submit # 查看进度 kubectl exec -n alluxio-cluster-coordinator-0 -- \ alluxio job load --path --progress ``` {% endtab %} {% tab title="Docker / Bare-Metal" %} ```shell # 提交（立即返回） bin/alluxio job load --path --submit # 查看进度 bin/alluxio job load --path --progress ``` {% endtab %} {% endtabs %} 进度输出示例： ```console Progress for loading path 's3://my-bucket/dataset/': Settings: replicas: ALL batch-size: 200 verify: false metadata-only: false quota-check: false Time start: 2026-04-15T22:05:01 Time finished: 2026-04-15T22:05:08 Time Elapsed: 7s Job State: SUCCEEDED Inodes Scanned: 1000 Non Empty File Copies Loaded: 1000 Bytes Scanned: 125.00MiB Bytes Loaded: 125.00MiB Throughput: 17.86MiB/s File Failure rate: 0.00% Subtask Failure rate: 0.00% Files Failed: 0 Subtask Retry rate: 0.00% Subtasks on Retry Dead Letter Queue: 0 ``` ### 停止运行中的作业 {% tabs %} {% tab title="Kubernetes (Operator)" %} ```shell kubectl exec -n alluxio-cluster-coordinator-0 -- \ alluxio job load --path --stop ``` {% endtab %} {% tab title="Docker / Bare-Metal" %} ```shell bin/alluxio job load --path --stop ``` {% endtab %} {% endtabs %} 已停止的作业可通过再次使用 `--submit` 提交来恢复。已缓存的文件若加上 `--skip-if-exists` 参数则会被跳过。 ### 常用参数 | 参数 | 说明 | | -------------------------- | ---------------------------------------------------------------------------------------------------- | | `--submit` | 异步提交作业（立即返回） | | `--progress` | 查看已提交作业的进度 | | `--stop` | 停止运行中的作业 | | `--verify` | 加载完成后验证所有文件均已缓存，并重新加载缺失的文件 | | `--replicas ` | 每个文件加载 `n` 个副本（默认：1）；适用于高并发读取场景 | | `--skip-if-exists` | 跳过已完全缓存的文件（可安全重复执行加载作业） | | `--load-policy IF_CHANGED` | 对每个已缓存文件与 UFS 元数据进行比对，仅重新加载内容发生变化的文件。适用于可变数据集的增量同步。 | | `--metadata-only` | 仅加载文件元数据，不缓存文件数据 | | `--batch-size ` | 每个 Worker 每批处理的文件数，默认值 200。小文件（< 1 MB）建议调大至 2000–5000 以提升吞吐量；大文件（> 100 MB）保持 200 或更低以避免 Worker 内存压力。 | | `--partial-listing` | 在完整目录列举完成前开始加载；适用于超大目录 | | `--index-file ` | 从 UFS 索引文件中加载指定文件列表（每行一个路径） | 完整参数说明请参阅 [`job load` CLI 文档](/ee-ai-cn/reference/user-cli.md#job-load)。 ### 从索引文件加载 适用于选择性加载，或目录树过大不适合整体遍历的场景： {% tabs %} {% tab title="Kubernetes (Operator)" %} ```shell kubectl exec -n alluxio-cluster-coordinator-0 -- \ alluxio job load --index-file s3://my-bucket/load-manifest.txt --submit ``` {% endtab %} {% tab title="Docker / Bare-Metal" %} ```shell bin/alluxio job load --index-file s3://my-bucket/load-manifest.txt --submit ``` {% endtab %} {% endtabs %} 索引文件格式——每行一个 UFS 路径，以 `#` 开头的行为注释： ``` s3://my-bucket/dataset/train/ s3://my-bucket/dataset/val/file.parquet # s3://my-bucket/dataset/test/ <- 跳过此行 ``` 目录路径须以 `/` 结尾才会被递归加载。 ### 增量加载（可变数据集） 当数据集周期性更新时（例如每日模型 checkpoint、更新的训练集划分），使用 `--load-policy IF_CHANGED` 只同步自上次加载以来发生变化的文件： {% tabs %} {% tab title="Kubernetes (Operator)" %} ```shell kubectl exec -n alluxio-cluster-coordinator-0 -- \ alluxio job load --path --submit --load-policy IF_CHANGED ``` {% endtab %} {% tab title="Docker / Bare-Metal" %} ```shell bin/alluxio job load --path --submit --load-policy IF_CHANGED ``` {% endtab %} {% endtabs %} `--load-policy IF_CHANGED` 会对每个**已缓存**文件与 UFS 元数据进行比对，仅在内容发生变化时重新加载；尚未缓存的文件会无条件加载。这使得它非常适合可变数据集的周期性同步：新文件会被缓存，已变化的文件会被刷新，未变化的文件会被跳过。 | 参数 | 已缓存文件 | 未缓存文件 | | -------------------------- | ----------- | ----- | | `--submit`（无额外 flag） | 无条件重新加载 | 加载 | | `--skip-if-exists` | 跳过 | 加载 | | `--load-policy IF_CHANGED` | 仅在内容变化时重新加载 | 加载 | ## 与 ML 训练集成 典型工作流：加载数据 → 验证 → 启动训练。 {% tabs %} {% tab title="Kubernetes (Operator)" %} ```shell # 1. 提交加载 kubectl exec -n alluxio-cluster-coordinator-0 -- \ alluxio job load --path s3://my-bucket/dataset/ --submit --verify # 2. 轮询直到完成 kubectl exec -n alluxio-cluster-coordinator-0 -- \ alluxio job load --path s3://my-bucket/dataset/ --progress # 重复执行直到 "Job State: SUCCEEDED"，然后启动训练 Pod ``` {% endtab %} {% tab title="Docker / Bare-Metal" %} ```shell # 1. 提交加载 bin/alluxio job load --path s3://my-bucket/dataset/ --submit --verify # 2. 等待完成 bin/alluxio job load --path s3://my-bucket/dataset/ --progress # 重复执行直到 "Job State: SUCCEEDED" # 3. 启动训练 python train.py --data /mnt/alluxio/fuse/dataset/ ``` {% endtab %} {% endtabs %} {% hint style="info" %} **近 100% 缓存覆盖率：** 对于关键数据集，建议在第一次 job 达到 `SUCCEEDED` 后再执行一次 `--skip-if-exists` 的补充加载。极少数情况下（Worker 短暂故障或哈希环边界时序问题），单次加载可能遗漏极小比例的文件。第二次执行可以填补这些空缺，且不会重复加载已缓存的数据： {% tabs %} {% tab title="Kubernetes (Operator)" %} ```shell kubectl exec -n alluxio-cluster-coordinator-0 -- \ alluxio job load --path --submit --skip-if-exists ``` {% endtab %} {% tab title="Docker / Bare-Metal" %} ```shell bin/alluxio job load --path --submit --skip-if-exists ``` {% endtab %} {% endtabs %} {% endhint %} ## 故障处理 **`Job State: FAILED`，`Files Failed > 0`** 查看文件级别的失败列表： {% tabs %} {% tab title="Kubernetes (Operator)" %} ```shell kubectl exec -n alluxio-cluster-coordinator-0 -- \ alluxio job load --path --progress --file-status FAILURE ``` {% endtab %} {% tab title="Docker / Bare-Metal" %} ```shell bin/alluxio job load --path --progress --file-status FAILURE ``` {% endtab %} {% endtabs %} 常见原因：UFS 访问错误、网络超时或凭证缺失。排查根本原因后，使用 `--skip-if-exists` 重新提交，避免重复加载已缓存的文件。 **提交后立即出现 `Job State: FAILED`** 使用 `--verbose` 获取详情： {% tabs %} {% tab title="Kubernetes (Operator)" %} ```shell kubectl exec -n alluxio-cluster-coordinator-0 -- \ alluxio job load --path --progress --verbose ``` {% endtab %} {% tab title="Docker / Bare-Metal" %} ```shell bin/alluxio job load --path --progress --verbose ``` {% endtab %} {% endtabs %} 常见原因：挂载表中找不到路径（通过 `alluxio mount list` 验证），或缓存配额不足。 **加载成功但读取仍走 UFS** 验证特定文件是否已缓存： {% tabs %} {% tab title="Kubernetes (Operator)" %} ```shell kubectl exec -n alluxio-cluster-coordinator-0 -- \ alluxio fs check-cached ``` {% endtab %} {% tab title="Docker / Bare-Metal" %} ```shell bin/alluxio fs check-cached ``` {% endtab %} {% endtabs %} 若文件在加载成功后显示为未缓存，数据可能已被驱逐。请检查缓存容量和驱逐配置——参阅[缓存驱逐](/ee-ai-cn/cache/removing-data-from-the-cache.md)。集群级缓存命中率可通过[监控](/ee-ai-cn/administration/monitoring-alluxio.md)查看。 ## 历史作业保留 已完成的作业记录会保留一段可配置的时间，默认为 7 天。如需调整： ```properties # 将已完成作业记录保留 3 天（默认：7d） alluxio.job.retention.time=3d ``` ## 相关文档 * [缓存驱逐](/ee-ai-cn/cache/removing-data-from-the-cache.md) — `job free` 手动释放、版本更新模式以及自动驱逐策略 * [Job Service](/ee-ai-cn/administration/managing-job-service.md) — `job list`、作业状态、Coordinator HA、故障恢复和配置调优 * [多副本](/ee-ai-cn/high-availability/multiple-replicas.md) — 为每个文件加载多个副本以提高容错性 * [`job load` CLI 参考](/ee-ai-cn/reference/user-cli.md#job-load) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://documentation.alluxio.io/ee-ai-cn/cache/loading-data-into-the-cache.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.