> 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](/ee-ai-cn/data-access/fuse-based-posix-api.md) | [S3 API](/ee-ai-cn/data-access/s3-api.md)     | [Python FSSpec](/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 指南](/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 指南](/ee-ai-cn/data-access/s3-api.md)

### 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 指南](/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 命名空间的顶层，不支持嵌套。挂载的添加与管理方式请参阅[底层存储](/ee-ai-cn/ufs.md)。

### 虚拟路径映射

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

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

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