Hub documentation

使用 Xet 存储

Hub

API docs

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

使用 Xet 存储

Python

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

pip install -U huggingface_hub

从 huggingface_hub 0.32.0 版本开始，此操作还将安装 hf_xet。hf_xet 包将 huggingface_hub 与 xet-core（Xet 后端的 Rust 客户端）集成在一起。

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

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

pip install -U hf-xet

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

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

Git

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

先决条件

安装 Git 和 Git LFS。

在 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 安装：

brew install git-xet
git xet install

要验证安装，请运行：

git xet --version

Windows (amd64)

使用 winget：

winget install git-xet

使用安装程序：

下载 git-xet-windows-installer-x86_64.zip（可在此处获取）并解压。
运行 msi 安装程序文件并按照提示操作。

手动安装：

下载 git-xet-windows-x86_64.zip（可在此处获取）并解压。
将提取的 git-xet.exe 放置在 PATH 目录下。
在终端中运行 git xet install。

要验证安装，请运行：

git xet --version

使用 Git Xet

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

请确保所有先决条件均已安装并配置，按照在 Hub 上操作仓库的设置说明进行操作，然后提交你的更改，并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 协议被调用以将大文件直接上传至 Xet 存储，借助块级去重的能力提升上传速度。

在 macOS 或 Linux 上卸载

使用 Homebrew：

git xet uninstall
brew uninstall git-xet

如果你使用了安装脚本（适用于 MacOS 或 Linux），请在终端中运行以下命令：

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 可用的内存进行设置，包括容器内存限制。小型容器用于下载的内存较少，大型机器则使用更多，无需任何设置。请参阅下载缓冲区。
高级调优：如需进行细粒度控制，HF_XET_FIXED_DOWNLOAD_CONCURRENCY 和 HF_XET_FIXED_UPLOAD_CONCURRENCY 可将并发数固定为指定值，从而绕过自适应控制器。完整的选项列表请参阅 hf_xet 的环境变量。

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

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

环境变量

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

HF_XET_HIGH_PERFORMANCE=1 是一个便捷标志，用于一次性调整多项设置（并发上限、缓冲区大小以及并行文件限制）。它专为高带宽和快速磁盘的机器设计。从 hf_xet 1.7.0 开始，该标志设置的缓冲区大小基于 hf_xet 可用的内存（参见下载缓冲区），因此不再需要 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_ENABLE_ADAPTIVE_CONCURRENCY`	`true`	启用或禁用自适应并发控制。禁用后，并发数将保持初始值不变。
`HF_XET_CLIENT_AC_INITIAL_UPLOAD_CONCURRENCY`	`1`	并发上传流的初始数量。HP 模式:`16`。
`HF_XET_CLIENT_AC_INITIAL_DOWNLOAD_CONCURRENCY`	`1`	并发下载流的初始数量。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`	记录并发状态的间隔（以毫秒为单位）。

要将并发数固定为特定值（绕过自适应控制器），请使用便捷别名 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_CONNECT_TIMEOUT`	`60s`	TCP 连接超时。
`HF_XET_CLIENT_READ_TIMEOUT`	`120s`	HTTP 响应的读取超时时间。
`HF_XET_CLIENT_IDLE_CONNECTION_TIMEOUT`	`60s`	在关闭空闲连接之前的超时时间。
`HF_XET_CLIENT_MAX_IDLE_CONNECTIONS`	`16`	连接池中空闲连接的最大数量。

数据传输

环境变量	默认	描述
`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 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 日志文件（参见日志记录）。

环境变量	默认	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`	`64mb`	内存中块索引的最大大小。达到该值后，将不再加载更多块用于去重。
`HF_XET_SHARD_CACHE_SUBDIR`	`shard-cache`	Xet 缓存目录中用于分片缓存的子目录。

块缓存

分块缓存将已下载的字节范围（分块）存储在磁盘上，以避免从存储中重复获取重叠的数据。在反复下载相关模型或数据集，或生成其新版本时，该功能最为有用。

环境变量	默认	描述
`HF_XET_CHUNK_CACHE_SIZE_BYTES`	`0`（已禁用）	本地块缓存的大小。`hf_xet` Python 包默认禁用该缓存；设置一个字节数（例如 `10000000000` 表示 10 GB）以启用它，或设置为 `0` 以禁用它。此变量在 Git Xet v0 中无效。

日志记录

环境变量	默认	描述
`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 会在每次上传和下载后发送一份简短的报告。有关其内容，请参阅遥测。要将其关闭，请设置 HF_HUB_DISABLE_TELEMETRY=1。

当前限制

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

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

Update on GitHub

←Xet 历史与概述安全性→