Hub documentation

存储桶

Hub

API docs

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

存储桶

Storage Buckets 是 Hugging Face Hub 上的一种仓库类型，提供类似 S3 的对象存储，由 Xet 存储后端提供支持。与基于 Git 的 repositories（模型、数据集、Spaces）不同，buckets 是 非版本化 且 可变的，专为需要简单、快速存储的场景而设计，例如训练检查点、日志、中间产物，或任何无需版本控制的大型文件集合。

您可以通过 Hub 网页界面、hf CLI 或 Python API 与存储桶进行交互。

Buckets 对所有用户和组织均可用。有关定价详情，请参阅 hf.co/storage。

请参阅访问模式了解如何从您的工具访问桶数据（挂载为文件系统、hf:// 路径、Jobs/Spaces 中的卷挂载），S3 兼容 API 用于使用现有的 S3 工具（AWS CLI、boto3、s5cmd），以及桶集成用于在 pandas、Dask 和 Spark 等流行数据库中提供即用型代码片段。

Buckets 与 Repositories

Hub 提供两种类型的存储：基于 Git 的仓库，用于版本控制和协作工作；以及存储桶，用于快速、可变的对象存储。

功能	仓库（基于 Git）	存储桶
版本控制	完整的 Git 历史记录	None（可变的，就地覆盖）
类型	模型、数据集、Spaces	独立存储桶
主要用例	发布最终生成的工件	工作存储 / 中间数据
操作	Hub API，Git push/pull	类似 S3 的 `sync`、`cp`、`rm`
去重	Xet 块级	Xet 块级
拉取请求	是的	No
模型/数据集卡片	是的	否（但会渲染纯文本 README）

当你需要版本历史记录、协作功能（PR、讨论）以及库集成时，请使用 repositories。当你需要用于频繁变更数据的快速、可变存储时，请使用 buckets——文件可以就地覆盖或删除。

创建存储桶

从 Hub 界面

前往 huggingface.co/new-bucket：

指定存储桶的所有者：可以是您本人，也可以是您所属的任何组织。
输入一个存储桶名称。
选择存储桶应为公开还是私有。
可选地，预选择CDN 预热区域，以便从一开始就将您的数据缓存到更接近计算资源的位置。

创建存储桶后，您应该能看到存储桶页面：

从 CLI

# Create a bucket under your namespace
hf buckets create my-bucket

# Create a private bucket
hf buckets create my-bucket --private

# Create a bucket under an organization
hf buckets create my-org/shared-bucket

来自 Python

from huggingface_hub import create_bucket

# Create a bucket under your namespace
create_bucket("my-bucket")

# Create a private bucket
create_bucket("my-bucket", private=True)

# Create a bucket under an organization
create_bucket("my-org/shared-bucket")

更改可见性

您可以在创建后更改存储桶的可见性：

# Make a bucket private
hf buckets settings username/my-bucket --private

# Make it public again
hf buckets settings username/my-bucket --public

from huggingface_hub import update_bucket_settings

update_bucket_settings("username/my-bucket", private=True)
update_bucket_settings("username/my-bucket", private=False)

如需了解完整的 Python API 参考，包括删除、移动和列出存储桶，请参阅 huggingface_hub Buckets 指南。

在 Hub 上浏览 Buckets

每个存储桶在 Hub 上都有一个页面，您可以在其中浏览其内容、导航目录并查看文件详情。存储桶页面位于 https://huggingface.co/buckets/<owner>/<bucket-name>。

README 渲染

如果存储桶中的某个目录包含 README.md 文件，Hub 会在该目录页面的文件列表下方渲染它。这在存储桶根目录和任何子目录中均有效——可用于记录存储桶的内容、数据的组织方式，或下游工具应如何消费这些数据。

从 CLI 列出

您也可以通过 CLI 列出存储桶的内容：

# List files in a bucket (with human-readable sizes)
hf buckets list julien-c/my-training-bucket -h
                     Feb 17 14:46  art/
                     Feb 17 14:58  arxivqa/
                     Feb 17 15:02  arxivqa2/
                     Feb 17 15:04  arxivqa3/
                     Feb 17 14:47  captcha/
                     Feb 17 14:53  captcha2/
                     Feb 24 17:22  julien/

# Recursive listing
hf buckets list julien-c/my-training-bucket/art -h -R
    423.6 MB         Feb 17 14:29  art/train-00000-of-00011.parquet
    441.0 MB         Feb 17 14:29  art/train-00001-of-00011.parquet
    521.7 MB         Feb 17 14:29  art/train-00002-of-00011.parquet
    481.4 MB         Feb 17 14:29  art/train-00003-of-00011.parquet
    444.6 MB         Feb 17 14:29  art/train-00004-of-00011.parquet
    461.6 MB         Feb 17 14:29  art/train-00005-of-00011.parquet
    466.4 MB         Feb 17 14:29  art/train-00006-of-00011.parquet
    486.3 MB         Feb 17 14:29  art/train-00007-of-00011.parquet
    477.0 MB         Feb 17 14:29  art/train-00008-of-00011.parquet
    454.0 MB         Feb 17 14:29  art/train-00009-of-00011.parquet
    483.1 MB         Feb 17 14:29  art/train-00010-of-00011.parquet

# Tree view
hf buckets list julien-c/my-training-bucket --tree -h -R
                        ├── art/
423.6 MB  Feb 17 14:29  │   ├── train-00000-of-00011.parquet
441.0 MB  Feb 17 14:29  │   ├── train-00001-of-00011.parquet
521.7 MB  Feb 17 14:29  │   ├── train-00002-of-00011.parquet
481.4 MB  Feb 17 14:29  │   ├── train-00003-of-00011.parquet
444.6 MB  Feb 17 14:29  │   ├── train-00004-of-00011.parquet
461.6 MB  Feb 17 14:29  │   ├── train-00005-of-00011.parquet
466.4 MB  Feb 17 14:29  │   ├── train-00006-of-00011.parquet
486.3 MB  Feb 17 14:29  │   ├── train-00007-of-00011.parquet
477.0 MB  Feb 17 14:29  │   ├── train-00008-of-00011.parquet
454.0 MB  Feb 17 14:29  │   ├── train-00009-of-00011.parquet
483.1 MB  Feb 17 14:29  │   └── train-00010-of-00011.parquet
                        ├── arxivqa/
495.9 MB  Feb 17 14:32  │   ├── train-00000-of-00164.parquet
518.3 MB  Feb 17 14:32  │   ├── train-00001-of-00164.parquet
495.5 MB  Feb 17 14:32  │   ├── train-00002-of-00164.parquet
486.6 MB  Feb 17 14:32  │   ├── train-00003-of-00164.parquet
490.4 MB  Feb 17 14:32  │   ├── train-00004-of-00164.parquet
...

管理文件

您可以直接在 Hub 的存储桶页面上上传和下载文件，也可以使用 CLI 和 Python API 进行编程访问。存储桶文件使用 hf://buckets/ 路径进行引用（例如 hf://buckets/username/my-bucket/path/to/file）。hf buckets cp 命令用于处理单个文件的传输，而 hf buckets sync 则更适合用于目录。所有命令均支持双向操作——从本地到远程以及从远程到本地。

如果您的数据已经存储在模型、数据集或 Space 仓库（或其他存储桶）中，您可以使用 hf buckets cp 进行 服务端 复制——无需下载或重新上传。请参阅在仓库和存储桶之间复制文件。

上传文件

如需快速上传，您可以直接在浏览器中的存储桶页面拖放文件。若需以编程方式使用，hf buckets cp 可将单个文件复制到存储桶中。源为本地路径，目标为 hf://buckets/ 路径。您还可以从标准输入（stdin）通过管道传入数据，这对于以编程方式生成的内容非常实用。

命令行界面：

# Upload a single file
hf buckets cp ./model.safetensors hf://buckets/username/my-bucket/models/model.safetensors

# Upload from stdin
cat config.json | hf buckets cp - hf://buckets/username/my-bucket/config.json

在 Python 中，使用 batch_bucket_files 可以在单次调用中上传一个或多个文件。每个条目都是一个 (local_path, remote_path) 元组。

Python：

from huggingface_hub import batch_bucket_files

batch_bucket_files(
    "username/my-bucket",
    add=[
        ("./model.safetensors", "models/model.safetensors"),
        ("./config.json", "models/config.json"),
    ],
)

有关更多上传选项（原始字节、上传+删除组合等），请参阅 huggingface_hub 上传指南。

下载文件

您可以直接在 Hub 的存储桶页面上单击文件来下载单个文件。对于编程访问，下载操作与上传语法类似——只需在 hf buckets cp 中交换源和目的地即可。您还可以使用 - 作为目的地，将文件流式传输到标准输出，从而将存储桶内容直接通过管道传递给其他工具。

命令行界面：

# Download a single file
hf buckets cp hf://buckets/username/my-bucket/models/model.safetensors ./model.safetensors

# Download to stdout and pipe
hf buckets cp hf://buckets/username/my-bucket/config.json - | jq .

在 Python 中，使用 download_bucket_files 并传入一个由 (remote_path, local_path) 元组组成的列表。

Python：

from huggingface_hub import download_bucket_files

download_bucket_files(
    "username/my-bucket",
    files=[
        ("models/model.safetensors", "./local/model.safetensors"),
        ("config.json", "./local/config.json"),
    ],
)

如需使用预获取的元数据实现更快的下载，请参阅 huggingface_hub 下载指南。

同步目录

sync 命令的工作方式类似于 rsync 或 aws s3 sync——它会比较源和目的地，仅传输已更改的文件。这是保持本地目录与存储桶同步的最高效方式。默认情况下，sync 仅添加和更新文件。传入 --delete 以同时删除目的地中在源端已不存在的文件。使用 --dry-run 可在不实际传输任何内容的情况下预览将发生的变化。

命令行界面：

# Upload a local directory to a bucket
hf buckets sync ./data hf://buckets/username/my-bucket/data

# Download from a bucket to a local directory
hf buckets sync hf://buckets/username/my-bucket/data ./data

# Sync with deletion of extraneous files
hf buckets sync ./data hf://buckets/username/my-bucket/data --delete

# Preview what would be synced without executing
hf buckets sync ./data hf://buckets/username/my-bucket/data --dry-run

# Plan and apply: review the sync plan before executing
hf buckets sync ./data hf://buckets/username/my-bucket/data --plan sync-plan.jsonl
# ... review the plan file, then apply it
hf buckets sync --apply sync-plan.jsonl

hf sync 是 hf buckets sync 的便捷别名。

Python：

from huggingface_hub import sync_bucket

# Upload a local directory to a bucket
sync_bucket("./data", "hf://buckets/username/my-bucket/data")

# Download from a bucket to a local directory
sync_bucket("hf://buckets/username/my-bucket/data", "./data")

sync 命令支持过滤（--include、--exclude）、比较模式（--ignore-times、--existing）以及先规划后执行的工作流，以便在执行操作前进行审查。有关完整的选项列表，请参阅huggingface_hub 同步指南。

删除文件

由于存储桶不启用版本控制，删除操作会立即生效且不可逆——无法恢复已删除的文件。在删除文件前，尤其是使用 --recursive 时，请使用 --dry-run 进行二次确认。

命令行界面：

# Remove a single file
hf buckets rm username/my-bucket/old-model.bin

# Remove all files under a prefix
hf buckets rm username/my-bucket/logs/ --recursive

# Preview what would be deleted
hf buckets rm username/my-bucket/checkpoints/ --recursive --dry-run

Python：

from huggingface_hub import batch_bucket_files

batch_bucket_files("username/my-bucket", delete=["old-model.bin", "logs/debug.log"])

有关更多删除选项（基于模式的过滤、递归删除等），请参阅 huggingface_hub 删除指南。

在仓库和存储桶之间复制文件

您可以将任何仓库（模型、数据集、Space）或存储桶中由 Xet 跟踪的文件复制到目标存储桶，而无需重新上传数据。该复制操作在服务器端执行：仅迁移 Xet 内容哈希，因此借助块级去重，即使是非常大的文件也能瞬间完成复制。

仅 Xet 跟踪的文件会在服务器之间复制。小型非 Xet 文件（例如配置文件和 README）会自动下载并重新上传。服务器端复制还要求源和目的地位于同一存储区域。

命令行界面：

hf buckets cp \
  hf://datasets/HuggingFaceFW/fineweb/data \
  hf://buckets/username/fineweb-data

Python：

from huggingface_hub import HfApi

api = HfApi()

api.copy_files(
    "hf://datasets/HuggingFaceFW/fineweb/data",
    "hf://buckets/username/fineweb-data",
)

您需要对源仓库或存储桶具有读取权限，并对目标存储桶具有写入权限。

请注意，目前尚不支持在不重新上传的情况下将数据从存储桶反向传输到仓库（模型、数据集、Space），但该功能已列入路线图。

跟踪更改

Bucket 是可变的，因此那些持有 Bucket 视图的工具——挂载、文件系统层、同步守护进程、仪表盘——需要知道文件何时发生变化。有两种可用的机制：

Webhooks：发往您控制的服务器或每次变更时启动的 Job 的 HTTP 回调——请参阅使用 Jobs 处理存储桶中的新文件。
实时跟踪：客户端订阅的服务器发送事件流。

实时跟踪

GET https://huggingface.co/api/buckets/<owner>/<bucket-name>/events 以 server-sent events 的形式流式传输 bucket 的文件变更。请求必须携带 Accept: text/event-stream（否则将返回 400），并且需要与列出 bucket 相同的读取权限——对于公开 bucket，无需提供 token。完整的参数和响应模式请参阅 OpenAPI spec。

curl -N -H "Accept: text/event-stream" \
  -H "Authorization: Bearer $HF_TOKEN" \
  "https://huggingface.co/api/buckets/username/my-bucket/events"

在 Python 中，您无需自行消费流。HfFileSystem 会在 live_follow=True 的情况下为您进行跟踪，因此当另一个进程更改存储桶时，其缓存的列表会保持最新：
from huggingface_hub import HfFileSystem

hffs = HfFileSystem(live_follow=True)
hffs.ls("buckets/username/my-bucket/data")  # starts following the bucket
接受 fsspec storage_options 的库（pandas、PyArrow 等）也接受该参数。

该流会发出四种事件类型：

事件	数据	含义
`ready`	`{"cursor": "..."}`	任何请求的回放均已完成，随后将应用实时更改。
`changes`	`{"cursor": "...", "changes": [...]}`	在较短时间窗口内合并的一批文件更改。
`reset`	`{"reason": "cursor_too_old"}`	无法重放恢复点；流已结束，您应该重新列出存储桶。
`reconnect`	`{"cursor": "..."}`	服务器有意关闭了流；请使用该游标重新连接。

changes 中的每个条目都包含一个 path 和一个 op（add、update 或 delete）。add 或 update 还会携带发生变化的字段——size、xetHash、uploadedAt、mtime、mtimeNanos——因此，当文件被完全相同地重新上传时，update 可能仅包含一个新的 uploadedAt。未发生变化的字段会被省略；如果上传操作清除了 mtime/mtimeNanos，它们也可能为 null，因此应将缺失和 null 视为等同。

event: ready
data: {"cursor":"..."}

event: changes
data: {"cursor":"...","changes":[{"path":"data/train.txt","op":"add","size":20,"uploadedAt":"2026-09-16T09:21:45.000Z"},{"path":"data/old.txt","op":"delete"}]}

恢复。 从你建立连接的那一刻起，就会开始一个新的流。为了同时获取你错过的更改，请将你收到的最后一个 cursor（每个 ready 和 changes 事件都携带一个）作为 ?cursor=<cursor> 传入，或者将时间戳作为 ?since=<ISO timestamp> 传入（包含该时间点，例如 2026-09-16T09:21:45Z）。

仅能重放最近约 15 分钟内的变更。如果您的cursor或since早于该时间，您将收到reset而非重放：请列出一次存储桶以重建您的视图，然后从新流的ready事件中的cursor继续跟踪。恢复机制旨在弥合短暂中断，例如连接断开或重启；如果客户端离线时间较长，则应预期需要重新列出。

正在重新连接。 长连接会被回收：大约每 20 分钟（以及在部署期间），服务器会发送 reconnect 然后结束流。请将任何流的结束都视为相同情况——使用您收到的最后一个游标重新连接。每 30 秒会发送一条 : ping 注释以保持连接活跃，因此如果流完全静默，可以认为其已失效。

503 响应表示实时跟踪功能暂时不可用——请在 Retry-After 头中指定的延迟时间后重试。

预热与 CDN

Buckets 默认存储在 Hub 的全局存储中。对于存储位置直接影响吞吐量的工作负载，您可以预热 bucket 数据，使其更接近您的计算资源。

预热会在靠近特定云提供商和区域的边缘位置缓存文件，因此您的作业可以本地读取数据，而无需跨区域拉取。这在以下场景中尤为有用：

需要快速访问大型数据集或检查点的训练集群
多区域配置，其中流水线的不同部分在不同的云中运行
向全球众多使用者分发大型工件

有关可用区域和启用预热功能的详细信息，请参阅 hf.co/storage。

用例

训练检查点和日志

在运行训练任务（例如通过 Jobs）时，请将检查点和日志保存到存储桶中。与 Git 仓库不同，您可以覆盖最新的检查点而无需累积版本历史，并且 sync 可确保仅传输已更改的数据。

# After each evaluation step, sync checkpoints to a bucket
hf sync ./checkpoints hf://buckets/my-org/training-run-42/checkpoints

由于存储桶基于 Xet 构建，在模型大部分参数被冻结的连续检查点中，可以利用块级去重。仅上传发生变化的块。

数据处理流水线

Buckets 充当数据处理工作流的暂存区域。处理原始数据，将中间输出写入 bucket，然后在管道完成时将最终产物提升为版本化的 Dataset 仓库。这既保持了版本化仓库的整洁，又为您的管道提供了快速的可变存储。

请注意，目前尚不支持在不重新上传的情况下将数据从 Bucket 传输到仓库，但该功能已列入路线图。

智能体存储

AI 智能体需要一个临时存储空间来存放中间结果、工具输出、追踪记录和工作记忆。Bucket 为此类数据提供了一个 Hub 原生的存储位置：无需 Git 开销即可实现快速的可变访问，支持标准的 Hugging Face 权限管理，并且可以通过 hf://buckets/ 路径在整个 Hub 生态系统中进行寻址。

滚动备份

Bucket 非常适合用于维护滚动备份。对于基于 Git 的 Dataset 仓库，删除过时的文件并不会释放存储空间——Git 历史会保留所有过往版本，因此你需要压缩提交或重写历史才能真正回收空间。而使用 Bucket 时，旧文件一旦删除便真正消失，你只需为当前存储的内容付费。

# Sync today's backup, removing files that no longer exist locally
hf sync ./daily-backup hf://buckets/my-user/backups/latest --delete

将模型链接到存储桶

您可以通过在模型卡元数据中添加 buckets 字段，在模型和 bucket 之间创建双向链接。之后，关联的模型将显示在 bucket 页面上，而 bucket 则会作为标签显示在模型页面上。

# In the model card YAML frontmatter
buckets:
- my-org/my-bucket

有关更多详细信息，请参阅模型卡片文档中的指定存储桶。

定价

存储桶根据存储的数据量计费，采用简单的按 TB 计价方式。企业版方案可享受基于去重的计费，文件间共享的数据块会直接减少计费占用空间。

与其他仓库一样，存储桶可以免费创建，并享有一定的免费存储额度。关于超出免费额度的使用，请参阅hf.co/storage。有关通用账单信息，请参阅账单文档。

Update on GitHub

←获取用户计划和状态访问模式→