Hugging Face Hub 推出 Storage Buckets

来源：https://huggingface.co/blog/storage-buckets 返回文章列表 (https://huggingface.co/blog)

• 我们为何构建 Buckets (https://huggingface.co/blog/storage-buckets#why-we-built-buckets)
• Xet 为何重要 (https://huggingface.co/blog/storage-buckets#why-xet-matters)
• 预热：让数据贴近计算 (https://huggingface.co/blog/storage-buckets#pre-warming-bringing-data-close-to-compute)
• 快速开始 (https://huggingface.co/blog/storage-buckets#getting-started)
• 通过 Python 使用 Buckets (https://huggingface.co/blog/storage-buckets#using-buckets-from-python)
• 文件系统集成 (https://huggingface.co/blog/storage-buckets#filesystem-integration)
• 从 Buckets 到版本化仓库 (https://huggingface.co/blog/storage-buckets#from-buckets-to-versioned-repos)
• 受启动合作伙伴信赖 (https://huggingface.co/blog/storage-buckets#trusted-by-launch-partners)
• 总结与资源 (https://huggingface.co/blog/storage-buckets#conclusion-and-resources)

Hugging Face 的 Models 和 Datasets 仓库非常适合发布最终产物。但生产环境中的 ML 会持续产生大量中间文件（检查点、优化器状态、处理后的分片、日志、追踪记录等），这些文件频繁变更、来自多个并行任务、且很少需要版本控制。

Storage Buckets 正是为此而生：一种可在 Hub 上浏览、通过 Python 脚本操作、或使用 hf CLI 管理的可变性 S3 风格对象存储。而且由于它们由 Xet 提供底层支持，对于跨文件共享内容的 ML 产物尤为高效。

我们为何构建 Buckets (https://huggingface.co/blog/storage-buckets#why-we-built-buckets)

当你遇到以下场景时，Git 很快就不再是合适的抽象：

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

这些场景的存储需求是一致的：快速写入、按需覆盖、同步目录、清理过期文件、保持流转。

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

Xet 为何重要 (https://huggingface.co/blog/storage-buckets#why-xet-matters)

Buckets 构建于 Xet 之上——Hugging Face 的基于分块的存储后端，这一点的重要性可能超乎你的想象。

Xet 不是将文件视为整体 blob，而是将内容拆分为分块并跨文件去重。上传一个与原始数据集大部分相似的处理后数据集？许多分块已经存在。存储连续检查点中模型大部分冻结的部分？同理。Buckets 会跳过已存在的字节，这意味着更少的带宽、更快的传输和更高效的存储。

这与 ML 工作负载天然契合。训练管道持续产生相关产物家族——原始与处理后的数据、连续检查点、Agent 追踪记录及其派生摘要——而 Xet 正是为了利用这种重叠而设计的。

对于企业客户，计费基于去重后的存储量，因此共享分块直接减少计费占用。去重在速度和成本方面都有帮助。

预热：让数据贴近计算 (https://huggingface.co/blog/storage-buckets#pre-warming-bringing-data-close-to-compute)

Buckets 位于 Hub 上，默认提供全球存储。但并非每个工作负载都能承受从数据实际存储位置拉取数据的代价，对于分布式训练和大规模管道，存储位置直接影响吞吐量。

预热功能让你将热数据带到计算所在的云提供商和区域附近。数据不再在每次读取时跨区域传输，你只需声明需求位置，Buckets 就能确保在任务开始前数据已就绪。这对于需要快速访问大型数据集或检查点的训练集群，以及管道不同部分运行在不同云上的多区域设置尤为实用。

我们首批与 AWS 和 GCP 合作，未来将有更多云提供商加入。

快速开始 (https://huggingface.co/blog/storage-buckets#getting-started)

使用 hf CLI 可在 2 分钟内创建并运行 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 使用 Buckets (https://huggingface.co/blog/storage-buckets#using-buckets-from-python)

上述所有功能也可通过 Python 的 huggingface_hub 实现（自 v1.5.0 起可用）。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)

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

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

文件系统集成 (https://huggingface.co/blog/storage-buckets#filesystem-integration)

Buckets 还可通过 HfFileSystem 使用，这是 huggingface_hub 中兼容 fsspec 的文件系统。这意味着你可以使用标准文件系统操作来列出、读取、写入和 glob Bucket 内容——任何支持 fsspec 的库都可以直接访问 Buckets。

from huggingface_hub import hffs

# 列出 bucket 目录中的文件
hffs.ls("buckets/username/my-training-bucket/checkpoints", detail=False)

# Glob 特定文件
hffs.glob("buckets/username/my-training-bucket/**/*.parquet")

# 直接读取文件
with hffs.open("buckets/username/my-training-bucket/config.yaml", "r") as f:
    print(f.read())

由于 fsspec 是 Python 远程文件系统的标准接口，pandas、Polars 和 Dask 等库可以直接使用 hf:// 路径从 Buckets 读写，无需额外配置：

import pandas as pd

# 直接从 Bucket 读取 CSV
df = pd.read_csv("hf://buckets/username/my-training-bucket/results.csv")

# 将结果写回
df.to_csv("hf://buckets/username/my-training-bucket/summary.csv")

这使得将 Buckets 接入现有数据工作流变得简单，无需更改代码的读写方式。

从 Buckets 到版本化仓库 (https://huggingface.co/blog/storage-buckets#from-buckets-to-versioned-repos)

Buckets 是产物仍在流转时的快速、可变存储场所。一旦某物成为稳定的可交付成果，它通常应归入版本化的模型或数据集仓库。

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

受启动合作伙伴信赖 (https://huggingface.co/blog/storage-buckets#trusted-by-launch-partners)

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

衷心感谢 Jasper、Arcee、IBM 和 PixAI 测试早期版本、发现 bug 并分享直接塑造了这一功能的反馈。

总结与资源 (https://huggingface.co/blog/storage-buckets#conclusion-and-resources)

Storage Buckets 为 Hub 带来了缺失的存储层。它们为 ML 中可变、高吞吐量的部分提供了 Hub 原生的存储场所：检查点、处理后的数据、Agent 追踪记录、日志，以及所有在成为最终产物之前有用的东西。

由于构建于 Xet 之上，Buckets 不仅比强制所有内容通过 Git 更易用，对于 AI 系统持续产生的相关产物类型也更加高效。这意味着更快的传输、更好的去重，以及在企业方案中受益于去重后占用的计费方式。

如果你已经在使用 Hub，Buckets 让你能将更多工作流保留在一处。如果你来自 S3 风格的存储，它们提供了熟悉的模式，同时对 AI 产物有更好的适配性，并有清晰的通往 Hub 最终发布的路径。

Buckets 已包含在现有的 Hub 存储方案 中。免费账户提供入门存储，PRO 和 Enterprise 方案提供更高限额。详见存储页面。

阅读更多并亲自尝试：

• Buckets 指南 (https://huggingface.co/docs/huggingface_hub/en/guides/buckets)
• Hub 文档 (https://huggingface.co/docs/hub/storage-buckets)
• CLI 安装指南 (https://huggingface.co/docs/huggingface_hub/en/installation)
• CLI 指南 (https://huggingface.co/docs/huggingface_hub/en/guides/cli) 和参考 (https://huggingface.co/docs/huggingface_hub/en/package_reference/cli)
• Hub 上的示例 Bucket (https://huggingface.co/buckets/julien-c/my-training-bucket)
• 存储定价 (https://huggingface.co/pricing#storage)