Совместимость с S3

Storage Buckets доступны через совместимый с S3 API, что позволяет использовать существующие инструменты S3 — AWS CLI, boto3, s5cmd и большинство других S3 SDK — для работы с вашими бакетами без изменения кода. Запросы обрабатываются через шлюз по адресу https://s3.hf.co.

S3 API — один из нескольких способов доступа к данным в бакете. Для доступа, нативного для Hugging Face (hf CLI, пути hf:// и монтирование файловой системы) без отдельных S3-учётных данных, см. Access Patterns.

API S3 работает только с Storage Buckets. Он не предоставляет доступ к другим типам репозиториев Hugging Face (модели, наборы данных, Spaces).

Генерация учётных данных S3

Шлюз выполняет аутентификацию с помощью ключей доступа в стиле AWS, полученных из User Access Token Hugging Face.

1. Перейдите в настройки токенов доступа. Если у вас ещё нет токена, создайте его с помощью кнопки Create new token. Права токена становятся правами учётных данных S3 — выберите Read для доступа только на чтение к вашим бакетам или Write для доступа на чтение и запись.

2. Найдите токен в списке, откройте его выпадающее меню и выберите Generate S3 credentials.

   

3. Скопируйте сгенерированный идентификатор ключа доступа (с префиксом HFAK…) и секретный ключ доступа в безопасное место — секрет отображается только один раз.

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

Для автоматизированных рабочих процессов, обращающихся к бакетам организации, вы также можете генерировать учётные данные S3 из токена service account, а не из User Access Token.

Настройка клиента

Настройте ваш S3-клиент на использование конечной точки шлюза и задайте несколько обязательных параметров. В URL конечной точки укажите ваше пространство имён Hugging Face (имя пользователя или название организации) — см. раздел Адресация бакетов ниже.

Два параметра контрольных сумм важны для последних версий клиентов: AWS CLI ≥ 2.23 и недавние версии boto3 по умолчанию отправляют контрольные суммы CRC32 в конце (через фрейминг aws-chunked), которые шлюз не обрабатывает. Эти параметры указывают клиенту отправлять контрольные суммы только в тех случаях, когда операция строго их требует.

Следующие параметры необязательны, но их использование рекомендуется, чтобы при загрузке больших файлов использовалось как можно меньше частей multipart:

Пример: профиль AWS CLI

Добавьте профиль в ~/.aws/config:

[profile hf]
region = us-east-1
endpoint_url = https://s3.hf.co/<namespace>
s3 =
    addressing_style = path
    multipart_threshold = 2GB
    multipart_chunksize = 2GB
request_checksum_calculation = when_required
response_checksum_validation = when_required

Примечание: замените <namespace> выше на имя пользователя или организацию, в которой хранятся ваши бакеты.

Добавьте соответствующие учётные данные для профиля в ~/.aws/credentials:

[hf]
aws_access_key_id = HFAK...
aws_secret_access_key = ...

Затем используйте любую команду S3 с этим профилем:

aws --profile hf s3 ls
aws --profile hf s3 mb s3://my-bucket
aws --profile hf s3 cp ./model.safetensors s3://my-bucket/models/model.safetensors

Адресация бакетов

AWS S3 использует единое плоское пространство глобально уникальных имён бакетов, а SDK ожидают, что имя бакета будет простой строкой без /. Бакеты Hugging Face идентифицируются как namespace/bucket, где namespace — это ваше имя пользователя или организации. Этот дополнительный уровень создаёт несовместимость с S3-клиентами: многие из них не принимают / в имени бакета или неверно экранируют его в URL. Существует два способа обойти эту проблему:

1. Укажите пространство имён в URL конечной точки (рекомендуется в большинстве случаев). Это ограничивает каждую операцию этим пространством имён, поэтому имя бакета, передаваемое клиенту, — это просто имя HF-бакета. Такой подход хорошо работает для собственных бакетов или бакетов в рамках одной организации, но не подходит для операций между пространствами имён — например, для серверного копирования из личного бакета в бакет организации.

aws --endpoint-url https://s3.hf.co/my-org s3api get-object \
  --bucket my-bucket --key some/object.txt ./object.txt

2. Рассматривайте пространство имён как бакет и добавляйте имя HF-бакета в начало ключа объекта. Это работает для операций на уровне объектов (загрузка, выгрузка), но вызывает проблемы при операциях на уровне бакета, таких как создание или удаление бакетов.

aws --endpoint-url https://s3.hf.co s3api get-object \
  --bucket my-org --key my-bucket/some/object.txt ./object.txt

Ограничения и отличия от AWS S3

Поскольку Storage Buckets не моделируют все концепции S3, некоторые поведения отличаются или не поддерживаются.

Скачивание объектов

Шлюз в настоящее время работает в одном регионе. Для улучшения производительности загрузки GetObject обычно отвечает HTTP-редиректом 302 на ближайший узел CDN Hugging Face, а не передаёт байты напрямую.

Некоторые SDK не следуют перенаправлениям с конечной точки S3, поэтому шлюз определяет клиентов, идентифицирующих себя как aws-cli, botocore (что покрывает boto3), или aws-sdk-rust и проксирует данные для них через себя. Все остальные клиенты (rclone, s5cmd, curl, AWS Go SDK и т. д.) получают ответ 302 и следуют ему нативно, исключая шлюз из пути данных для более быстрого скачивания.

Именование ключей объектов

Ключи объектов в Bucket более ограничены, чем в S3. Ключ не должен содержать:

• начинается или заканчивается на /
• содержат последовательные слэши (//)
• содержат последовательности ../
• начинается с ./
• заканчиваются на ..
• содержат обратные слэши (\) или нулевые байты (\0)

ListObjects

• ListObjectsV1 не поддерживается — используйте ListObjectsV2. Обратите внимание, что некоторые клиенты (например, rclone) могут требовать настройки для использования исключительно ListObjectsV2.
• В качестве разделителя допускается только /.

Другие различия в API

• Метаданные объекта: произвольные пользовательские метаданные (x-amz-meta-*) не сохраняются и не возвращаются. Поддерживается Content-Type.
• Неподдерживаемые функции: ACL, политики хранения, метки объектов, версионирование объектов, правила жизненного цикла, серверное шифрование (SSE) и уведомления о событиях в хранилище не поддерживаются. Объекты всегда сообщаются с классом хранения STANDARD. Соответствующие заголовки и параметры запроса принимаются, но игнорируются.
• CopyObject: серверное копирование работает только в пределах одного пространства имён. Копирование между пространствами имён и UploadPartCopy (копирование части из существующего объекта в multipart-загрузку) не поддерживаются.
• Условные запросы: предикаты If-Match / If-None-Match учитываются для PutObject и для источника копирования в CopyObject, но не для GetObject.
• Срок действия многочастной загрузки: незавершённые и не прерванные многочастные загрузки автоматически истекают и удаляются через 7 дней.

Примеры

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

Чтение и запись с помощью boto3

boto3 работает с шлюзом с указанными выше настройками клиента. Замените <namespace> на ваше имя пользователя или организацию:

import boto3
from botocore.config import Config

s3 = boto3.client(
    "s3",
    endpoint_url="https://s3.hf.co/<namespace>",
    aws_access_key_id="HFAK...",
    aws_secret_access_key="...",
    config=Config(
        region_name="us-east-1",
        s3={"addressing_style": "path"},
        request_checksum_calculation="when_required",
        response_checksum_validation="when_required",
    ),
)

s3.upload_file("model.safetensors", "my-bucket", "models/model.safetensors")
s3.download_file("my-bucket", "models/model.safetensors", "model.safetensors")

Запрос к бакету с помощью DuckDB

В DuckDB 2.0 и более поздних версиях расширение httpfs напрямую читает пути hf://buckets/, а с расширением hf также позволяет записывать данные в Buckets. См. Запросы с помощью DuckDB.

Для более ранних версий DuckDB или для записи результатов запросов обратно в бакет с помощью COPY ... TO без расширения используйте S3-шлюз:

INSTALL httpfs;
LOAD httpfs;

CREATE SECRET hf (
    TYPE s3,
    KEY_ID 'HFAK...',
    SECRET '...',
    ENDPOINT 's3.hf.co/<namespace>',
    URL_STYLE 'path',
    REGION 'us-east-1'
);

SELECT * FROM read_parquet('s3://my-bucket/data.parquet');

Необязательно указывать URL_STYLE 'path'. Без него DuckDB использует адресацию в стиле виртуального хоста (my-bucket.s3.hf.co), которую шлюз не поддерживает — вы увидите ошибку «Could not resolve hostname».

Импорт данных с помощью rclone

rclone — удобный способ копирования данных между двумя хранилищами, совместимыми с S3, поэтому он хорошо подходит для переноса существующего бакета AWS S3 (или любого другого источника, совместимого с S3) в Storage Bucket.

Идея состоит в том, чтобы объявить два удалённых хранилища — исходный бакет и шлюз Hugging Face — и позволить rclone передавать объекты между ними. Добавьте оба удалённых хранилища в ~/.config/rclone/rclone.conf. Первое указывает на ваш существующий S3-бакет; настройте его в соответствии с вашим источником (здесь — обычный AWS S3):

[aws]
type = s3
provider = AWS
access_key_id = AKIA...
secret_access_key = ...
region = us-east-1

Второй указывает на шлюз Hugging Face. Как и в случае с любым другим клиентом, ограничьте конечную точку вашим пространством имён, используйте адресацию по path, принудительно применяйте ListObjectsV2 (единственную поддерживаемую шлюзом версию перечисления) и задавайте большие размеры частей для multipart-загрузок, чтобы при загрузке использовалось как можно меньше частей:

[hf]
type = s3
provider = Other
endpoint = https://s3.hf.co/<namespace>
access_key_id = HFAK...
secret_access_key = ...
region = us-east-1
force_path_style = true
list_version = 2
upload_cutoff = 2G
chunk_size = 2G

Примечание: замените <namespace> выше на имя пользователя или организацию, в которой хранятся ваши бакеты, и используйте учётные данные S3, сгенерированные из вашего токена доступа. Целевой бакет должен уже существовать в этом пространстве имён.

Теперь скопируйте исходное хранилище в ваше хранилище Storage Bucket:

rclone copy aws:my-source-bucket hf:my-bucket --progress

rclone copy переносит только те объекты, которых нет в пункте назначения или которые были изменены, поэтому повторный запуск безопасен: он позволяет возобновить прерванный импорт или получить новые объекты. Чтобы сделать пункт назначения точным зеркалом источника — удалив объекты, которые больше не существуют в источнике, — используйте вместо этого rclone sync:

rclone sync aws:my-source-bucket hf:my-bucket --progress

Для больших импортов добавьте --transfers и --checkers, чтобы увеличить параллелизм (например, --transfers 16 --checkers 16), а затем выполните rclone check aws:my-source-bucket hf:my-bucket, чтобы убедиться, что все объекты были перенесены.

Версионирование данных с DVC

DVC версионирует наборы данных и модели в git, сохраняя в репозитории небольшие файлы-указатели и отправляя сами данные на удалённый сервер. Бакет работает как удалённый сервер DVC через шлюз, поэтому ваш код и указатели .dvc остаются в git, а данные хранятся в вашем бакете. Установите DVC с поддержкой S3 (pip install 'dvc[s3]'), затем добавьте удалённый сервер, используя настройки клиента, описанные выше:

dvc remote add -d hf-bucket s3://my-bucket/dvc-store
dvc remote modify hf-bucket endpointurl https://s3.hf.co/<namespace>
dvc remote modify hf-bucket region us-east-1

Передайте учётные данные S3 через переменные окружения или с помощью dvc remote modify --local, чтобы они не попадали в git:

export AWS_ACCESS_KEY_ID=HFAK...
export AWS_SECRET_ACCESS_KEY=...

Затем отслеживайте, отправляйте и получайте данные как обычно — dvc push загружает их в бакет, а dvc pull в новом клоне скачивает их обратно:

dvc add data/
git add data.dvc .gitignore .dvc/config && git commit -m "Track data with DVC"
dvc push

Используйте свой namespace в endpointurl и имя «голого» бакета в URL s3://.