Compatibilité S3

Les Storage Buckets sont accessibles via une API compatible S3, ce qui vous permet d’utiliser les outils S3 existants — AWS CLI, boto3, s5cmd et la plupart des autres SDK S3 — sur vos buckets sans modifier votre code. Les requêtes passent par un service de passerelle situé à https://s3.hf.co.

L’API S3 est l’une des plusieurs façons d’accéder aux données d’un bucket — pour un accès natif Hugging Face (la CLI hf, les chemins hf:// et les montages de système de fichiers) sans identifiants S3 distincts, consultez Access Patterns.

L'API S3 fonctionne uniquement avec les Storage Buckets. Elle n'expose pas les autres types de dépôts Hugging Face (modèles, jeux de données, Spaces).

Génération des identifiants S3

La passerelle s'authentifie à l'aide de clés d'accès de type AWS dérivées d'un jeton d'accès utilisateur Hugging Face.

1. Accédez à vos paramètres de jetons d’accès. Créez un jeton avec le bouton Créer un nouveau jeton si vous n’en avez pas encore. Les autorisations du jeton deviennent les autorisations des identifiants S3 — choisissez Lecture pour un accès en lecture seule à vos buckets, ou Écriture pour un accès en lecture et en écriture.

2. Trouvez le jeton dans la liste, ouvrez son menu déroulant et choisissez Generate S3 credentials.

   

3. Copiez l'identifiant de clé d'accès généré (préfixé par HFAK…) et la clé d'accès secrète dans un endroit sûr — la clé secrète n'est affichée qu'une seule fois.

Les identifiants S3 héritent des autorisations du jeton d'accès sous-jacent. Pour les jetons à granularité fine, limitez leur portée aux espaces de noms et aux buckets que vous prévoyez d'utiliser.

Pour les flux de travail automatisés qui accèdent aux buckets d’une organisation, vous pouvez également générer des identifiants S3 à partir d’un jeton de compte de service plutôt que d’un jeton d’accès utilisateur.

Configurer un client

Pointez votre client S3 vers le point d'accès du gateway et définissez quelques options requises. Utilisez votre namespace Hugging Face (votre nom d'utilisateur ou le nom d'une organisation) dans l'URL du point d'accès — voir Adressage des buckets ci-dessous.

Les deux paramètres de contrôle d’intégrité sont importants pour les clients récents : AWS CLI ≥ 2.23 et les versions récentes de boto3 envoient par défaut des sommes de contrôle CRC32 de fin (via l’encadrement aws-chunked), que la passerelle n’analyse pas. Ces paramètres indiquent au client d’envoyer des sommes de contrôle uniquement lorsqu’une opération les exige strictement.

Les éléments suivants sont facultatifs mais recommandés. Avec la valeur par défaut du client de 8 Mo, un fichier volumineux est découpé en de nombreuses parties ; 256 Mo signifie beaucoup moins de parties par téléversement, tout en conservant une taille de partie suffisamment petite pour que la passerelle puisse les traiter efficacement :

Exemple : profil AWS CLI

Ajoutez un profil à ~/.aws/config :

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

Note : remplacez le <namespace> ci-dessus par le nom d'utilisateur ou l'organisation dans laquelle vos buckets sont stockés.

Ajoutez les identifiants correspondants au profil dans ~/.aws/credentials :

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

Utilisez ensuite n'importe quelle commande S3 avec le profil :

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

Gestion des buckets

AWS S3 utilise un espace unique et globalement unique de noms de buckets, et les SDK s’attendent à ce qu’un nom de bucket soit une simple chaîne de caractères sans /. Les buckets Hugging Face sont en revanche identifiés sous la forme namespace/bucket, où le namespace correspond à votre nom d’utilisateur ou à votre organisation. Ce niveau supplémentaire crée un désaccord avec les clients S3 — beaucoup n’acceptent pas de / dans un nom de bucket, ou l’échappent incorrectement dans l’URL. Il existe deux façons de contourner ce problème :

1. Placer l’espace de noms dans l’URL du point de terminaison (recommandé dans la plupart des cas). Cela limite chaque opération à cet espace de noms, de sorte que le nom du seau transmis au client est simplement le nom du seau HF. Cela fonctionne bien pour vos propres seaux ou pour les seaux d’une seule organisation, mais cela échoue entre les espaces de noms — par exemple, une copie côté serveur d’un seau personnel vers un seau d’organisation.

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

2. Traiter l'espace de noms comme le seau et préfixer la clé d'objet avec le nom du seau HF. Cela fonctionne pour les opérations au niveau des objets (téléversements, téléchargements) mais pose des problèmes pour les opérations au niveau du seau, telles que la création ou la suppression de seaux.

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

Limites et différences par rapport à AWS S3

Étant donné que les Storage Buckets ne modélisent pas tous les concepts S3, certains comportements diffèrent ou ne sont pas pris en charge.

Téléchargements d'objets

La passerelle est actuellement mono-région. Pour améliorer les performances de téléchargement, GetObject répond généralement par une redirection HTTP 302 vers le bord du CDN Hugging Face le plus proche, plutôt que de servir les octets directement.

Certains SDK ne suivent pas les redirections depuis un point d’accès S3. Le gateway détecte donc les clients qui s’identifient comme aws-cli, botocore (ce qui couvre boto3) ou aws-sdk-rust et leur transmet les données par lui-même. Tous les autres clients (rclone, s5cmd, curl, le SDK AWS Go, etc.) reçoivent la réponse 302 et la suivent nativement, ce qui permet d’exclure le gateway du chemin de données pour des téléchargements plus rapides.

Nommage des clés d'objets

Les clés des objets du bucket sont plus restreintes que sur S3. Une clé ne doit pas :

• commence ou se termine par /
• contient des barres obliques consécutives (//)
• contenir des séquences ../
• commence par ./
• se termine par ..
• contient des barres obliques inverses (\) ou des octets nuls (\0)

ListObjects

• ListObjectsV1 n'est pas pris en charge — utilisez ListObjectsV2. Notez que certains clients (comme rclone) peuvent nécessiter d'être configurés pour utiliser exclusivement ListObjectsV2.
• Seul / est autorisé comme délimiteur.

Autres différences d'API

• Métadonnées d’objet : les métadonnées utilisateur arbitraires (x-amz-meta-*) ne sont ni stockées ni renvoyées. Content-Type est pris en charge.
• Fonctionnalités non prises en charge : les ACL, les politiques de bucket, le balisage d'objets, le versionnage d'objets, les règles de cycle de vie, le chiffrement côté serveur (SSE) et les notifications de bucket ne sont pas pris en charge. Les objets sont toujours signalés avec la classe de stockage STANDARD. Les en-têtes et paramètres de requête associés sont acceptés mais ignorés.
• CopyObject : la copie côté serveur ne fonctionne que dans un seul espace de noms. La copie entre espaces de noms et UploadPartCopy (copie d’une partie d’un objet existant vers un téléchargement multipart) ne sont pas prises en charge.
• Requêtes conditionnelles : les préconditions If-Match / If-None-Match sont respectées pour PutObject et pour la source de copie de CopyObject, mais pas pour GetObject.
• Expiration des téléversements multipart : les téléversements multipart en cours qui ne sont jamais terminés ni annulés expirent et sont nettoyés automatiquement après 7 jours.

Exemples

Recettes concrètes pour des tâches courantes. Chacune s'appuie sur la configuration du client ci-dessus.

Lecture et écriture avec boto3

boto3 fonctionne avec la passerelle grâce aux paramètres client ci-dessus. Remplacez <namespace> par votre nom d’utilisateur ou votre organisation :

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")

Interroger un bucket avec DuckDB

Sur DuckDB 2.0 ou ultérieur, l'extension httpfs lit directement les chemins hf://buckets/, et avec l'extension hf, elle peut également écrire dans Buckets. Voir Interroger avec DuckDB.

Pour les versions antérieures de DuckDB, ou pour écrire les résultats d’une requête dans un bucket avec COPY ... TO sans l’extension, passez plutôt par la passerelle 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' est requis. Sans cela, DuckDB utilise l’adressage en style hôte virtuel (my-bucket.s3.hf.co), que la passerelle ne prend pas en charge — vous verrez une erreur « Could not resolve hostname ».

Importer des données à l'aide de rclone

rclone est un moyen pratique de copier des données entre deux magasins compatibles S3, ce qui en fait un bon choix pour déplacer un bucket AWS S3 existant (ou toute source compatible S3) vers un Storage Bucket.

Vous déplacez un grand jeu de données ? Le montage de la source et l’exécution de hf sync effectuent la déduplication côté client, ce qui permet généralement de téléverser moins d’octets qu’avec rclone. Consultez le Guide de migration.

L’idée est de déclarer deux distants — votre bucket source et la passerelle Hugging Face — et de laisser rclone diffuser les objets entre eux. Ajoutez les deux distants à ~/.config/rclone/rclone.conf. Le premier pointe vers votre bucket S3 existant ; ajustez-le pour qu’il corresponde à votre source (ici, AWS S3 simple) :

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

Le second pointe vers la passerelle Hugging Face. Comme pour tout autre client, restreignez le point de terminaison à votre espace de noms, utilisez l’adressage par path, forcez ListObjectsV2 (la seule version de liste prise en charge par la passerelle) et définissez une taille de partie de 256 Mo. C’est beaucoup plus grand que la valeur par défaut de 5 Mo de rclone, de sorte que les gros fichiers sont envoyés en moins de parties, tout en restant suffisamment petits pour que la passerelle les traite efficacement et que la mémoire de rclone reste sous contrôle (il conserve 4 parties par transfert en mémoire) :

[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 = 256M
chunk_size = 256M

Note : remplacez le <namespace> ci-dessus par le nom d'utilisateur ou l'organisation dans laquelle vos buckets sont stockés, et utilisez les identifiants S3 générés à partir de votre jeton d'accès. Le bucket de destination doit déjà exister sous cet espace de noms.

Copiez maintenant un bucket source dans votre bucket de stockage :

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

rclone copy ne transfère que les objets manquants ou modifiés à la destination, ce qui permet de relancer la commande en toute sécurité pour reprendre une importation interrompue ou récupérer de nouveaux objets. Pour faire de la destination un miroir exact de la source — en supprimant les objets de la destination qui n’existent plus à la source — utilisez plutôt rclone sync :

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

Pour les importations volumineuses, ajoutez --transfers et --checkers pour augmenter la concurrence (par exemple --transfers 16 --checkers 16), puis exécutez rclone check aws:my-source-bucket hf:my-bucket par la suite pour vous assurer que tous les objets ont bien été transférés.

Données de version avec DVC

DVC versionne les jeux de données et les modèles dans git en conservant de petits fichiers pointeurs dans le dépôt et en poussant les données réelles vers un distant. Un bucket agit comme un distant DVC via la passerelle, de sorte que votre code et vos pointeurs .dvc restent dans git tandis que les données résident dans votre bucket. Installez DVC avec le support S3 (pip install 'dvc[s3]'), puis ajoutez le distant en utilisant les paramètres du client ci-dessus :

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

Transmettez les identifiants S3 via l’environnement, ou avec dvc remote modify --local afin qu’ils ne soient pas stockés dans git :

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

Puis suivez, poussez et tirez comme d’habitude — dvc push téléverse vers le bucket, et dvc pull sur un clone neuf le télécharge à nouveau :

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

Utilisez votre namespace dans endpointurl et le nom du bucket brut dans l’URL s3://.