存储

Hugging Face Hub 上的存储库与软件开发平台上的存储库不同。它们包含的文件具有以下特点：

• 大——模型或数据集文件通常在 GB 甚至更大范围。我们有一些 TB 级的文件！
• 二进制——默认情况下不可读（例如，Safetensors 或 Parquet）

尽管 Hub 利用了 Git 支持的现代版本控制，但这些差异使得模型和数据集存储库与仅包含源代码的存储库大相径庭。

将这些文件直接存储在 Git 存储库中是不切实际的。Git 存储库背后的典型存储系统不适合此类文件，而且当你克隆一个存储库时，Git 会检索整个历史记录，包括所有文件修订。对于大型二进制文件来说，这可能非常庞大，迫使你下载可能永远不需要的千兆字节历史数据。

相反，在 Hub 上，这些大型文件通过“指针文件”进行跟踪，并通过 `.gitattributes` 文件进行标识（两者都将在下面详细讨论），它们保留在 Git 存储库中，而实际数据则存储在远程存储（如 Amazon S3）中。因此，存储库保持小巧，典型的 Git 工作流也保持高效。

从历史上看，Hub 存储库一直依赖 Git LFS 来实现这种机制。虽然 Git LFS 仍然受支持并广泛使用（请参阅下面的旧版部分），但 Hub 正在引入一个专门为 AI/ML 开发构建的现代化自定义存储系统，它支持块级重复数据删除、更小的上传和比 Git LFS 更快的下载。

Xet

Hugging Face 于 2024 年 8 月收购了 XetHub，这是一家位于西雅图的种子期初创公司，旨在取代 Hub 上的 Git LFS。

与 Git LFS 类似，基于 Xet 的存储库利用 S3 作为远程存储，并在存储库根目录中使用 `.gitattributes` 文件来帮助识别哪些文件应该远程存储。

同时，Git LFS 指针文件提供元数据以定位远程存储中的实际文件内容

• SHA256: 为实际的大文件提供唯一标识符。此标识符是通过计算文件内容的 SHA-256 哈希值生成的。
• 指针大小: 存储在 Git 仓库中的指针文件的大小。
• 远程文件大小: 指示实际大文件的大小（以字节为单位）。此元数据对于验证和管理存储及传输操作都很有用。

Xet 指针本身包含所有这些信息。有关详细信息，请参阅关于与 Git LFS 的向后兼容性的部分，其中增加了用于引用 Xet 存储中文件的 `Xet backed hash` 字段。

与 Git LFS 在文件级别进行重复数据删除不同，启用 Xet 的存储库在字节级别进行重复数据删除。当基于 Xet 存储的文件更新时，只有修改过的数据会上传到远程存储，从而显著节省网络传输。对于许多工作流，例如模型检查点的增量更新或向数据集中追加/插入新数据，这可以提高您和您的协作者的迭代速度。要了解有关 Xet 存储中重复数据删除的更多信息，请参阅下面的重复数据删除部分。

使用 Xet 存储

要开始使用 Xet 存储，您需要一个支持 Xet 的存储库和一个支持 Xet 的 huggingface_hub Python 库版本。截至 2025 年 5 月 23 日，支持 Xet 的存储库已成为 Hub 上所有新用户和组织的默认设置。

要获取 Xet 感知版本的 `huggingface_hub`，只需安装最新版本即可。

pip install -U huggingface_hub

自 `huggingface_hub` 0.32.0 版本起，这还将安装 `hf_xet`。`hf_xet` 包将 `huggingface_hub` 与 Xet 后端的 Rust 客户端 `xet-core` 集成。

如果您使用 `transformers` 或 `datasets` 库，它已经在使用 `huggingface_hub`。只要 `huggingface_hub` 的版本 >= 0.32.0，就不需要进一步的操作。

如果安装了版本 >= 0.30.0 且 < 0.32.0 的 `huggingface_hub`，则必须显式安装 `hf_xet`

pip install -U hf-xet

就这样！你现在可以享受 Xet 对上传和下载的重复数据删除带来的好处。使用 `huggingface_hub` 版本 < 0.30.0 的团队成员仍然可以通过 LFS 桥提供的向后兼容性上传和下载存储库。

要查看更详细的使用文档，请参考 `huggingface_hub` 的文档：

• 上传
• 下载
• 管理 `hf_xet` 缓存

建议

Xet 与 Hub 当前基于 Python 的工作流程无缝集成。但是，您可以考虑以下几个步骤，以充分利用 Xet 存储的优势：

• 使用 `hf_xet`：虽然 Xet 仍与针对 Git LFS 优化的旧版客户端向后兼容，但 `hf_xet` 与 `huggingface_hub` 的集成可提供最佳的基于分块的性能，并加快大型文件的迭代速度。
• 利用 `hf_xet` 环境变量：`hf_xet` 的默认安装旨在支持最广泛的硬件。要利用具有更多网络带宽或处理能力的设置，请查阅 `hf_xet` 的环境变量，以进一步加快下载和上传速度。
• 利用频繁的增量提交：Xet 的块级重复数据删除意味着您可以安全地对模型或数据集进行增量更新。只上传更改的块，因此频繁提交既快速又节省存储空间。
• 在 .gitattributes 中明确指定：在定义 Xet 或 LFS 模式时，使用精确的文件扩展名（例如，`*.safetensors`，`*.bin`）以避免不必要地将较小的文件通过大文件存储路由。
• 优先考虑社区访问：Xet 大幅提高了大文件传输的效率和规模。与其调整存储库结构以减小其总大小（或单个文件的大小），不如为协作者和社区用户组织存储库，以便他们可以轻松导航和检索所需内容。

当前限制

尽管 Xet 为基于 Git 的存储带来了细粒度的重复数据删除和增强的性能，但某些功能和平台兼容性仍在开发中。因此，在使用启用 Xet 的存储库时，请记住以下限制：

• 仅限 64 位系统：`hf_xet` 客户端目前需要 64 位架构；不支持 32 位系统。
• 部分 JavaScript 库支持：huggingface.js 库对 Xet 支持的存储库功能有限；计划在未来的版本中增加额外的覆盖范围。
• 暂无完整 Web 支持：通过 Hub Web 界面进行分块上传的完整支持仍在开发中。
• 不支持欧盟地区：计划支持 Xet 支持的存储库的欧盟存储区域，但仍在开发中。
• Git 客户端集成 (git-xet)：已计划但仍在开发中。

重复数据删除

支持 Xet 的存储库利用内容定义分块 (CDC) 来在字节级别（约 64KB 数据，也称为“块”）进行重复数据删除。每个块都通过一个滚动哈希来标识，该哈希根据实际文件内容确定块边界，使其能够抵御文件中任意位置的插入或删除。当使用支持 Xet 的客户端将文件上传到支持 Xet 的存储库时，其内容会被分解成这些可变大小的块。只有 Xet 存储中尚未存在的新块才会在分块后保留，其余所有内容都会被丢弃。

为了避免在块级别进行通信和管理的开销，新的块被分组到64MB 的块中并上传。每个块在内容寻址存储 (CAS) 中存储一次，并以其哈希值作为键。

Hub 目前的建议是将文件限制在 20GB。以 64KB 的分块大小计算，一个 20GB 的文件有 312,500 个分块，其中许多版本之间保持不变。Git LFS 旨在只注意到文件已更改并存储该修订的全部内容。通过在分块级别进行重复数据删除，Xet 后端可以只存储文件中修改过的内容（可能只有几 KB 或 MB），并安全地对跨存储库共享的块进行重复数据删除。对于模型和数据集存储库中的大型二进制文件，这显著提高了文件传输时间。

欲了解更多详情，请参阅从文件到块和从块到块的博客文章，或者 Low 等人撰写的Git 是数据论文，该论文在 Hugging Face 收购 XetHub 之前曾作为 XetHub 的启动点。

与 LFS 的向后兼容性

Xet 存储为现有 Hub 存储库提供了无缝过渡。完全不需要了解是否涉及 Xet 后端。Xet 支持的存储库继续使用 Git LFS 指针文件格式；`Xet backed hash` 的添加仅作为方便在 Web 界面中显示。实际上，这意味着如果你对现有存储库和新创建的存储库进行 `bare clone`，它们看起来不会有任何不同。每个大型文件（或二进制文件）将继续拥有一个与 Git LFS 指针文件规范相匹配的指针文件。

这种对称性允许不感知 Xet 的客户端（例如，旧版本的 `huggingface_hub`）与支持 Xet 的存储库进行交互而无需担忧。事实上，在一个存储库中，支持 Git LFS 和 Xet 支持的文件的混合。Xet 后端指示文件是位于 Git LFS 还是 Xet 存储中，允许下游服务从 S3 请求适当的 URL，无论哪个存储系统持有内容。

在 Xet 架构中，下载的向后兼容性由 Git LFS 网桥实现。Xet 感知客户端将从 CAS 接收文件重建信息以下载 Xet 支持的文件，而传统客户端将从网桥获取单个 URL，该网桥负责重建请求文件并返回资源 URL。这允许通过 URL 下载文件，以便您可以继续使用 Hub 的 Web 界面或 `curl`。

同时，来自非 Xet 感知客户端的上传仍遵循标准的 Git LFS 路径，即使文件已经由 Xet 支持。一旦文件上传到 LFS，后台进程会自动迁移内容，将其转换为 Xet 支持的版本。结合 Git LFS 网桥，这使得存储库维护者和 Hub 的其余部分可以按照自己的节奏无缝采用 Xet。

安全模型

Xet 存储通过加密哈希以隐私敏感的方式对 Hugging Face 中存储的所有分块进行数据去重。分块的内容受到保护，并与存储库权限关联。也就是说，您只能读取重现您有权访问的文件所需的块，不能多读。有关详细信息，请参阅 xet-core。

旧版存储：Git LFS

Hub 上的旧版存储系统 Git LFS 采用了许多与 Xet 支持的存储库相同的约定。Hub 的 Git LFS 后端是 Amazon Simple Storage Service (S3)。当调用 Git LFS 时，它使用 SHA 哈希将文件内容存储在 S3 中，以便将来访问。这种存储架构相对简单，并允许 Hub 存储数百万个模型、数据集和 Spaces 存储库的文件（截至本文撰写时共计 45PB）。

Git LFS 的主要限制在于其以文件为中心的重复数据删除方法。对文件的任何更改，无论大小如何，都意味着整个文件都被版本化——导致文件传输中产生显著的开销，因为整个文件会被上传（如果提交到存储库）或下载（如果拉取最新版本到您的机器）。

这导致开发人员体验变差，并导致额外存储的泛滥。