Зачем еще одно хранилище, если есть S3?

Представьте: вы обучаете модель, и каждый чекпоинт весит 10-20 ГБ. Амазон S3 стоит денег, настройка IAM головная боль, а выгружать промежуточные результаты в публичный репозиторий Hugging Face не хочется. Знакомо? Именно эту проблему решают Hugging Face Storage Buckets.

С марта 2025 года Storage Buckets интегрированы с платформой Xet, что обеспечивает дедупликацию и эффективное хранение. На 10 марта 2026 года это основной способ хранения приватных ML-артефактов на Hugging Face.

Что внутри: S3-совместимость и адресация hf://

Storage Buckets - это объектное хранилище с API, идентичным Amazon S3. Вы можете использовать знакомые библиотеки вроде boto3 или стандартные S3-клиенты. Но главная фишка - адресация через схему hf://. Например, hf://username/bucket-name/path/to/file. Это позволяет интегрировать хранилище в пайплайны, как если бы это был частью Hugging Face Hub.

Как это работает с Xet?

Под капотом используется Xet Storage, который обеспечивает дедупликацию на уровне блоков. Если вы сохраняете несколько версий одной модели, измененные части будут храниться только один раз. Это экономит место и ускоряет загрузку.

💡

Дедупликация особенно полезна для чекпоинтов: между эпохами меняются лишь веса, а архитектура остается той же. Xet хранит только дельты.

Настройка за 5 минут

1 Установите hf CLI последней версии

pip install -U huggingface-hub[cli]

На 10 марта 2026 года актуальна версия 1.0.0 huggingface-hub, которая включает все необходимые команды для работы с Storage Buckets.

2 Аутентификация

huggingface-cli login

Или установите переменную среды HF_TOKEN.

3 Создайте бакет

huggingface-cli storage-create my-bucket

Бакет создается в вашем пространстве имен. Для организаций используйте --org.

Примеры использования: от Python до CLI

Самый простой способ - использовать hf CLI для загрузки и скачивания. Но для автоматизации подойдет Python.

from huggingface_hub import HfApi

api = HfApi()
# Загрузка файла
api.upload_file(
    path_or_fileobj="/local/path/to/model.bin",
    path_in_repo="checkpoints/epoch-1/model.bin",
    repo_id="username/my-bucket",
    repo_type="storage",
)

# Скачивание
api.hf_hub_download(
    repo_id="username/my-bucket",
    filename="checkpoints/epoch-1/model.bin",
    repo_type="storage",
    local_dir="/local/download",
)

А если вы привыкли к S3 API, то можно использовать boto3:

import boto3
from huggingface_hub import get_storage_endpoint

endpoint = get_storage_endpoint()
s3 = boto3.client(
    's3',
    endpoint_url=endpoint,
    aws_access_key_id='your_hf_token',
    aws_secret_access_key='your_hf_token',  # Тот же токен
)

s3.upload_file('/local/file', 'bucket-name', 'path/in/bucket')

Внимание: для S3-совместимого API используйте ваш HF_TOKEN как access key и secret key. Это временное решение, в будущем могут появятся отдельные ключи.

Сравнение с альтернативами: когда выбирать Storage Buckets

Хранилище	Плюсы	Минусы	Когда использовать
Hugging Face Storage Buckets	Интеграция с HF-экосистемой, дедупликация через Xet, бесплатные квоты	Ограниченная геораспространенность, нет версионирования объектов	ML-артефакты, чекпоинты, приватные датасеты
Amazon S3	Высокая надежность, множество регионов, богатый API	Дорого для больших объемов, сложная настройка IAM	Критичные данные, высокие нагрузки
Google Cloud Storage	Интеграция с Google AI, мультирегиональность	Цены могут быть выше, привязка к Google Cloud	Если уже используете GCP
Hugging Face Hub (модели/датасеты)	Публикация и обнаружение, версионирование Git	Не для промежуточных файлов, публичность по умолчанию	Финальные модели и датасеты для сообщества

Storage Buckets занимают нишу между публичным Hub и облачными хранилищами. Они идеальны для того, что не должно быть публичным, но должно быть доступно из пайплайнов HF.

Интеграция в ML-пайплайны: реальные сценарии

Допустим, вы обучаете модель с помощью нашего руководства по обучению LLM. Вместо того чтобы сохранять чекпоинты на локальный диск, вы загружаете их в Storage Bucket. Затем, если обучение прервалось, вы можете продолжить с последнего чекпоинта из облака.

Или вы строите локальный RAG для миллионов PDF. Эмбеддинги и индекс можно хранить в Storage Buckets, а затем загружать на несколько серверов. Дедупликация сэкономит гигабайты.

Для мобильных разработчиков, которые используют Swift-клиент для Hugging Face, Storage Buckets могут стать источником моделей, которые не должны быть в публичном доступе.

Кому подойдет, а кому нет

Выбирайте Storage Buckets, если:

Вы уже в экосистеме Hugging Face и не хотите заморачиваться с другими облаками.
Вам нужен простой способ обмениваться приватными артефактами внутри команды.
Вы хотите экономить на хранении за счет дедупликации (особенно для чекпоинтов).
Вы используете HuggingFace Downloader v2.3.0 и хотите ускорить загрузку из приватных источников.

Посмотрите в сторону альтернатив, если:

Вам нужны гарантии SLA 99.9% или конкретные регионы хранения.
Вы работаете с данными, которые требуют compliance (например, медицинские).
У вас уже настроена инфраструктура на AWS/GCP/Azure.
Вам нужно объектное версионирование или сложные политики жизненного цикла.

Что будет дальше?

На 10 марта 2026 года команда Hugging Face анонсировала интеграцию Storage Buckets с Hugging Face Hub v1.0, что упростит управление правами доступа. Ожидается, что в течение года появятся пресеты для автоматического удаления старых чекпоинтов и интеграция с MLflow.

Мой совет: если вы еще не пробовали, создайте тестовый бакет и загрузите туда пару чекпоинтов. Ощутите, насколько это проще, чем настраивать S3 с нуля. И да, это бесплатно в пределах лимитов.

А если вы столкнулись с проблемами при миграции, проверьте, не связаны ли они с KV-cache в долговременной памяти - иногда ошибки хранения маскируются под проблемы с памятью.

Подписаться на канал

Hugging Face Storage Buckets: полное руководство по S3-совместимому хранилищу для ML-артефактов