# FUSE 写入优化

{% hint style="warning" %}
此功能自 AI-3.8.15.1.6 起为实验性功能。
{% endhint %}

本指南介绍如何通过 FUSE POSIX 接口使用[写缓存](/ee-ai-cn/performance/s3-write-cache.md)后端，通过标准文件系统调用（`write()`、`open()`、`close()`）实现低延迟写入。在阅读本指南前，请确保写缓存已完成部署。

## 与 S3-API 写缓存的关系

写缓存后端（FoundationDB 元数据 + NVMe 数据 + 异步 UFS 持久化）由两种访问接口**共享**：

|                  | [S3-API 写入优化](/ee-ai-cn/performance/s3-write-cache.md) | FUSE 写入优化（本指南）                                                          |
| ---------------- | ------------------------------------------------------ | ----------------------------------------------------------------------- |
| **接口**           | S3 兼容 API（`PUT`、`GET`）                                 | POSIX 文件系统调用（`write`、`read`）                                            |
| **客户端**          | AWS CLI、boto3、s3fs、任意 S3 客户端                           | 任意 POSIX 应用、ML 框架、Shell 工具                                              |
| **写入策略**         | `WRITE_THROUGH`、`WRITE_BACK`、`TRANSIENT`               | 相同                                                                      |
| **FoundationDB** | 必需                                                     | 必需（同一 FDB 集群）                                                           |
| **额外限制**         | 无（仅 S3 语义限制）                                           | 参见[写缓存模式下的 POSIX 兼容性](#xie-huan-cun-mo-shi-xia-de-posix-jian-rong-xing) |

## 开始之前

* [ ] **写缓存已部署** — FDB 须处于运行状态，且 `alluxio.write.cache.enabled: "true"`。验证：

  ```shell
  kubectl exec -n <NAMESPACE> <CLUSTER_NAME>-coordinator-0 -- \
    alluxio conf get alluxio.write.cache.enabled
  ```

  预期输出：`true`。若非如此，请先完成 [S3-API 写入优化](/ee-ai-cn/performance/s3-write-cache.md)的部署。
* [ ] **FDB Pod 运行正常**：

  ```shell
  kubectl get pods -n <NAMESPACE> | grep fdb
  ```

  预期输出：FDB controller、log 和 storage Pod 均为 `Running`。
* [ ] **FUSE PVC 已存在**：

  ```shell
  kubectl get pvc -n <NAMESPACE> <CLUSTER_NAME>-fuse
  ```

  预期输出：PVC 存在（Pod 挂载前状态为 `Pending` 属正常现象）。

## 推荐集群配置

启用 FUSE 写缓存时，未持久化的写入数据会占用更大比例的 NVMe 容量。建议将 `alluxio-cluster.yaml` 中的 Pinned 空间比例从默认的 `0.3` 提高至 `0.5`：

```yaml
spec:
  properties:
    alluxio.write.cache.enabled: "true"
    # 从默认 0.3 提高至 0.5，以应对 FUSE 写入密集型工作负载
    alluxio.worker.page.store.pinned.file.capacity.limit.ratio: "0.5"
  fdb:
    enabled: true
```

应用配置：

```shell
# Idempotent
kubectl apply -f alluxio-cluster.yaml
```

> 请合理规划 Worker 的 NVMe 容量：在比例为 `0.5`、总缓存为 `1 TiB` 的情况下，最多 500 GiB 的空间可能被未持久化的写入数据占用。若写入吞吐持续超过持久化吞吐，空间将耗尽，Alluxio 会返回 `out-of-space` 错误。参见[缓存空间管理](/ee-ai-cn/performance/s3-write-cache.md#huan-cun-kong-jian-guan-li)。

## 部署 FUSE 客户端 Pod

Operator 在集群安装期间会创建名为 `<CLUSTER_NAME>-fuse` 的 PVC。使用 `mountPropagation: HostToContainer` 挂载，以便 FUSE 进程重启时自动恢复。

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: fuse-test-0
  namespace: <NAMESPACE>
spec:
  containers:
    - image: ubuntu:22.04
      name: fuse-test
      command: ["sleep", "infinity"]
      volumeMounts:
        - mountPath: /data
          name: alluxio-pvc
          mountPropagation: HostToContainer
  volumes:
    - name: alluxio-pvc
      persistentVolumeClaim:
        claimName: <CLUSTER_NAME>-fuse
```

```shell
# Idempotent
kubectl apply -f fuse-pod.yaml
kubectl -n <NAMESPACE> get pod fuse-test-0
```

预期输出：`STATUS = Running`，`READY = 1/1`。

更多 FUSE 部署选项（DaemonSet、Docker / 裸机），参见 [POSIX API](/ee-ai-cn/data-access/fuse-based-posix-api.md)。

## 配置写回路径

写入策略按路径配置，与 [S3-API 写入优化](/ee-ai-cn/performance/s3-write-cache.md#lu-jing-ji-pei-zhi) 中的路径级配置相同。路径指 Alluxio 命名空间（如 `/s3/checkpoints`），而非 FUSE 挂载路径（`/data/s3/checkpoints`）。

非交互式配置（适用于脚本）：

```shell
kubectl exec -i -n <NAMESPACE> <CLUSTER_NAME>-coordinator-0 -- \
  bash -c 'EDITOR="cp /dev/stdin" alluxio pathconfig edit' << 'EOF'
{
  "apiVersion": "v1.0",
  "defaultRule": {
    "description": "Global default",
    "policyMode": "WRITE_THROUGH"
  },
  "pathRules": [
    {
      "alluxioPath": "/s3/checkpoints/**",
      "description": "Low-latency checkpoint writes",
      "policyMode": "WRITE_BACK",
      "properties": { "writeReplicas": 1 }
    }
  ]
}
EOF
```

预期输出：`Update successful!`

验证指定路径是否解析为预期策略：

```shell
kubectl exec -n <NAMESPACE> <CLUSTER_NAME>-coordinator-0 -- \
  alluxio pathconfig test --path /s3/checkpoints/epoch-1/model.pt
```

预期输出：包含 `"policyMode": "WRITE_BACK"`。

## 验证 FUSE 写回

通过 FUSE 写入文件，并确认其最终持久化至 UFS：

```shell
# 通过 FUSE 写入
kubectl exec -i -n <NAMESPACE> fuse-test-0 -- \
  bash -c 'echo "hello from fuse write cache" > /data/s3/checkpoints/test.txt'

# 确认在 Alluxio 命名空间中可见
kubectl exec -i -n <NAMESPACE> <CLUSTER_NAME>-coordinator-0 -- \
  alluxio fs ls /s3/checkpoints/test.txt
```

等待异步持久化完成（最长 `alluxio.write.cache.async.file.check.period`，默认 `10min`）：

```shell
# 轮询至 PERSISTED（8 次 × 15s = 2 分钟）
for i in $(seq 1 8); do
  echo "--- Check $i/8 ---"
  NOT_PERSISTED=$(kubectl exec -i -n <NAMESPACE> <CLUSTER_NAME>-coordinator-0 -- \
    alluxio fs ls /s3/checkpoints/ 2>&1 | grep -c "NOT_PERSISTED" || true)
  if [ "${NOT_PERSISTED}" = "0" ]; then
    echo "All files PERSISTED."
    break
  fi
  echo "${NOT_PERSISTED} file(s) still pending. Waiting 15s..."
  sleep 15
done
```

预期输出：2 分钟内出现 `All files PERSISTED.`

***

## 写缓存模式下的 POSIX 兼容性

{% hint style="warning" %}
FUSE 写缓存与 S3-API 写缓存共用同一后端。因此，写缓存 FUSE 挂载在标准 FUSE 语义之上还有额外的 POSIX 限制，且对**所有写缓存策略**（`WRITE_THROUGH`、`WRITE_BACK`、`TRANSIENT`）均生效。在将工作负载迁移至写缓存 FUSE 挂载前，请务必了解以下限制。
{% endhint %}

下表汇总了任意写缓存策略（`WRITE_THROUGH`、`WRITE_BACK`、`TRANSIENT`）生效时各 POSIX 操作的支持情况。符号说明：✅ 支持 | ⚠️ 部分支持 | ❌ 不支持。

| 类别         | 操作                                    | 支持                  | 说明                             |
| ---------- | ------------------------------------- | ------------------- | ------------------------------ |
| **读取**     | `read` / `readv` / `pread` / `preadv` | ✅                   |                                |
| **写入**     | 顺序写入（新文件）                             | ✅                   | 核心使用场景                         |
|            | 覆盖写入现有文件                              | ✅                   | 通过 truncate + recreate         |
|            | 追加写入现有文件                              | ⚠️                  | 架构层面支持（MPU）                    |
|            | `fsync` / `fdatasync`                 | ✅                   | 触发异步持久化                        |
|            | `truncate`                            | ✅                   | delete + recreate              |
|            | 并发写入（同一文件）                            | ❌                   | S3 对象模型限制                      |
| **Rename** | 文件 rename                             | ✅ Atomic            | 适用于所有 S3 存储桶类型；零拷贝（仅元数据）       |
|            | 目录 rename                             | ✅ Atomic            | AI/ML checkpoint 模式的关键能力       |
| **删除**     | `unlink`                              | ✅ Default enabled   |                                |
|            | `rm -rf`                              | ✅                   | 页面在所有 Worker 上回收（15.1.3+）      |
| **目录**     | `readdir`                             | ✅ Dual-path merge   |                                |
|            | `mkdir`                               | ✅ Persisted         |                                |
|            | `rmdir`                               | ✅ Empty directories |                                |
| **元数据**    | `stat` / `getattr`                    | ✅                   |                                |
|            | 文件大小                                  | ✅                   |                                |
|            | `mtime`                               | ✅                   | 读写（`utimens`）                  |
|            | `atime` / `ctime`                     | = `mtime`           |                                |
|            | `chmod` / `chown`                     | ❌                   | S3 无 POSIX 权限模型                |
|            | `xattr`                               | ⚠️ Limited          |                                |
| **链接**     | 符号链接（`symlink` / `readlink`）          | ✅                   | Magic header 编码，目标路径最长 4096 字节 |
|            | 硬链接（`link()`）                         | ❌ `EOPNOTSUPP`      | S3 无 inode 概念                  |
| **锁**      | `flock`（建议锁）                          | ✅ 单节点               | 仅 libfuse；不支持跨节点锁定             |
|            | `fcntl` / `lockf`                     | ❌                   |                                |

### rename() 支持（15.1.6+）

自 AI-3.8.15.1.6 起，`rename()` 已完全支持——文件和目录均可重命名，操作原子，采用零拷贝纯元数据语义（无需 S3 `CopyObject + DeleteObject`）。适用于任意 S3 存储桶类型。

在 **AI-3.8.15.1.6 之前**的版本中，所有 `rename()` 操作均失败并返回 `EIO`，受影响的操作包括：

* Shell 的 `mv` 和 `rename`
* Python 的 `os.rename()`、`pathlib.Path.rename()`
* 写后重命名模式（先写入 `.tmp`，再重命名）

**Silly rename 拦截器（需手动开启）：** 当应用对已打开的文件执行 `rm` 时，Linux 内部会向 `.fuse_hidden*` 发起 `rename()`。启用拦截器可透明处理这一情况，无需触发 S3 的 `CopyObject + DeleteObject`：

```yaml
spec:
  properties:
    # CLIENT 级别：在 FUSE 客户端属性中设置
    alluxio.fuse.silly.rename.interceptor.enabled: "true"
```

默认值为 `false`。

### 覆盖写入（15.1.6+）

自 AI-3.8.15.1.6 起，支持通过 `truncate` + recreate 语义覆盖写入现有文件：Alluxio 删除现有文件并在同一路径创建新文件。不支持随机原地覆盖（`pwrite`）。

在 15.1.6 之前，文件关闭后不可再写——对现有文件重新打开以写入会返回 `EACCES`。若使用早期版本：

| 操作                                                    | errno    |
| ----------------------------------------------------- | -------- |
| `open(path, O_CREAT \| O_EXCL)` — 文件已存在               | `EEXIST` |
| `open(path, O_WRONLY)` 或 `open(path, O_RDWR)` — 文件已存在 | `EACCES` |

**影响：** 原地更新文件的应用（数据库、日志轮转、配置重写器）最适合使用 AI-3.8.15.1.6+。即使支持覆盖写入，写缓存 FUSE 挂载仍最适合一次性写入的工作负载——模型检查点、训练数据集、ETL 阶段输出。

### 不支持硬链接

`link()` 返回 `EOPNOTSUPP`。依赖硬链接的工具（`rsync --hard-links`、部分包管理器）无法通过该挂载正常工作。

### 删除时的缓存页回收（15.1.3+ 行为）

通过 FUSE `rm` 或 `rm -rf` 删除文件时，缓存页将在持有该文件副本的**所有** Worker 上回收，而不仅限于哈希环所有者 Worker。15.1.3 之前的版本中，仅所有者 Worker 回收缓存页；其他 Worker 上的孤儿页将保留至下一轮驱逐周期。

### 与 AWS Mountpoint for S3 的对比

Alluxio WriteCache（WRITE\_BACK 模式）在 POSIX 接口支持方面是 AWS Mountpoint for Amazon S3 的**严格超集**——Mountpoint 支持的每一个 POSIX 操作，Alluxio 都以相同或更高水平支持，无一例外。

Alluxio 额外提供以下 Mountpoint 不支持的 POSIX 能力：

* Atomic `rename`（文件和目录，适用于所有 S3 存储桶类型）
* `symlink` / `readlink`（符号链接）
* Persistent `mkdir`（目录在重启后保留）
* `xattr`（扩展属性）

符号说明：✅ 支持 | ⚠️ 有限 / 条件支持 | ❌ 不支持。

| 类别      | 操作                                     | Alluxio WriteCache（WRITE\_BACK 模式） | AWS Mountpoint for S3               | 说明                                         |
| ------- | -------------------------------------- | ---------------------------------- | ----------------------------------- | ------------------------------------------ |
| **读取**  | `read` / `readv` / `pread` / `preadv`  | ✅                                  | ✅                                   | 两者均完整支持所有读取变体                              |
| **写入**  | Sequential write (new file)            | ✅                                  | ✅                                   | 两者的核心使用场景                                  |
|         | Random write (`pwrite`)                | ❌                                  | ❌                                   | 两者均不支持主要写入模式下的随机写入                         |
|         | Overwrite existing file                | ✅ truncate + recreate              | ⚠️ `--allow-overwrite` + `O_TRUNC`  | —                                          |
|         | Append existing file                   | ⚠️ Architecture supports (MPU)     | ⚠️ S3 Express One Zone only         | 均有条件支持                                     |
|         | Concurrent writers (same file)         | ❌                                  | ❌                                   | S3 对象模型限制                                  |
|         | `fsync` / `fdatasync`                  | ✅ Triggers upload                  | ⚠️ Commits to S3; no further writes | —                                          |
|         | `truncate`                             | ✅ delete + recreate                | ⚠️ Requires `--allow-overwrite`     | —                                          |
| **重命名** | Single file rename                     | ✅ Atomic                           | ⚠️ S3 Express One Zone only         | **Alluxio 适用于任意 S3 存储桶**                   |
|         | File rename with overwrite             | ✅                                  | ⚠️ S3 XOZ + `--allow-overwrite`     | —                                          |
|         | Directory rename                       | ✅ Atomic                           | ❌                                   | **Alluxio 优势**——AI/ML checkpoint 模式的关键能力   |
|         | Zero-copy rename                       | ✅ Metadata-only, no data copy      | ❌ S3 rename = copy + delete         | 关键架构优势                                     |
| **删除**  | `unlink`                               | ✅ Default enabled                  | ⚠️ Requires `--allow-delete`        | —                                          |
|         | Recursive delete (`rm -rf`)            | ✅                                  | ✅ File-by-file                      | —                                          |
| **目录**  | `readdir`                              | ✅ Dual-path merge                  | ✅                                   | —                                          |
|         | `mkdir`                                | ✅ Persisted                        | ⚠️ Local only, not persisted to S3  | **Alluxio**：真实目录语义                         |
|         | `rmdir`                                | ✅ Empty directories                | ⚠️ Only `mkdir`-created dirs        | —                                          |
| **元数据** | `stat` / `getattr`                     | ✅                                  | ✅ Limited                           | —                                          |
|         | File size                              | ✅                                  | ✅                                   | —                                          |
|         | `mtime`                                | ✅ Read/write (`utimens`)           | ✅ Read-only                         | Alluxio 支持写入                               |
|         | `atime` / `ctime`                      | = `mtime`                          | = `mtime`                           | —                                          |
|         | `chmod` / `chown`                      | ❌                                  | ❌                                   | S3 无 POSIX 权限模型                            |
|         | `xattr`                                | ⚠️ Limited                         | ❌                                   | —                                          |
| **链接**  | Symbolic link (`symlink` / `readlink`) | ✅                                  | ❌                                   | **Alluxio**：magic header 编码，目标路径最长 4096 字节 |
|         | Hard link                              | ❌ `EOPNOTSUPP`                     | ❌                                   | S3 无 inode 概念                              |
| **锁**   | `flock` (advisory)                     | ✅ Single-node (libfuse)            | ✅ Single-node (libfuse)             | 两者均不支持跨节点锁定                                |
|         | `fcntl` locking                        | ❌                                  | ❌                                   | —                                          |
|         | `lockf`                                | ❌                                  | ❌                                   | —                                          |
| **其他**  | `mmap` shared write                    | ❌                                  | ❌                                   | 需要页缓存语义                                    |
|         | Sparse files (file holes)              | ❌                                  | ❌                                   | 与顺序写入模型冲突                                  |

**一致性模型**

| 场景         | Alluxio WriteCache（WRITE\_BACK 模式） | AWS Mountpoint for S3 |
| ---------- | ---------------------------------- | --------------------- |
| 写后读（本地）    | 关闭后**立即可从写缓冲区读取**                  | 关闭后可读（须等待 S3 上传完成）    |
| S3 可见性     | 异步持久化（关闭后数秒至数分钟）                   | 关闭后立即在 S3 可见          |
| 多实例一致性     | **分布式元数据**（强一致性）                   | 无跨实例协调                |
| `stat` 新鲜度 | **强一致性**                           | 并发修改时可能滞后约 1 秒        |
| 目录列表一致性    | **强一致性**                           | 强一致性（S3 ListObjects）  |
| 关闭时的持久性    | 数据在 Worker NVMe 缓存中（多副本）；异步写入 S3   | 数据在 S3（同步上传）          |
| 节点故障       | **多副本保护** — 触发提前 S3 持久化            | 未关闭的写入数据将丢失           |

Alluxio 提供更快的本地读后写（无需 S3 往返）以及通过其分布式元数据层实现的强跨实例元数据一致性。Mountpoint 提供更强的关闭时 S3 持久性（同步上传）。Alluxio 通过多副本写入弥补这一差距——若某个 Worker 故障，其他 Worker 上的副本将保留数据并触发提前 S3 持久化。

***

## 监控异步持久化

两条 CLI 命令（15.1.3+ 可用）可用于检查持久化操作的实时状态，无需等待 `alluxio fs ls`：

```shell
# 列出指定 Worker 上所有待处理或进行中的文件
kubectl exec -i -n <NAMESPACE> <CLUSTER_NAME>-worker-0 -- \
  alluxio async-persist list

# 按 Worker ID 过滤
kubectl exec -i -n <NAMESPACE> <CLUSTER_NAME>-worker-0 -- \
  alluxio async-persist list --worker <WORKER_ID>

# 查询指定路径的持久化状态和重试次数
kubectl exec -i -n <NAMESPACE> <CLUSTER_NAME>-coordinator-0 -- \
  alluxio async-persist stat --path /s3/checkpoints/epoch-1/model.pt
```

当 `alluxio fs ls` 显示文件长期处于 `NOT_PERSISTED` 状态时，可使用 `async-persist stat` 判断问题出在队列还是上传阶段。

## 关键配置

| 配置项                                                          | 默认值     | 描述                                                      |
| ------------------------------------------------------------ | ------- | ------------------------------------------------------- |
| `alluxio.write.cache.enabled`                                | `false` | 启用写缓存（与 S3 API 共享）。                                     |
| `alluxio.worker.page.store.pinned.file.capacity.limit.ratio` | `0.3`   | NVMe 容量中用于未持久化写入数据的最大比例。FUSE 写入密集型工作负载建议提高至 `0.5`。      |
| `alluxio.write.cache.async.file.check.period`                | `10min` | 孤儿检测扫描周期。设置过短会增加 FDB 负载。                                |
| `alluxio.write.cache.async.check.orphan.timeout`             | `1h`    | 超过此时间仍未提交的写入将被视为已放弃并清理。                                 |
| `alluxio.fuse.silly.rename.interceptor.enabled`              | `false` | CLIENT 级别。拦截 `.fuse_hidden*` 重命名/删除操作，透明处理已打开文件的 `rm`。  |
| `alluxio.worker.mark.writing.files.duration`                 | `10min` | 若文件处于写入状态但在该时长内未收到新数据，Worker 将其视为悬空写入并纳入清理。每次写入都会重置计时器。 |

## 故障排查

### 目录删除返回 DEADLINE\_EXCEEDED

对 `WRITE_BACK` 路径执行 `alluxio fs rm -R` 或 `rm -rf` 时可能出现：

```
io.grpc.StatusRuntimeException: DEADLINE_EXCEEDED: CallOptions deadline exceeded after ~5s
```

{% hint style="danger" %}
尽管出现该错误，底层文件**可能已在超时前从 UFS 删除**。请勿假设数据仍然存在。
{% endhint %}

**恢复步骤：**

1. 直接验证 UFS 状态：

   ```shell
   aws s3 ls s3://<BUCKET>/<path>/ --recursive | head -20
   ```
2. 若 S3 中文件已不存在，则数据层删除已成功。重新执行 `alluxio fs rm -R` 将确认并返回 `Path does not exist`。
3. Pagestore 磁盘空间不会立即收缩 — 孤儿页将在下一轮驱逐周期中被回收。

***

### 文件长期处于 NOT\_PERSISTED

```shell
kubectl exec -i -n <NAMESPACE> <CLUSTER_NAME>-coordinator-0 -- \
  alluxio fs ls /s3/checkpoints/
```

若文件在 `alluxio.write.cache.async.file.check.period` 后仍处于 `NOT_PERSISTED` 状态：

1. 检查异步持久化队列：

   ```shell
   kubectl exec -i -n <NAMESPACE> <CLUSTER_NAME>-worker-0 -- \
     alluxio async-persist list
   ```
2. 检查指定文件状态：

   ```shell
   kubectl exec -i -n <NAMESPACE> <CLUSTER_NAME>-coordinator-0 -- \
     alluxio async-persist stat --path /s3/checkpoints/<filename>
   ```
3. 检查 Worker 日志中的上传错误：

   ```shell
   kubectl logs -n <NAMESPACE> <CLUSTER_NAME>-worker-0 --tail=100 | \
     grep -i "persist\|upload\|flush"
   ```
4. 若 UFS 不可达，重试将进入指数退避（最长 `alluxio.worker.write.cache.async.persist.retry.max.interval`，默认 `1h`）。请从 Worker Pod 验证 UFS 连通性。

***

### rename() 意外返回 EIO

在任意写缓存策略生效时，此为预期行为（参见 [rename() 支持（15.1.6+）](#rename-zhi-chi-15-1-6)）。若应用依赖 rename：

* 将受影响路径切换为 `NO_CACHE` 策略，完全绕过该路径的写缓存。
* 若 rename 由已打开文件的 `rm` 触发，启用 `alluxio.fuse.silly.rename.interceptor.enabled: "true"`。

***

### FUSE Pod OOM 或挂载断开

这些问题与写缓存无关。参见 [FUSE 故障排除](/ee-ai-cn/data-access/fuse-based-posix-api.md#gu-zhang-pai-chu)。

## 参考资源

* [S3-API 写入优化](/ee-ai-cn/performance/s3-write-cache.md) — 通过 S3 API 使用写缓存；部署写缓存请先完成此步骤
* [POSIX API](/ee-ai-cn/data-access/fuse-based-posix-api.md) — FUSE 部署详情、挂载选项、读缓存模式
* [S3 API 基准测试](/ee-ai-cn/benchmark/s3-api.md) — S3 侧写入吞吐基线
* [POSIX 性能基准测试](/ee-ai-cn/benchmark/benchmarking-posix-performance.md) — FUSE 侧吞吐基线


---

# 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/performance/fuse-write-cache.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.