> For the complete documentation index, see [llms.txt](https://documentation.alluxio.io/ee-ai-cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.alluxio.io/ee-ai-cn/cache/loading-data-into-the-cache.md).

# 缓存加载

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 <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
```

{% endtab %}

{% tab title="Docker / Bare-Metal" %}

```shell
# 提交（立即返回）
bin/alluxio job load --path <ufs-or-alluxio-path> --submit

# 查看进度
bin/alluxio job load --path <ufs-or-alluxio-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 <NAMESPACE> alluxio-cluster-coordinator-0 -- \
  alluxio job load --path <ufs-or-alluxio-path> --stop
```

{% endtab %}

{% tab title="Docker / Bare-Metal" %}

```shell
bin/alluxio job load --path <ufs-or-alluxio-path> --stop
```

{% endtab %}
{% endtabs %}

已停止的作业可通过再次使用 `--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 文档](/ee-ai-cn/reference/user-cli.md#job-load)。

### 从索引文件加载

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

{% tabs %}
{% tab title="Kubernetes (Operator)" %}

```shell
kubectl exec -n <NAMESPACE> 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 <NAMESPACE> alluxio-cluster-coordinator-0 -- \
  alluxio job load --path <ufs-or-alluxio-path> --submit --load-policy IF_CHANGED
```

{% endtab %}

{% tab title="Docker / Bare-Metal" %}

```shell
bin/alluxio job load --path <ufs-or-alluxio-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 <NAMESPACE> alluxio-cluster-coordinator-0 -- \
  alluxio job load --path s3://my-bucket/dataset/ --submit --verify

# 2. 轮询直到完成
kubectl exec -n <NAMESPACE> 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 <NAMESPACE> alluxio-cluster-coordinator-0 -- \
  alluxio job load --path <ufs-or-alluxio-path> --submit --skip-if-exists
```

{% endtab %}

{% tab title="Docker / Bare-Metal" %}

```shell
bin/alluxio job load --path <ufs-or-alluxio-path> --submit --skip-if-exists
```

{% endtab %}
{% endtabs %}
{% endhint %}

## 故障处理

**`Job State: FAILED`，`Files Failed > 0`**

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

{% tabs %}
{% tab title="Kubernetes (Operator)" %}

```shell
kubectl exec -n <NAMESPACE> alluxio-cluster-coordinator-0 -- \
  alluxio job load --path <path> --progress --file-status FAILURE
```

{% endtab %}

{% tab title="Docker / Bare-Metal" %}

```shell
bin/alluxio job load --path <path> --progress --file-status FAILURE
```

{% endtab %}
{% endtabs %}

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

**提交后立即出现 `Job State: FAILED`**

使用 `--verbose` 获取详情：

{% tabs %}
{% tab title="Kubernetes (Operator)" %}

```shell
kubectl exec -n <NAMESPACE> alluxio-cluster-coordinator-0 -- \
  alluxio job load --path <path> --progress --verbose
```

{% endtab %}

{% tab title="Docker / Bare-Metal" %}

```shell
bin/alluxio job load --path <path> --progress --verbose
```

{% endtab %}
{% endtabs %}

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

**加载成功但读取仍走 UFS**

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

{% tabs %}
{% tab title="Kubernetes (Operator)" %}

```shell
kubectl exec -n <NAMESPACE> alluxio-cluster-coordinator-0 -- \
  alluxio fs check-cached <path>
```

{% endtab %}

{% tab title="Docker / Bare-Metal" %}

```shell
bin/alluxio fs check-cached <path>
```

{% 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)