# 存储桶 Storage Buckets 是 Hugging Face Hub 上的一种仓库类型，提供类似 S3 的对象存储，由 [Xet](./xet/index) 存储后端提供支持。与基于 Git 的 [repositories](./repositories)（模型、数据集、Spaces）不同，buckets 是 **非版本化** 且 **可变的**，专为需要简单、快速存储的场景而设计，例如训练检查点、日志、中间产物，或任何无需版本控制的大型文件集合。 您可以通过 Hub 网页界面、[`hf` CLI](https://huggingface.co/docs/huggingface_hub/guides/cli#hf-buckets) 或 [Python API](https://huggingface.co/docs/huggingface_hub/guides/buckets) 与存储桶进行交互。 > [!TIP] > Buckets 对所有用户和组织均可用。有关定价详情，请参阅 [hf.co/storage](https://huggingface.co/storage)。 > [!TIP] > 请参阅 [访问模式](./storage-buckets-access) 了解如何从您的工具访问桶数据（挂载为文件系统、`hf://` 路径、Jobs/Spaces 中的卷挂载），[S3 兼容 API](./storage-buckets-s3) 用于使用现有的 S3 工具（AWS CLI、boto3、s5cmd），以及 [桶集成](./storage-buckets-integrations) 用于在 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 界面 1. 前往 [huggingface.co/new-bucket](https://huggingface.co/new-bucket)： 2. 指定存储桶的所有者：可以是您本人，也可以是您所属的任何组织。 3. 输入一个存储桶名称。 4. 选择存储桶应为公开还是私有。 5. 可选地，预选择[CDN 预热](#pre-warming-and-cdn)区域，以便从一开始就将您的数据缓存到更接近计算资源的位置。 创建存储桶后，您应该能看到存储桶页面： ### 从 CLI ```bash # 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 ```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") ``` ### 更改可见性 您可以在创建后更改存储桶的可见性： ```bash # Make a bucket private hf buckets settings username/my-bucket --private # Make it public again hf buckets settings username/my-bucket --public ``` ```python 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 指南](https://huggingface.co/docs/huggingface_hub/guides/buckets)。 ## 在 Hub 上浏览 Buckets 每个存储桶在 Hub 上都有一个页面，您可以在其中浏览其内容、导航目录并查看文件详情。存储桶页面位于 `https://huggingface.co/buckets//`。 ### README 渲染 如果存储桶中的某个目录包含 `README.md` 文件，Hub 会在该目录页面的文件列表下方渲染它。这在存储桶根目录和任何子目录中均有效——可用于记录存储桶的内容、数据的组织方式，或下游工具应如何消费这些数据。 ### 从 CLI 列出 您也可以通过 CLI 列出存储桶的内容： ```bash # 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` 进行 **服务端** 复制——无需下载或重新上传。请参阅 [在仓库和存储桶之间复制文件](#copying-files-between-repos-and-buckets)。 ### 上传文件 如需快速上传，您可以直接在浏览器中的存储桶页面拖放文件。若需以编程方式使用，`hf buckets cp` 可将单个文件复制到存储桶中。源为本地路径，目标为 `hf://buckets/` 路径。您还可以从标准输入（stdin）通过管道传入数据，这对于以编程方式生成的内容非常实用。 **命令行界面：** ```bash # 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：** ```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` 上传指南](https://huggingface.co/docs/huggingface_hub/guides/buckets#upload-files)。 ### 下载文件 您可以直接在 Hub 的存储桶页面上单击文件来下载单个文件。对于编程访问，下载操作与上传语法类似——只需在 `hf buckets cp` 中交换源和目的地即可。您还可以使用 `-` 作为目的地，将文件流式传输到标准输出，从而将存储桶内容直接通过管道传递给其他工具。 **命令行界面：** ```bash # 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：** ```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` 下载指南](https://huggingface.co/docs/huggingface_hub/guides/buckets#download-files)。 ### 同步目录 `sync` 命令的工作方式类似于 `rsync` 或 `aws s3 sync`——它会比较源和目的地，仅传输已更改的文件。这是保持本地目录与存储桶同步的最高效方式。默认情况下，`sync` 仅添加和更新文件。传入 `--delete` 以同时删除目的地中在源端已不存在的文件。使用 `--dry-run` 可在不实际传输任何内容的情况下预览将发生的变化。 **命令行界面：** ```bash # 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 ``` > [!TIP] > `hf sync` 是 `hf buckets sync` 的便捷别名。 **Python：** ```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` 同步指南](https://huggingface.co/docs/huggingface_hub/guides/buckets#sync-directories)。 ### 删除文件 由于存储桶不启用版本控制，删除操作会立即生效且不可逆——无法恢复已删除的文件。在删除文件前，尤其是使用 `--recursive` 时，请使用 `--dry-run` 进行二次确认。 **命令行界面：** ```bash # 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：** ```python from huggingface_hub import batch_bucket_files batch_bucket_files("username/my-bucket", delete=["old-model.bin", "logs/debug.log"]) ``` 有关更多删除选项（基于模式的过滤、递归删除等），请参阅 [`huggingface_hub` 删除指南](https://huggingface.co/docs/huggingface_hub/guides/buckets#delete-files)。 ### 在仓库和存储桶之间复制文件 您可以将任何仓库（模型、数据集、Space）或存储桶中由 [Xet](./xet/index) 跟踪的文件复制到目标存储桶，而无需重新上传数据。该复制操作在服务器端执行：仅迁移 Xet 内容哈希，因此借助 [块级去重](./xet/deduplication)，即使是非常大的文件也能瞬间完成复制。 > [!NOTE] > 仅 Xet 跟踪的文件会在服务器之间复制。小型非 Xet 文件（例如配置文件和 README）会自动下载并重新上传。服务器端复制还要求源和目的地位于同一存储区域。 **命令行界面：** ```bash hf buckets cp \ hf://datasets/HuggingFaceFW/fineweb/data \ hf://buckets/username/fineweb-data ``` **Python：** ```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](./webhooks#buckets)：发往您控制的服务器或每次变更时启动的 [Job](./jobs) 的 HTTP 回调——请参阅 [使用 Jobs 处理存储桶中的新文件](./webhooks-guide-bucket-jobs)。 - **实时跟踪**：客户端订阅的服务器发送事件流。 ### 实时跟踪 `GET https://huggingface.co/api/buckets///events` 以 [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) 的形式流式传输存储桶的文件变更。请求必须携带 `Accept: text/event-stream`（否则将返回 `400`），并且需要与列出存储桶相同的读取权限——对于公共存储桶，无需提供令牌。完整的参数和响应模式请参阅 [OpenAPI 规范](https://huggingface.co/spaces/huggingface/openapi#tag/buckets/GET/api/buckets/{namespace}/{repo}/events)。 ```bash curl -N -H "Accept: text/event-stream" \ -H "Authorization: Bearer $HF_TOKEN" \ "https://huggingface.co/api/buckets/username/my-bucket/events" ``` > [!TIP] > 在 Python 中，您无需自行消费流。[`HfFileSystem`](/docs/huggingface_hub/guides/hf_file_system#keep-listings-fresh) 会通过 `live_follow=True` 为您进行跟踪，因此当另一个进程更改存储桶时，其缓存的列表会保持最新： > > ```python > 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=` 传入，或者将时间戳作为 `?since=` 传入（包含该时间点，例如 `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](https://huggingface.co/storage)。 ## 用例 ### 训练检查点和日志 在运行训练任务（例如通过 [Jobs](./jobs)）时，请将检查点和日志保存到存储桶中。与 Git 仓库不同，您可以覆盖最新的检查点而无需累积版本历史，并且 `sync` 可确保仅传输已更改的数据。 ```bash # After each evaluation step, sync checkpoints to a bucket hf sync ./checkpoints hf://buckets/my-org/training-run-42/checkpoints ``` 由于存储桶基于 [Xet](./xet/index) 构建，在模型大部分参数被冻结的连续检查点中，可以利用块级去重。仅上传发生变化的块。 ### 数据处理流水线 Buckets 充当数据处理工作流的暂存区域。处理原始数据，将中间输出写入 bucket，然后在管道完成时将最终产物提升为版本化的 [Dataset](./datasets) 仓库。这既保持了版本化仓库的整洁，又为您的管道提供了快速的可变存储。 请注意，目前尚不支持在不重新上传的情况下将数据从 Bucket 传输到仓库，但该功能已列入路线图。 ### 智能体存储 AI 智能体需要一个临时存储空间来存放中间结果、工具输出、追踪记录和工作记忆。Bucket 为此类数据提供了一个 Hub 原生的存储位置：无需 Git 开销即可实现快速的可变访问，支持标准的 Hugging Face 权限管理，并且可以通过 `hf://buckets/` 路径在整个 Hub 生态系统中进行寻址。 ### 滚动备份 Bucket 非常适合用于维护滚动备份。对于基于 Git 的 [Dataset](./datasets) 仓库，删除过时的文件并不会释放存储空间——Git 历史会保留所有过往版本，因此你需要压缩提交或重写历史才能真正回收空间。而使用 Bucket 时，旧文件一旦删除便真正消失，你只需为当前存储的内容付费。 ```bash # 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 则会作为标签显示在模型页面上。 ```yaml # In the model card YAML frontmatter buckets: - my-org/my-bucket ``` 有关更多详细信息，请参阅模型卡片文档中的 [指定存储桶](./model-cards#specifying-a-bucket)。 ## 定价 存储桶根据存储的数据量计费，采用简单的按 TB 计价方式。企业版方案可享受基于去重的计费，文件间共享的数据块会直接减少计费占用空间。 与其他仓库一样，存储桶可以免费创建，并享有一定的免费存储额度。关于超出[免费额度](https://huggingface.co/docs/hub/storage-limits)的使用，请参阅[hf.co/storage](https://huggingface.co/storage)。有关通用账单信息，请参阅[账单](./billing)文档。