Hugging Face Hub 推出存储桶管理功能

Storage Bucket 让可变的、高吞吐量的 ML 工件有了归宿。它们正是为此而构建的：可变的、类似 S3 的对象存储，你可以在 Hub 上浏览、用 Python 脚本操作，或通过 hf CLI 管理。而且因为它们由 Xet 支撑，对于在文件之间共享内容的 ML 工件特别高效。

为什么 Bucket 而不是 Git

当处理以下情况时，Git 很快就会显得不像是正确的抽象：

• 训练集群在运行中持续写入检查点和优化器状态
• 数据管道迭代处理原始数据集
• Agent 存储跟踪、内存和共享知识图

在所有这些情况下，存储需求是相同的：快速写入、必要时覆盖、同步目录、移除过期文件，让流程保持进行。

Bucket：基础概念

Bucket 是 Hub 上的一个非版本化存储容器。它存在于用户或组织命名空间下，具有标准的 Hugging Face 权限，可以是私有或公开，有一个可以在浏览器中打开的页面，并且可以通过编程方式使用句柄（例如 hf://buckets/username/my-training-bucket）来访问。

Xet：高效的块存储

Bucket 基于 Xet 构建，这是 Hugging Face 的基于块的存储后端。这比看起来要重要得多。

Xet 并不将文件视为单块的对象，而是将内容分解成块并跨块进行去重。上传一个主要与原始数据集相似的处理后的数据集？许多块已经存在。存储连续的检查点，其中模型的大部分是冻结的？情况相同。Bucket 跳过已经存在的字节，这意味着更少的带宽、更快的传输和更高效的存储。

这对 ML 工作负载是自然契合的。训练管道不断产生相关工件族——原始和处理后的数据、连续的检查点、Agent 跟踪和衍生摘要——而 Xet 的设计就是利用这种重叠。

对于企业客户，计费基于去重后的存储，因此共享块直接减少了计费的占用空间。去重既有助于速度，也有助于成本。

预热：将数据靠近计算

Bucket 存储在 Hub 上，这意味着默认为全局存储。但并非每个工作负载都能承受从任何地方拉取数据的成本。对于分布式训练和大规模管道，存储位置直接影响吞吐量。

预热让你能够将热数据靠近运行计算的云提供商和区域。与其让数据在每次读取时跨区域传输，你可以声明需要它的地方，Bucket 会确保在你的作业开始时它已经在那里。这对需要快速访问大型数据集或检查点的训练集群，以及在不同云中运行管道不同部分的多区域设置特别有用。

我们首先与 AWS 和 GCP 合作，未来还会有更多云提供商。

快速开始：CLI

你可以在 2 分钟内用 hf CLI 启动并运行一个 bucket。首先是安装并登录：

curl -LsSf https://hf.co/cli/install.sh | bash
hf auth login

为你的项目创建一个 bucket：

hf buckets create my-training-bucket --private

假设你的训练作业在本地将检查点写入 ./checkpoints。将该目录同步到 Bucket：

hf buckets sync ./checkpoints hf://buckets/username/my-training-bucket/checkpoints

对于大型传输，你可能想在任何东西移动之前看看会发生什么。--dry-run 会打印计划而不执行任何操作：

hf buckets sync ./checkpoints hf://buckets/username/my-training-bucket/checkpoints --dry-run

你也可以将计划保存到文件中以供审查，之后再应用：

hf buckets sync ./checkpoints hf://buckets/username/my-training-bucket/checkpoints --plan sync-plan.jsonl
hf buckets sync --apply sync-plan.jsonl

完成后，从 CLI 检查 Bucket：

hf buckets list username/my-training-bucket -h

或直接在 Hub 上浏览它，网址为 https://huggingface.co/buckets/username/my-training-bucket。

这就是整个流程。创建一个 bucket，将你的工作数据同步到其中，在需要时检查，并在某些东西值得发布时保存版本化仓库。对于一次性操作，hf buckets cp 复制单个文件，hf buckets remove 清理过期的对象。

从 Python 使用 Bucket

上述所有操作也可以通过 huggingface_hub（自 v1.5.0 起可用）从 Python 执行。API 遵循相同的模式：创建、同步、检查。

from huggingface_hub import create_bucket, list_bucket_tree, sync_bucket

create_bucket("my-training-bucket", private=True, exist_ok=True)

sync_bucket(
    "./checkpoints",
    "hf://buckets/username/my-training-bucket/checkpoints",
)

for item in list_bucket_tree(
    "username/my-training-bucket",
    prefix="checkpoints",
    recursive=True,
):
    print(item.path, item.size)

这使得将 Bucket 集成到训练脚本、数据管道或任何以编程方式管理工件的服务变得简单明了。Python 客户端还支持批量上传、选择性下载、删除和 bucket 移动，以便在需要更细粒度控制时使用。

Bucket 支持也可通过 @huggingface/hub（自 v2.10.5 起）在 JavaScript 中获得，因此你也可以将 Bucket 集成到 Node.js 服务和 Web 应用中。

文件系统集成

Bucket 也可以通过 HfFileSystem（huggingface_hub 中兼容 fsspec 的文件系统）工作。这意味着你可以使用标准文件系统操作来列表、读取、写入和匹配 Bucket 内容——任何支持 fsspec 的库都可以直接访问 Bucket。

from huggingface_hub import hffs

# List files in a bucket directory
hffs.ls("buckets/username/my-training-bucket/checkpoints", detail=False)

# Glob for specific files
hffs.glob("buckets/username/my-training-bucket/**/*.parquet")

# Read a file directly
with hffs.open("buckets/username/my-training-bucket/config.yaml", "r") as f:
    print(f.read())

因为 fsspec 是远程文件系统的标准 Python 接口，pandas、Polars 和 Dask 等库可以使用 hf:// 路径读取和写入 Bucket，无需额外设置：

import pandas as pd

# Read a CSV directly from a Bucket
df = pd.read_csv("hf://buckets/username/my-training-bucket/results.csv")

# Write results back
df.to_csv("hf://buckets/username/my-training-bucket/summary.csv")

这使得可以轻松将 Bucket 集成到现有的数据工作流中，而无需改变代码读取或写入文件的方式。

从 Bucket 到版本化仓库

Bucket 是工件在运动过程中所在的快速、可变的地方。一旦某些东西变成稳定的交付物，它通常属于版本化的模型或数据集仓库。

在路线图上，我们计划支持 Bucket 和仓库之间双向的直接传输：将最终的检查点权重提升到模型仓库中，或在管道完成后将处理过的分片提交到数据集仓库中。工作层和发布层保持分离，但融入一个连续的 Hub 原生工作流中。

被启动合作伙伴信赖

在向所有人开放 Bucket 之前，我们与一小群启动合作伙伴进行了私密 beta 测试。

非常感谢 Jasper、Arcee、IBM 和 PixAI 测试早期版本、发现错误，以及分享直接影响此功能的反馈。

结论和资源

Storage Bucket 为 Hub 带来了一个缺失的存储层。它为你提供了一个 Hub 原生的地方，用于 ML 的可变、高吞吐量方面：检查点、处理后的数据、Agent 跟踪、日志以及在成为最终内容之前有用的所有其他东西。

因为它们基于 Xet 构建，Bucket 不仅比强制将所有东西都通过 Git 更容易使用。它们对于 AI 系统一直产生的相关工件类型也更高效。这意味着更快的传输、更好的去重，以及在企业计划中，计费从去重后的占用空间受益。

如果你已经使用 Hub，Bucket 让你可以在一个地方保持更多的工作流。如果你来自 S3 风格的存储，它们为你提供了一个熟悉的模型，更好地与 AI 工件对齐，并且有一条通向 Hub 上最终发布的清晰路径。

Bucket 包含在现有的 Hub 存储计划中。免费账户附带存储以供入门，PRO 和企业计划提供更高的限制。有关详细信息，请参阅存储页面。

阅读更多信息并自己尝试：

• CLI 安装指南
• CLI 指南和参考
• Hub 上的示例 Bucket
• 来自我们博客的更多文章

常见问题

有人考虑过冷存储层吗？

可能有很多用户（包括我自己）拥有以下数据：

• 不需要热或温存储
• 不需要跨区域可用性
• 可以容忍显著降低的访问速度

我理解 Xet 和较新的存储限制缩减非常专注于降低你的运营支出，因为有大量滥用行为，比如用户托管视频文件和上传虚假数据。然而，一些合法的工作负载涉及很少被访问但仍然有用的大型静态资源（出于自然灾害/火灾的原因 😅）。我很好奇一些更低成本（且更慢）的存档层对于这些情况是否最终可能有意义？

回应： 我们在内部讨论过这样的功能，我们可能在某个时候提供它，但它不在我们的短期路线图中。目前，主要目标是促进数据密集的 AI 工作流。

我如何将其附加到我的 Spaces 以实现持久存储？我需要快速访问我的数据检索和存储，通过 FastAPI。我托管在 Spaces 上。

回应： 我们很快会有一些东西。