# 客户端 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)


---

# 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/data-access.md?ask=<question>
```

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.