Images de conteneur

Les images conteneur sont un type de dépôt sur le Hugging Face Hub destiné aux images Docker et autres images OCI. Le registre de conteneurs Hugging Face, cr.hf.co, stocke les images sur le backend de stockage Xet. Poussez-les et tirez-les avec hf image, le client recommandé ; les clients standard tels que Docker, Podman, crane, skopeo, ORAS et Helm fonctionnent également.

Les images conteneur sont en bêta privée : contactez-nous pour les activer pour votre organisation.

Créer un dépôt

Accédez à huggingface.co/new-container et choisissez l’organisation, un nom et la visibilité. Ou utilisez l’API :

curl -X POST https://huggingface.co/api/containers/my-org/my-app \
  -H "Authorization: Bearer $HF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"private": true}'

Créez le dépôt avant de pousser : une tentative de push vers un dépôt inexistant échoue avec NAME_UNKNOWN. Sa page, https://huggingface.co/containers/my-org/my-app, répertorie ses tags. Les droits de pull et de push suivent la visibilité du dépôt et le rôle de chaque membre au sein de l’organisation.

Pousser et tirer avec hf image

hf image, une extension de l’interface en ligne de commande hf, ne transfère que les parties de chaque couche qui ont changé par rapport à la version précédente, ce qui offre une expérience plus rapide par rapport à d’autres clients OCI.

hf extensions install hf-image
hf auth login                                   # or set HF_TOKEN
hf image build -t cr.hf.co/my-org/my-app:v2 .   # optional: docker build works too
hf image push cr.hf.co/my-org/my-app:v2
hf image pull cr.hf.co/my-org/my-app:v2

Il utilise votre jeton d’accès utilisateur Hugging Face (read pour récupérer, write pour pousser) et nécessite Docker avec le magasin d’images containerd. Les images poussées avec hf image peuvent être récupérées par n’importe quel client.

Comme hf image stocke les couches non compressées, les images qu’il pousse reçoivent des digests différents de ceux obtenus avec docker push. Pour conserver les digests de docker push, par exemple pour des signatures ou des déploiements épinglés par digest, utilisez hf image push --preserve-digests. C’est plus lent : les couches modifiées sont alors poussées et tirées en entier, comme avec docker push.

Utiliser Docker et d'autres clients OCI

Bien que nous recommandions d’utiliser hf image (voir la section précédente) pour tirer pleinement parti du backend Xet, vous pouvez également interagir avec le registre via n’importe quel client OCI.

Connectez-vous avec votre nom d'utilisateur Hugging Face et un User Access Token en tant que mot de passe : read pour tirer, write pour pousser. Les images publiques peuvent être tirées sans connexion.

echo $HF_TOKEN | docker login cr.hf.co -u <username> --password-stdin
docker tag my-app cr.hf.co/my-org/my-app:v1
docker push cr.hf.co/my-org/my-app:v1
docker pull cr.hf.co/my-org/my-app:v1

Les autres clients OCI fonctionnent de la même manière. Helm ajoute le nom du graphique à l’URL : helm push mychart-0.1.0.tgz oci://cr.hf.co/my-org pousse vers my-org/mychart, qui doit exister au préalable.

Suppression d'images

Sur le Hub, supprimez un tag à l’aide de Supprimer ce tag dans son menu, sur la page de l’image ou du tag. Avec hf image, supprimez les tags d’une image, puis supprimez-la par digest :

hf image untag cr.hf.co/my-org/my-app:v1                # prints the image's digest
hf image delete cr.hf.co/my-org/my-app@sha256:<digest>

Si quelque chose référence encore l’image, comme un autre tag, la suppression est refusée et énumère ce qu’il faut d’abord supprimer. La suppression d’une image multi-arch supprime également ses images de plateforme.

Collecte des ordures

Le registre supprime les images auxquelles aucun tag ne pointe plus, directement ou via une image multi-arch, comme l’ancienne latest après un nouveau push. Il supprime également les couches qu’aucune image restante n’utilise. Pour continuer à tirer une image par digest, conservez un tag dessus.

Limites

• Les noms d’images sont cr.hf.co/<namespace>/<name>, en minuscules.
• Calques jusqu'à 100 Go, manifestes jusqu'à 4 Mio.
• L’affichage d’une nouvelle étiquette dans les listes d’étiquettes peut prendre quelques secondes.