存储

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

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

与 Git LFS 类似，由 Xet 支持的仓库使用 S3 作为远程存储，仓库根目录中的 .gitattributes 文件帮助识别哪些文件应远程存储。

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

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

Xet 指针在设计上包含所有这些信息。请参阅关于与 Git LFS 的向后兼容性的部分，其中添加了一个 Xet backed hash 字段，用于引用 Xet 存储中的文件。

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

使用 Xet 存储

要开始使用 Xet 存储，您需要一个启用 Xet 的仓库和一个 Xet 感知版本的 huggingface_hub Python 库。

要访问 Xet 感知客户端，请在安装 huggingface_hub 时添加 hf_xet Python 包（应 >= 0.30.0）

pip install -U huggingface_hub[hf_xet]

如果您使用 transformers 或 datasets 库，它已经在使用 huggingface_hub (huggingface_hub 应该 >= 0.30.0)，因此您只需在同一环境中安装 hf_xet

pip install hf-xet

如果您的 Python 环境具有 hf_xet 感知版本的 huggingface_hub，那么您的上传和下载将自动使用 Xet。

就是这样！您现在可以获得 Xet 去重对上传和下载的好处。使用旧版本 huggingface_hub 的团队成员仍然可以通过 LFS 桥提供的向后兼容性来上传和下载仓库。

要查看更详细的使用文档，请参阅 huggingface_hub 文档，了解

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

建议

Xet 与 Hub 当前基于 Python 的工作流程无缝集成。但是，您可以考虑以下几个步骤，以从 Xet 存储中获得最大收益

• 使用 hf_xet：虽然 Xet 仍然向后兼容为 Git LFS 优化的旧版客户端，但 hf_xet 与 huggingface_hub 的集成提供了最佳的基于块的性能，并加快了大型文件的迭代速度。
• 利用频繁的增量提交：Xet 的块级去重意味着您可以安全地对模型或数据集进行增量更新。仅上传更改的块，因此频繁提交既快速又节省存储空间。
• 在 .gitattributes 中具体说明：在定义 Xet 或 LFS 的模式时，请使用精确的文件扩展名（例如，*.safetensors、*.bin），以避免不必要地通过大型文件存储路由较小的文件。
• 优先考虑社区访问：Xet 大大提高了大型文件传输的效率和规模。与其构建仓库来减小其总大小（或单个文件的大小），不如为协作者和社区用户组织它，以便他们可以轻松地导航和检索他们需要的内容。

当前限制

虽然 Xet 为基于 Git 的存储带来了细粒度的去重和增强的性能，但某些功能和平台兼容性仍在开发中。因此，在使用启用 Xet 的仓库时，请记住以下约束

• 仅限 64 位系统：hf_xet 客户端目前需要 64 位架构；不支持 32 位系统。
• 部分 JavaScript 库支持：huggingface.js 库对 Xet 支持的仓库的功能有限；计划在未来版本中增加覆盖范围。
• 当前不可用完整的 Web 支持：通过 Hub Web 界面完全支持分块上传仍在开发中。
• Git 客户端集成 (git-xet)：已计划但仍在开发中。

去重

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

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

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

有关更多详细信息，请参阅从文件到块和从块到块博客文章，或 Low 等人的Git is for Data论文，该论文是 Hugging Face 收购 XetHub 之前的启动点。

与 LFS 的向后兼容性

Xet 存储为现有的 Hub 仓库提供了无缝过渡。完全没有必要知道是否涉及 Xet 后端。Xet 支持的仓库继续使用 Git LFS 指针文件格式，仅添加了 Xet backed hash 字段。这意味着，如果您对现有仓库和新创建的仓库进行 bare clone，它们看起来没有任何不同。每个大型文件（或二进制文件）将继续具有指针文件，并符合 Git LFS 指针文件规范。

这种对称性允许非 Xet 感知客户端（例如，旧版本的不感知 Xet 的 huggingface_hub）与 Xet 支持的仓库进行交互，而无需担心。实际上，在一个仓库中，支持 Git LFS 和 Xet 支持的文件混合使用。正如描述 CAS API 的部分所述，Xet 后端指示文件是在 Git LFS 还是 Xet 存储中，允许下游服务（Git LFS 或 Git LFS 桥）提供正确的 S3 URL，而不管哪个存储系统保存内容。

虽然 Xet 感知客户端将从 CAS 接收文件重建信息以在本地下载 Xet 支持的文件，但旧版客户端将从 Git LFS 桥获取 S3 URL。同时，当上传对 Xet 支持的文件的更新时，Xet 感知客户端将运行 CDC 去重并通过 CAS 上传，而非 Xet 感知客户端将通过 Git LFS 上传，并且后台进程会将文件修订版本转换为 Xet 支持的版本。

安全模型

Xet 存储在 Hugging Face 中存储的所有块上提供数据去重。这是通过加密哈希以隐私敏感的方式完成的。块的内容受到保护，并与仓库权限相关联。即，您只能读取重现您有权访问的文件所需的块，仅此而已。有关详细信息，请参阅xet-core。

传统存储：Git LFS

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

Git LFS 的主要限制在于其以文件为中心的去重方法。对文件的任何更改，无论更改大小，都意味着整个文件都需要进行版本控制 - 在文件传输中产生显著的开销，因为整个文件都会被上传（如果提交到仓库）或下载（如果将最新版本拉取到您的机器）。

这导致了更糟糕的开发者体验，以及额外的存储空间激增。