# 使用 Xet 存储

## Python

要访问支持 Xet 的 `huggingface_hub` 版本，只需安装最新版本即可：

```bash
pip install -U huggingface_hub
```

从 `huggingface_hub` 0.32.0 版本开始，此操作还将安装 `hf_xet`。`hf_xet` 包将 `huggingface_hub` 与 [`xet-core`](https://github.com/huggingface/xet-core)（Xet 后端的 Rust 客户端）集成在一起。

如果你使用的是 `transformers` 或 `datasets` 库，它们已经在使用 `huggingface_hub`。只要 `huggingface_hub` 的版本 >= 0.32.0，就无需采取任何额外操作。

当安装的 `huggingface_hub` 版本 >= 0.30.0 且 < 0.32.0 时，必须显式安装 `hf_xet`：

```bash
pip install -U hf-xet
```

就是这样！现在上传和下载都能享受 Xet 去重带来的好处。使用 `huggingface_hub` < 0.30.0 版本的团队成员仍然可以通过 [LFS 桥接提供的向后兼容性](legacy-git-lfs#backward-compatibility-with-lfs) 来上传和下载仓库。

如需查看更详细的使用文档，请参阅 `huggingface_hub` 的文档：

- [上传](https://huggingface.co/docs/huggingface_hub/guides/upload#faster-uploads)
- [下载](https://huggingface.co/docs/huggingface_hub/guides/download#faster-downloads)
- [管理 `hf_xet` 缓存](https://huggingface.co/docs/huggingface_hub/guides/manage-cache#chunk-based-caching-xet)

## Git

Git 用户可以通过下载并安装 Git Xet 扩展来享受 Xet 带来的优势。安装完成后，只需使用[通过 Git 管理 Hub 仓库的标准工作流](../repositories-getting-started)即可，无需进行任何额外更改。

### 先决条件

安装 [Git](https://git-scm.com/) 和 [Git LFS](https://git-lfs.com/)。

### 在 macOS 或 Linux（amd64 或 aarch64）上安装

在终端中使用以下命令通过安装脚本进行安装（需要 `curl` 和 `unzip`）：
```
curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/huggingface/xet-core/refs/heads/main/git_xet/install.sh | sh
```

或者，使用 [Homebrew](https://brew.sh/) 安装：
```
brew install git-xet
git xet install
```

要验证安装，请运行：
```
git xet --version
```

### Windows (amd64)

使用 `winget`：
```
winget install git-xet
```

使用安装程序：
 - 下载 `git-xet-windows-installer-x86_64.zip`（[可在此处获取](https://github.com/huggingface/xet-core/releases/download/git-xet-v0.2.0/git-xet-windows-installer-x86_64.zip)）并解压。
 - 运行 `msi` 安装程序文件并按照提示操作。

手动安装：
 - 下载 `git-xet-windows-x86_64.zip`（[可在此处获取](https://github.com/huggingface/xet-core/releases/download/git-xet-v0.2.0/git-xet-windows-x86_64.zip)）并解压。
 - 将提取的 `git-xet.exe` 放置在 `PATH` 目录下。
 - 在终端中运行 `git xet install`。

要验证安装，请运行：
  ```
  git xet --version
  ```

### 使用 Git Xet

在您的平台上安装完成后，使用 Git Xet 只需遵循 Hub 的标准 Git 工作流即可。

请确保所有[先决条件均已安装并配置](https://huggingface.co/docs/hub/repositories-getting-started#requirements)，按照[在 Hub 上操作仓库的设置说明](https://huggingface.co/docs/hub/repositories-getting-started#set-up)进行操作，然后提交你的更改，并`push`到 Hub：

  ```
  # Create any files you like! Then...
  git add .
  git commit -m "Uploading new models"  # You can choose any descriptive message
  git push
  ```
在底层，[Xet 协议](https://huggingface.co/docs/xet/index)被调用以将大文件直接上传至 Xet 存储，借助[块级去重](./deduplication)的能力提升上传速度。

### 在 macOS 或 Linux 上卸载

使用 Homebrew：
```bash
git xet uninstall
brew uninstall git-xet
```
如果你使用了安装脚本（适用于 MacOS 或 Linux），请在终端中运行以下命令：
```bash
git xet uninstall
sudo rm $(which git-xet)
```
### 在 Windows 上卸载

如果您使用的是 `winget`：
```
winget uninstall git-xet
```

如果您使用了安装程序：
-  转到 设置 -> 应用 -> 已安装的应用
- 查找“Git-Xet”。
- 选择上下文菜单中可用的“卸载”选项。

如果您手动安装了：
- 在终端中运行 `git xet uninstall`。
- 从原始放置位置删除 `git-xet.exe` 文件。

## 建议

Xet 与 Hub 的所有工作流无缝集成。不过，为了从 Xet 存储中获益最多，您可以考虑执行以下几个步骤。

使用 Python 上传或下载时：

- **确保已安装 `hf_xet`**：尽管 Xet 仍与针对 Git LFS 优化的传统客户端保持向后兼容，但 `hf_xet` 与 `huggingface_hub` 的集成可提供最佳的基于分块的性能，并加快大文件的迭代速度。
- **自适应并发默认开启**：`hf_xet` 会根据实时网络状况自动调整并行传输流的数量——无需任何配置。默认设置即可让大多数网络路径达到饱和，无需调优。
- **下载缓冲区随系统内存扩展**：从 `hf_xet` 1.7.0 开始，下载缓冲区的大小基于 `hf_xet` 可用的内存进行设置，包括容器内存限制。小型容器用于下载的内存较少，大型机器则使用更多，无需任何设置。请参阅 [下载缓冲区](#download-buffers)。
- **高级调优**：如需进行细粒度控制，`HF_XET_FIXED_DOWNLOAD_CONCURRENCY` 和 `HF_XET_FIXED_UPLOAD_CONCURRENCY` 可将并发数固定为指定值，从而绕过自适应控制器。完整的选项列表请参阅 `hf_xet` 的 [环境变量](https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables#xet)。

在 Git 或 Python 中上传或下载时：

- **利用频繁且增量的提交**：Xet 的块级去重机制意味着你可以安全地对模型或数据集进行增量更新。只有发生变化的块会被上传，因此频繁提交既快速又节省存储空间。
- **在 .gitattributes 中明确指定**：在定义 Xet 或 LFS 的模式时，请使用精确的文件扩展名（例如 `*.safetensors`、`*.bin`），以避免将较小的文件不必要地路由到大文件存储中。
- **优先考虑社区访问**：Xet 大幅提升了大文件传输的效率和规模。在组织仓库时，不要以减小仓库总大小（或单个文件大小）为目标，而应面向协作者和社区用户进行组织，以便他们轻松浏览并获取所需内容。

## 通过代理或防火墙上传

从 `hf_xet` 1.8.0 开始，上传操作可以直接将数据发送到 Amazon S3，而不再仅通过 Xet 存储服务。Hub 会为每次上传决定是否使用直接上传，并正在逐步启用该功能。下载操作保持不变。

如果您的网络限制了出站流量，除了[在代理或防火墙后下载](../models-downloading#downloading-behind-a-proxy-or-firewall)中列出的主机名外，请允许以下主机名（HTTPS，端口 443）：

| 主机名                     | 目的                                          |
|------------------------------|--------------------------------------------------|
| `s3.us-east-1.amazonaws.com` | 直接上传（美国）                              |
| `s3.eu-west-3.amazonaws.com` | 存储于欧盟的仓库的直接上传 |

这些主机名不属于 `hf.co` 或 `huggingface.co`，因此将这些后缀加入白名单无法覆盖它们。

如果 `hf_xet` 无法连接到 S3，它会重试直接上传，然后改为通过 Xet 存储服务发送该数据。上传最终仍会完成，但由于每个数据块都需要先等待重试过程，速度可能会慢得多。发生这种情况时，`hf_xet` 的 [日志](#logging) 会显示 `Upload grant URL unreachable, falling back to legacy xorb upload path (may be slower)`。如果无法允许 S3 主机名，请设置 `HF_XET_CLIENT_LEGACY_DIRECT_XORB_UPLOAD=1` 以关闭直接上传。

## 环境变量

`hf_xet` 和 Git Xet 均由 `xet-core` 提供支持，可通过环境变量进行配置。下表列出了用于精细控制的各个变量。大多数用户无需更改这些设置——默认值已针对自动充分利用大多数网络路径进行了调优。

> [!NOTE]
> `HF_XET_HIGH_PERFORMANCE=1` 是一个便捷标志，用于一次性调整多项设置（并发上限、缓冲区大小以及并行文件限制）。它专为高带宽和快速磁盘的机器设计。从 `hf_xet` 1.7.0 开始，该标志设置的缓冲区大小基于 `hf_xet` 可用的内存（参见 [下载缓冲区](#download-buffers)），因此不再需要 64 GB 的 RAM，且您自行设置的任何变量都将优先于该标志。在更早的版本中，请仅在拥有至少 64 GB RAM 的机器上使用它。

### 通用

大多数用户首先会用到的高级标志。

| 环境变量 | 默认 | 描述 |
|---|---|---|
| `HF_XET_HIGH_PERFORMANCE`（别名 `HF_XET_HP`） | off | 一个便捷标志，通过同时提高并发数、缓冲区大小和并行文件限制来最大化网络和 CPU 的使用率。请参阅上方的说明。 |
| `HF_XET_CACHE` | `$HF_HOME/xet` | Xet 在本地缓存数据（下载的块和去重分片）的目录。其优先级高于 `HF_HOME`。 |

### 自适应并发

默认情况下，`xet-core` 使用自适应并发——根据实时网络状况动态调整并行度。这些是高级设置，在大多数情况下不太可能需要使用。以下变量用于控制自适应控制器的行为：

| 环境变量 | 默认 | 描述 |
|---|---|---|
| `HF_XET_CLIENT_AC_INITIAL_UPLOAD_CONCURRENCY` | `2` | 并发上传流的初始数量。HP 模式:`16`。 |
| `HF_XET_CLIENT_AC_INITIAL_DOWNLOAD_CONCURRENCY` | `4` | 并发下载流的初始数量。HP 模式:`16`。 |
| `HF_XET_CLIENT_AC_MIN_UPLOAD_CONCURRENCY` | `1` | 上传并发数的下限。HP 模式:`4`。 |
| `HF_XET_CLIENT_AC_MIN_DOWNLOAD_CONCURRENCY` | `1` | 下载并发数的下限。HP 模式:`4`。 |
| `HF_XET_CLIENT_AC_MAX_UPLOAD_CONCURRENCY` | `64` | 上传并发数的上限。HP 模式：`124`。 |
| `HF_XET_CLIENT_AC_MAX_DOWNLOAD_CONCURRENCY` | `64` | 下载并发数的上限。HP 模式：`124`。 |
| `HF_XET_CLIENT_AC_TARGET_RTT` | `60s` | 目标往返时间。只要预测的完整传输往返时间低于此值，并发度就会增加。 |
| `HF_XET_CLIENT_AC_MAX_HEALTHY_RTT` | `90s` | 可接受的最大往返时间。超过此时间的传输会被自适应控制器计为失败。 |
| `HF_XET_CLIENT_AC_HEALTHY_SUCCESS_RATIO_THRESHOLD` | `0.8` | 控制器提高并发度所需达到的成功率阈值。 |
| `HF_XET_CLIENT_AC_UNHEALTHY_SUCCESS_RATIO_THRESHOLD` | `0.5` | 低于此成功率时，控制器会降低并发度。 |
| `HF_XET_CLIENT_AC_LOGGING_INTERVAL_MS` | `10000` | 记录并发状态的间隔（以毫秒为单位）。 |

> [!TIP]
> 要将并发数固定为特定值（绕过自适应控制器），请使用便捷别名 `HF_XET_FIXED_UPLOAD_CONCURRENCY` 和 `HF_XET_FIXED_DOWNLOAD_CONCURRENCY`。这些别名会将初始、最小和最大并发数设置为相同的值。

### 网络和重试

| 环境变量 | 默认 | 描述 |
|---|---|---|
| `HF_XET_CLIENT_RETRY_MAX_ATTEMPTS` | `5` | 失败请求的最大重试次数。 |
| `HF_XET_CLIENT_RETRY_BASE_DELAY` | `3000ms` | 重试之间的基础延迟（采用指数退避策略）。 |
| `HF_XET_CLIENT_RETRY_MAX_DURATION` | `360s` | 任何单次重试前的最大等待时间。在达到`HF_XET_CLIENT_RETRY_MAX_ATTEMPTS`后重试将停止，因此总重试时间可能超过此值。 |
| `HF_XET_CLIENT_CONNECT_TIMEOUT` | `60s` | TCP 连接超时。 |
| `HF_XET_CLIENT_READ_TIMEOUT` | `300s` | HTTP 响应的读取超时时间。 |
| `HF_XET_CLIENT_IDLE_CONNECTION_TIMEOUT` | `60s` | 在关闭空闲连接之前的超时时间。 |
| `HF_XET_CLIENT_MAX_IDLE_CONNECTIONS` | `16` | 连接池中空闲连接的最大数量。 |
| `HF_XET_CLIENT_RECONSTRUCTION_API_VERSION` | （未设置） | 强制将下载（重建）API 版本设置为 `1` 或 `2`，不进行回退。如果未设置，`hf_xet` 会尝试使用版本 2，并在服务器不支持时回退到版本 1。 |
| `HF_XET_CLIENT_SHARD_API_VERSION` | （未设置） | 强制将上传（分片）API 版本设置为 `1` 或 `2`，不进行回退。如果未设置，`hf_xet` 会尝试使用版本 2，并在服务器不支持时回退到版本 1。 |

### 数据传输

| 环境变量 | 默认 | 描述 |
|---|---|---|
| `HF_XET_DATA_MAX_CONCURRENT_FILE_INGESTION` | `8` | 上传期间并发处理的最大文件数。HP 模式:`100`。 |
| `HF_XET_DATA_MAX_CONCURRENT_FILE_DOWNLOADS` | `8` | 并发下载的最大文件数。 |
| `HF_XET_DATA_INGESTION_BLOCK_SIZE` | `8mb` | 文件摄取期间读取的块大小。 |
| `HF_XET_DATA_PROGRESS_UPDATE_INTERVAL` | `200ms` | 进度条的更新频率。 |
| `HF_XET_DATA_PROGRESS_UPDATE_SPEED_SAMPLING_WINDOW` | `10s` | 用于在进度报告中聚合传输速度测量的时间窗口。 |
| `HF_XET_CLIENT_LEGACY_DIRECT_XORB_UPLOAD` | `false` | 设置为 `1` 可让所有上传数据通过 Xet 存储服务传输，而不是直接发送到 S3（`hf_xet` 1.8.0+）。请参阅 [在代理或防火墙后上传](#uploading-behind-a-proxy-or-firewall)。 |

### 下载缓冲区

这些参数用于控制下载过程中的内存使用。

从 `hf_xet` 1.7.0 开始，三个 `DOWNLOAD_BUFFER` 变量的默认值基于 `hf_xet` 可使用的内存量。该内存量为机器的 RAM，或者如果容器的内存限制更低，则为该限制。每个默认值都是该内存的一定比例，并保持在表格中所示的最小值和最大值之间。HP 模式使用两倍的比例，最小值和最大值保持不变。例如，限制为 4 GB 的容器将获得约 256 MB 的缓冲区，上限为 1 GB；而拥有 32 GB 内存的机器将获得与早期版本相同的约 2 GB 缓冲区和 8 GB 上限。

早期版本，或任何无法确定可用内存量的版本，会使用固定的默认值 `2gb`、`512mb` 和 `8gb`（在 HP 模式下为 `16gb`、`2gb` 和 `64gb`）。启动时，正在使用的值会写入 `hf_xet` 日志文件（参见 [日志记录](#logging)）。

| 环境变量 | 默认 | HP 模式 | 描述 |
|---|---|---|---|
| `HF_XET_RECONSTRUCTION_MIN_RECONSTRUCTION_FETCH_SIZE` | `256mb` | `1gb` | 用于重建请求的最小获取大小。 |
| `HF_XET_RECONSTRUCTION_MAX_RECONSTRUCTION_FETCH_SIZE` | `8gb` | `16gb` | 用于重建请求的最大获取大小。 |
| `HF_XET_RECONSTRUCTION_DOWNLOAD_BUFFER_SIZE` | 1/16 的内存，从 `64mb` 到 `16gb` | 1/8 的内存 | 基础共享缓冲区预算。 |
| `HF_XET_RECONSTRUCTION_DOWNLOAD_BUFFER_PERFILE_SIZE` | 1/64 的内存，从 `16mb` 到 `2gb` | 1/32 的内存 | 每个活动文件的额外缓冲区预算。 |
| `HF_XET_RECONSTRUCTION_DOWNLOAD_BUFFER_LIMIT` | 1/4 的内存，从 `264mb` 到 `64gb` | 1/2 的内存 | 总下载缓冲内存的硬性上限。如果 `HF_XET_RECONSTRUCTION_DOWNLOAD_BUFFER_SIZE` 的值高于此上限，则上限会相应提高以保持一致。 |
| `HF_XET_DISABLE_MEMORY_DERIVED_DOWNLOAD_BUFFERS` | unset | — | 设置为 `1` 以使用固定的默认值，而不是根据可用内存来调整缓冲区大小。 |
| `HF_XET_RECONSTRUCTION_TARGET_BLOCK_COMPLETION_TIME` | `15m` | — | 用于预取块完成的目标时间。用于确定在下载过程中应提前预取多少数据。 |
| `HF_XET_RECONSTRUCTION_MIN_PREFETCH_BUFFER` | `1gb` | — | 在下载过程中，无论预计完成时间如何，需要保持预取的最小数据量。 |

### 分片缓存

**shard cache** 在 Xet 缓存目录下的磁盘上存储去重索引（即描述已上传数据块的“shards”）。更大的缓存可以让客户端针对更多已见过的数据进行去重，从而减少重新上传的字节数。

| 环境变量 | 默认 | 描述 |
|---|---|---|
| `HF_XET_SHARD_CACHE_SIZE_LIMIT` | `16gb` | 磁盘分片缓存的软上限。在运行**开始**时，缓存会被修剪至该大小，但在单个长时间运行的会话中可能会超过该大小。作为粗略参考，大小为 *X* 的缓存大约可以对 1000 × *X* 的数据进行去重（16 GB → 约 16 TB）。对于非常大的仓库，请调高此值以获得更好的去重效果；如果不断增长的缓存有占满磁盘的风险，请调低此值。接受人类可读的大小（例如 `32gb`）或原始字节数。 |
| `HF_XET_SHARD_CHUNK_INDEX_TABLE_MAX_SIZE` | `67108864` | 内存去重索引中分块条目的最大数量。请设置一个整数，而非诸如 `128mb` 这样的大小值。从 `hf_xet` 1.7.1 版本开始，当索引已满时，最旧的分片会被移除以为新分片腾出空间；早期版本在索引满后则停止添加分块。 |
| `HF_XET_SHARD_CACHE_SUBDIR` | `shard-cache` | Xet 缓存目录中用于分片缓存的子目录。 |

### 块缓存

`hf_xet` 不再使用本地分块缓存进行下载。下载的文件仍会存储在 `huggingface_hub` 的文件缓存中。

| 环境变量 | 默认 | 描述 |
|---|---|---|
| `HF_XET_CHUNK_CACHE_SIZE_BYTES` | — | 不再被 `hf_xet` 使用。设置它不会启用下载分块缓存。 |

### 日志记录

| 环境变量 | 默认 | 描述 |
|---|---|---|
| `HF_XET_LOG_DEST` | (none) | 日志目标位置。接受文件路径或目录路径（以 `/` 结尾）。当设置为目录时，日志文件将以带时间戳的名称创建。当设置为空字符串时，日志输出到控制台。当未设置时，日志输出到 Hugging Face Xet 缓存目录中的 `logs/` 子目录。 |
| `HF_XET_LOG_FORMAT` | (none) | 日志格式。设置为 `json` 以使用 JSON 格式的日志；否则为纯文本。默认情况下，文件日志使用 JSON 格式，控制台日志使用文本格式。 |
| `HF_XET_LOG_PREFIX` | `xet` | 向日志目录记录日志时，日志文件名的前缀。 |
| `HF_XET_LOG_DIR_DISABLE_CLEANUP` | `false` | 禁用日志目录中旧日志文件的自动清理。 |
| `HF_XET_LOG_DIR_MAX_SIZE` | `250mb` | 日志目录中日志文件的最大总大小。旧文件会被删除，以确保不超过此限制。 |
| `HF_XET_LOG_DIR_MIN_DELETION_AGE` | `1d` | 在清理过程中，日志文件可被删除前所需的最小存在时长。 |
| `HF_XET_LOG_DIR_MAX_RETENTION_AGE` | `14d` | 日志文件的最大保留时长。清理过程中，超过此时长的文件将被始终删除。 |

### 遥测

`hf_xet` 会在每次上传和下载后发送一份简短的报告。有关其内容，请参阅 [遥测](./telemetry)。要将其关闭，请设置 `HF_HUB_DISABLE_TELEMETRY=1`。

## 当前限制

虽然 Xet 为基于 Git 的存储带来了细粒度去重和性能提升，但部分功能和平台兼容性仍在开发中。因此，在使用启用 Xet 的仓库时，请注意以下限制：

- **仅限 64 位系统**：`hf_xet` 和 Git Xet 目前均要求 64 位架构；不支持 32 位系统。