Skip to main content

使用 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。只要版本 ≥ 0.32.0，无需额外操作。

若安装的 huggingface_hub 版本在 0.30.0 至 0.32.0 之间，则需要单独安装 hf_xet：

pip install -U hf-xet

就这么简单！现在你即可在上传与下载过程中享受 Xet 去重带来的好处。团队成员即便使用 < 0.30.0 的 huggingface_hub，仍可通过LFS 桥的向后兼容机制上传与下载仓库。

更多使用细节，请查看 huggingface_hub 文档：

Git​

Git 用户可通过下载并安装 Git Xet 扩展来使用 Xet 的优势。安装完成后，直接使用管理 Hub 仓库的标准 Git 工作流即可，无需额外改动。

前置条件​

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

brew tap huggingface/tap
brew install git-xet
git-xet install

验证安装：

git-xet --version

Windows（amd64）​

使用安装程序：

  • 下载 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 工作流一样简单。

确保所有前置条件已安装并配置好，按照操作仓库的设置指南完成初始化，然后提交更改并 push 到 Hub：

# 创建任意文件！然后……
git add .
git commit -m "Uploading new models"  # 说明信息可自定义
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 上卸载​

如果使用安装程序：

  • 前往 设置 -> 应用 -> 已安装的应用
  • 找到 “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 的默认安装面向最广泛的硬件环境。若你拥有更高的网络带宽或算力，可查阅 hf_xet 的环境变量，以优化上下行效率。

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

  • 善用频繁的增量提交：Xet 的块级去重意味着你可以放心地对模型或数据集进行增量更新。只会上载变更的块，因此频繁提交也能快速且高效。
  • 在 .gitattributes 中精确匹配：定义 Xet 或 LFS 模式时，使用精确的文件扩展名（如 *.safetensors、*.bin），避免小文件不必要地走大文件存储。
  • 优先考虑社区访问体验：Xet 大幅提升大文件传输的效率与规模。与其为了减小仓库或单个文件大小而牺牲结构，不如让仓库结构更利于协作者与社区用户导航与获取所需内容。

当前限制​

虽然 Xet 将细粒度去重与更高性能带入基于 Git 的存储方案，但部分功能与平台兼容性仍在完善中。使用启用 Xet 的仓库时，请注意：

  • 仅支持 64 位系统：hf_xet 与 Git Xet 目前都需要 64 位架构，不支持 32 位系统。
Last updated on