Бuckets для хранения

Storage Buckets — это тип репозитория на Hugging Face Hub, обеспечивающий объектное хранилище, аналогичное S3, на базе хранилища Xet. В отличие от репозиториев на основе Git (модели, наборы данных, Spaces), бакеты являются неверсионированными и изменяемыми, что делает их пригодными для сценариев, где требуется простое и быстрое хранилище, например для контрольных точек обучения, журналов, промежуточных артефактов или любых больших коллекций файлов, не требующих контроля версий.

Вы можете взаимодействовать с бакетами с помощью веб-интерфейса Hub, CLI hf или Python API.

Buckets доступны всем пользователям и организациям. Подробности о тарифах см. на hf.co/storage.

См. раздел Access Patterns, чтобы узнать, как получить доступ к данным в bucket из ваших инструментов (монтирование в качестве файловой системы, пути hf://, монтирование томов в Jobs/Spaces), раздел S3-Compatible API для использования существующих S3-инструментов (AWS CLI, boto3, s5cmd) и раздел Bucket Integrations с готовыми фрагментами кода для популярных библиотек данных, таких как pandas, Dask и Spark.

Бакеты и репозитории

Hub предлагает два типа хранилища: репозитории на базе Git для версионирования и совместной работы, а также бакеты для быстрого изменяемого объектного хранилища.

Используйте репозитории, если вам нужна история версий, функции для совместной работы (PR, обсуждения) и интеграции с библиотеками. Используйте бакеты, если вам требуется быстрое изменяемое хранилище для данных, которые часто меняются — файлы можно перезаписывать или удалять на месте.

Создание хранилища

Из интерфейса Hub

1. Перейдите на huggingface.co/new-bucket:

2. Укажите владельца бакета: это может быть либо вы, либо одна из организаций, с которыми вы связаны.

3. Введите имя хранилища.

4. Выберите, должен ли бакет быть публичным или частным.

5. При необходимости предварительно выберите регионы предварительного прогрева 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

У каждого бакета есть страница на Hub, где можно просматривать его содержимое, переходить по каталогам и видеть детали файлов. Страницы бакетов доступны по адресу https://huggingface.co/buckets/<owner>/<bucket-name>.

Отображение README

Если в каталоге вашего bucket-хранилища есть файл README.md, Hub отображает его под списком файлов на странице этого каталога. Это работает как в корне bucket-хранилища, так и в любом подкаталоге — удобно для описания содержимого bucket-хранилища, структуры данных или того, как downstream-инструменты должны использовать эти данные.

Получение списка из 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, что удобно для программно сгенерированного контента.

CLI:

# 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. Также можно передать файл в stdout, используя - в качестве назначения, что позволяет напрямую передавать содержимое бакета в другие инструменты через конвейер.

CLI:

# 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, чтобы просмотреть, что произойдёт, без фактической передачи данных.

CLI:

# 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) и рабочий процесс plan-and-apply для проверки операций перед их выполнением. Полный список параметров см. в руководстве по синхронизации huggingface_hub.

Удаление файлов

Поскольку бакеты не поддерживают версионирование, удаление происходит немедленно и безвозвратно — восстановить удалённый файл невозможно. Используйте --dry-run, чтобы перепроверить действия перед удалением файлов, особенно при использовании --recursive.

CLI:

# 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.

Копирование файлов между репозиториями и хранилищами

Вы можете копировать файлы, отслеживаемые Xet, из любого репозитория (модели, набора данных, Space) или хранилища в целевое хранилище без повторной загрузки данных. Копирование выполняется на стороне сервера: мигрируются только хеши содержимого Xet, поэтому даже очень большие файлы копируются мгновенно благодаря дедупликации на уровне чанков.

Копирование с сервера на сервер выполняется только для файлов, отслеживаемых Xet. Небольшие файлы, не отслеживаемые Xet (например, файлы конфигурации и README), автоматически скачиваются и повторно загружаются. Для копирования на стороне сервера также требуется, чтобы источник и назначение находились в одном и том же регионе хранения.

CLI:

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) — без повторной загрузки пока недоступна, но запланирована в дорожной карте.

Отслеживание изменений

Buckets изменяемы, поэтому инструменты, сохраняющие представление о bucket — монтирования, слои файловой системы, демон синхронизации, дашборды — должны знать, когда файлы изменяются. Доступны два механизма:

• Webhooks: HTTP-колбэки на сервер, которым вы управляете, или Job, запускаемый при каждом изменении — см. Обработка новых файлов в бакете с помощью Jobs.
• Live follow: поток событий, отправляемых сервером, на который подписывается ваш клиент.

Live follow

GET https://huggingface.co/api/buckets/<owner>/<bucket-name>/events транслирует изменения файлов в bucket в формате server-sent events. Запрос должен содержать заголовок Accept: text/event-stream (иначе вернется 400), а также требует тех же прав на чтение, что и для получения списка содержимого bucket — для публичного bucket токен не нужен. Полную схему параметров и ответа см. в спецификации OpenAPI.

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

Библиотеки, принимающие storage_options fsspec (pandas, PyArrow, …), также поддерживают его.

Поток излучает четыре типа событий:

Каждая запись в 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: выполните перечисление бакета один раз, чтобы восстановить представление, а затем продолжайте отслеживание с cursor из события ready нового потока. Возобновление предназначено для преодоления коротких пауз, таких как потеря соединения или перезапуск; клиент, отсутствовавший дольше, должен ожидать повторного перечисления.

Переподключение. Долгоживущие соединения пересоздаются: примерно каждые 20 минут (а также во время развёртываний) сервер отправляет reconnect, а затем завершает поток. Относитесь к любому завершению потока одинаково — переподключайтесь с помощью последнего полученного курсора. Комментарий : ping отправляется каждые 30 секунд для поддержания соединения, поэтому полностью бездействующий поток можно считать мёртвым.

Ответ 503 означает, что live follow временно недоступен — повторите запрос после задержки, указанной в заголовке Retry-After.

Предварительное прогревание и CDN

По умолчанию данные бакетов хранятся в глобальном хранилище Hub. Для рабочих нагрузок, в которых расположение хранилища напрямую влияет на пропускную способность, вы можете предварительно загрузить данные бакета, чтобы приблизить их к вашим вычислительным ресурсам.

Функция Pre-warming кэширует файлы в узлах сети доставки контента (edge locations), расположенных вблизи конкретных облачных провайдеров и регионов, благодаря чему ваши задания читают данные локально, а не загружают их из других регионов. Это особенно полезно в следующих случаях:

• Кластеры обучения, которым требуется быстрый доступ к большим наборам данных или контрольным точкам
• Многорегиональные конфигурации, в которых различные части конвейера выполняются в разных облаках
• Распределение крупных артефактов среди множества потребителей по всему миру

Список доступных регионов и информация о включении предварительного прогрева приведены на 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-агентам требуется временное хранилище для промежуточных результатов, выводов инструментов, трассировок и рабочей памяти. Buckets предоставляют нативное для Hub место для этих данных: быстрый изменяемый доступ без накладных расходов Git, стандартные разрешения Hugging Face и адресация через пути hf://buckets/ во всей экосистеме Hub.

Резервные копии

Бакеты хорошо подходят для создания резервных копий по принципу скользящего окна. В случае с репозиторием Dataset на базе Git удаление устаревших файлов не освобождает место на диске — история Git сохраняет все предыдущие версии, поэтому для фактического освобождения пространства необходимо объединять коммиты или переписывать историю. В бакетах старые файлы действительно исчезают после удаления, и вы платите только за то, что хранится в данный момент.

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

Связывание моделей с бакетами

Вы можете создать двустороннюю связь между моделью и bucket, добавив поле buckets в метаданные карточки модели. Связанные модели будут отображаться на странице bucket, а bucket будет отображаться как тег на странице модели.

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

См. раздел Указание бакета в документации по карточкам моделей для получения дополнительных сведений.

Тарифы

Тарификация хранилищ Buckets основана на объёме хранящихся данных и рассчитывается по простой ставке за ТБ. Пользователи корпоративных тарифов получают выгоду от тарификации на основе дедупликации, при которой общие фрагменты между файлами напрямую уменьшают объём, за который взимается плата.

Что касается других репозиториев, создание бакетов бесплатно, и предусмотрен бесплатный лимит хранилища. Для использования сверх бесплатного тарифа см. hf.co/storage. Общую информацию о тарификации см. в документации Billing.