> 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/data-access.md).

# 客户端 API

Alluxio 提供三种客户端 API，均可访问相同的缓存数据——选择哪种取决于您应用程序的语言、框架和运维约束。

## 选择 API

|          | [POSIX API](https://documentation.alluxio.io/ee-ai-cn/data-access/fuse-based-posix-api.md) | [S3 API](https://documentation.alluxio.io/ee-ai-cn/data-access/s3-api.md) | [Python FSSpec](https://documentation.alluxio.io/ee-ai-cn/data-access/fsspec.md) |
| -------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| **适用场景** | 应用使用标准文件系统调用；无需修改任何代码                                                                      | 应用已使用 boto3 / AWS SDK / 任意 S3 兼容客户端                                       | 纯 Python：Pandas、PyArrow、Ray、Hugging Face Datasets                                |
| **语言**   | 任意                                                                                         | 任意（HTTP）                                                                  | 仅 Python                                                                         |
| **部署方式** | 每个客户端节点运行 FUSE 守护进程（K8s 用 CSI 或 DaemonSet）                                                 | 在 Worker 上启用 S3 端点；将 SDK 指向 `worker-ip:29998`                             | `pip install alluxiofs`                                                          |
| **状态**   | GA                                                                                         | GA                                                                        | 实验性                                                                              |

### 快速决策指南

* **K8s 上的 ML 训练**（PyTorch、TensorFlow）→ POSIX API（CSI 方式），或 S3 API（PyTorch S3 Connector）
* **现有 S3 工作负载**（boto3、Spark 等）→ S3 API——替换 endpoint URL，无需其他改动
* **Pandas / PyArrow / Ray** → FSSpec（`alluxiofs`）——无需挂载或守护进程
* **性能敏感、高吞吐场景** → S3 API（启用 HTTP 307 redirect）

## API 简介

### POSIX API

将 Alluxio 挂载为本地目录。任何使用标准文件系统调用（`open`、`read`、`write`、`ls`、`cp`）的工具均无需修改即可使用——无需改代码，无需引入 SDK。

每个客户端节点上运行一个 FUSE 守护进程，将文件系统调用转换为 Alluxio RPC——对应用完全透明。代价是每次操作都需要经过 FUSE 进程（相比直接使用 SDK 多一跳），且守护进程需要在每个客户端节点上单独部署。

```shell
# FUSE 挂载后，无需任何代码改动
ls /mnt/alluxio/fuse/s3/
cat /mnt/alluxio/fuse/s3/dataset/train.csv
```

→ [POSIX API 指南](https://documentation.alluxio.io/ee-ai-cn/data-access/fuse-based-posix-api.md)

### S3 API

在每个 Alluxio Worker 进程内直接暴露 S3 兼容的 HTTP 端点（端口 29998）。使用任意 AWS S3 SDK 的应用只需修改 endpoint URL，无需其他代码改动。

S3 端点直接运行在每个 Worker 进程内，无需额外守护进程。部署模式和吞吐调优请参阅详细指南。

```python
import boto3
client = boto3.client(
    "s3",
    endpoint_url="http://<WORKER_IP>:29998",
    aws_access_key_id="alluxio",
    aws_secret_access_key="alluxio",
)
client.list_objects_v2(Bucket="s3")
```

→ [S3 API 指南](https://documentation.alluxio.io/ee-ai-cn/data-access/s3-api.md)

对于需要接近线性吞吐、又要避免跨 worker 跳转的 AWS SDK 客户端,该指南还介绍了节点本地的 [S3 代理](https://documentation.alluxio.io/ee-ai-cn/data-access/s3-proxy.md)——一个 OpenResty sidecar,通过一致性哈希环把每个请求路由到数据所属 worker。

### Python FSSpec API

`alluxiofs` 实现了 [fsspec](https://filesystem-spec.readthedocs.io/) 接口，使 Alluxio 可作为 Pandas、PyArrow、Ray Dataset 和 Hugging Face Datasets 中 `s3fs` 的直接替代。

> **实验性**：`alluxiofs` 尚未 GA。请使用 UFS 原生路径（如 `s3://bucket/path`），而非 Alluxio 虚拟挂载路径。

```python
import fsspec
from alluxiofs import AlluxioFileSystem
fsspec.register_implementation("alluxiofs", AlluxioFileSystem, clobber=True)

fs = fsspec.filesystem("alluxiofs", worker_hosts="<WORKER_IP>", target_protocol="s3")

import pandas as pd
df = pd.read_parquet("s3://my-bucket/dataset/train.parquet", filesystem=fs)
```

→ [FSSpec API 指南](https://documentation.alluxio.io/ee-ai-cn/data-access/fsspec.md)

## 路径映射

三种 API 共用同一个路径命名空间。Alluxio 根据**挂载表**解析路径：每个挂载点将一个 Alluxio 虚拟路径绑定到一个 UFS URI。例如，将 `s3://my-bucket/data/` 挂载到 `/data` 后：

* POSIX：`cat /mnt/alluxio/fuse/data/file.csv`
* S3 API：`client.get_object(Bucket="data", Key="file.csv")`
* FSSpec：`fs.open("s3://my-bucket/data/file.csv")`

三种方式访问的是相同的缓存数据。挂载点必须位于 Alluxio 命名空间的顶层，不支持嵌套。挂载的添加与管理方式请参阅[底层存储](https://documentation.alluxio.io/ee-ai-cn/ufs.md)。

### 虚拟路径映射

当挂载表本身无法满足需求时——例如命名空间隔离、UFS 零停机迁移或多版本路径别名——Alluxio 提供虚拟路径映射功能。它是服务端的路径重写层，在路径解析前对 POSIX、S3 API 和 CLI 透明生效，应用代码无需任何改动。

示例：将 `/model/latest/` 重定向到 `/model/v3/`，无需修改任何客户端配置。

→ [虚拟路径映射指南](https://documentation.alluxio.io/ee-ai-cn/data-access/client-virtual-path-mapping.md)

## 容器镜像

前面提到的三种 API，均通过挂载表来提供文件数据。但对于另一类常见场景——在大规模 AI/ML 训练扩容时，容器镜像拉取容易成为性能瓶颈——Alluxio 同样提供了有效的加速方案。它可作为节点本地的 OCI 镜像仓库缓存，直接透传镜像数据，支持 Azure Container Registry 及任意兼容 OCI Distribution v2 规范的仓库。containerd 通过 Alluxio 拉取镜像时，Alluxio 会将镜像的 blob 数据缓存在 Worker 节点的 NVMe 存储上。值得注意的是，这种缓存方式不需要额外挂载UFS, 实际拉取镜像数据时,按 digest 内容直接读取缓存。

→ [OCI Registry API 指南](https://documentation.alluxio.io/ee-ai-cn/data-access/oci-registry-api.md)
