Créer et gérer un dépôt

Le Hugging Face Hub est une collection de dépôts git. Git est un outil largement utilisé dans le développement logiciel pour versionner facilement les projets lors d’un travail collaboratif. Ce guide vous montre comment interagir avec les dépôts du Hub, notamment :

• Créer et supprimer un dépôt.
• Gérer les branches et les étiquettes.
• Renommez votre dépôt.
• Mettez à jour la visibilité de votre dépôt.
• Gérer une copie locale de votre dépôt.

Si vous êtes habitué à travailler avec des plateformes telles que GitLab/GitHub/Bitbucket, votre premier réflexe sera probablement d’utiliser l’interface en ligne de commande git pour cloner votre dépôt (git clone), enregistrer les modifications (git add, git commit) et les pousser (git push). Cette approche est valide sur le Hugging Face Hub. Cependant, le génie logiciel et l’apprentissage automatique n’ont pas les mêmes exigences ni les mêmes flux de travail. Les dépôts de modèles peuvent contenir de gros fichiers de poids pour différents frameworks et outils, ce qui peut entraîner le maintien de dossiers locaux volumineux. Par conséquent, il peut être plus efficace d’utiliser nos méthodes HTTP personnalisées. Vous pouvez consulter notre page d’explication Paradigme Git vs HTTP pour plus de détails.

Si vous souhaitez créer et gérer un dépôt sur le Hub, votre machine doit être connectée. Si ce n'est pas le cas, veuillez consulter cette section. Dans la suite de ce guide, nous supposerons que votre machine est connectée.

Lister vos dépôts

Vous pouvez lister tous les dépôts (modèles, jeux de données, espaces et buckets) de votre compte ou d’une organisation à l’aide de list_user_repos(). Les résultats incluent des informations de stockage et sont triés par utilisation du stockage.

>>> from huggingface_hub import list_user_repos

# List repos for the authenticated user
>>> repos = list(list_user_repos())
>>> for repo in repos[:3]:
...     print(f"{repo.id} ({repo.type}) - {repo.storage} bytes")
username/my-model (model) - 4828692480 bytes
username/my-dataset (dataset) - 598427559 bytes
username/my-space (space) - 120620146 bytes

# List repos from an organization
>>> repos = list(list_user_repos(namespace="my-org"))

Ou via l'interface en ligne de commande (affiche 30 dépôts par défaut, utilisez --limit 0 pour les lister tous) :

>>> hf repos ls
>>> hf repos ls --namespace my-org --type model
>>> hf repos ls --limit 0 --format json | jq '.[].id'

Création et suppression de dépôts

La première étape consiste à savoir comment créer et supprimer des dépôts. Vous ne pouvez gérer que les dépôts que vous possédez (sous votre espace de noms d'utilisateur) ou ceux d'organisations pour lesquelles vous disposez de droits d'écriture.

Créer un dépôt

Créez un dépôt vide avec create_repo() et donnez-lui un nom avec le paramètre repo_id. Le repo_id est votre espace de noms suivi du nom du dépôt : username_or_org/repo_name.

>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-model")
'https://huggingface.co/lysandre/test-model'

Ou via l'interface en ligne de commande :

>>> hf repos create lysandre/test-model
Successfully created lysandre/test-model on the Hub.
Your repo is now available at https://huggingface.co/lysandre/test-model

Par défaut, create_repo() crée un dépôt de modèle. Mais vous pouvez utiliser le paramètre repo_type pour spécifier un autre type de dépôt. Par exemple, si vous souhaitez créer un dépôt de jeu de données :

>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-dataset", repo_type="dataset")
'https://huggingface.co/datasets/lysandre/test-dataset'

Ou via l'interface en ligne de commande :

>>> hf repos create lysandre/test-dataset --repo-type dataset

Lors de la création d'un dépôt, vous pouvez définir la visibilité de votre dépôt avec le paramètre visibility :

>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-private", visibility="private")

Ou via l'interface en ligne de commande :

>>> hf repos create lysandre/test-private --private

Si vous souhaitez modifier la visibilité du dépôt à un moment ultérieur, vous pouvez utiliser la fonction update_repo_settings().

Si vous faites partie d’une organisation disposant d’un plan Enterprise, vous pouvez créer un dépôt dans un groupe de ressources spécifique en passant resource_group_id en paramètre à create_repo(). Les groupes de ressources sont une fonctionnalité de sécurité permettant de contrôler quels membres de votre organisation peuvent accéder à une ressource donnée. Vous pouvez obtenir l’identifiant du groupe de ressources en le copiant depuis l’URL de la page de paramètres de votre organisation sur le Hub (par exemple "https://huggingface.co/organizations/huggingface/settings/resource-groups/66670e5163145ca562cb1988" => "66670e5163145ca562cb1988"). Pour plus de détails sur les groupes de ressources, consultez ce guide.

Vous pouvez également créer un dépôt dans une région cloud spécifique en passant region en tant que paramètre :

>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-model", region="us")

Supprimer un dépôt

Supprimez un dépôt avec delete_repo(). Assurez-vous de vouloir supprimer un dépôt car il s'agit d'un processus irréversible !

Spécifiez le repo_id du dépôt que vous souhaitez supprimer :

>>> delete_repo(repo_id="lysandre/my-corrupted-dataset", repo_type="dataset")

Passez missing_ok=True pour ignorer silencieusement l’appel si le dépôt n’existe pas :

>>> delete_repo(repo_id="lysandre/my-corrupted-dataset", repo_type="dataset", missing_ok=True)

Ou via l'interface en ligne de commande :

>>> hf repos delete lysandre/my-corrupted-dataset --repo-type dataset

Dupliquer un dépôt

Dans certains cas, vous souhaitez copier le dépôt d’une autre personne pour l’adapter à votre cas d’usage. Cela est possible à l’aide de la méthode duplicate_repo(). Elle duplique l’intégralité du dépôt, en conservant l’historique git complet. Cela fonctionne pour les modèles, les jeux de données et les Spaces. Pour les Spaces, vous devrez toujours configurer vos propres paramètres (matériel, temps de veille, stockage, variables et secrets). Consultez notre guide Gérer votre Space pour plus de détails.

>>> from huggingface_hub import duplicate_repo

# Duplicate a Space
>>> duplicate_repo("multimodalart/dreambooth-training", repo_type="space", private=False)
RepoUrl('https://huggingface.co/spaces/nateraw/dreambooth-training',...)

# Duplicate a dataset
>>> duplicate_repo("openai/gdpval", repo_type="dataset")
RepoUrl('https://huggingface.co/datasets/nateraw/gdpval',...)

Comme create_repo(), duplicate_repo() accepte un resource_group_id pour créer la copie directement dans un groupe de ressources de votre organisation Enterprise (--resource-group-id avec hf repos duplicate).

L’historique git est copié immédiatement, mais les fichiers LFS/Xet peuvent encore être copiés en arrière-plan une fois que duplicate_repo() a retourné. Jusqu’à la fin de la copie, le téléchargement de ces fichiers depuis le nouveau dépôt peut échouer. Vérifiez files_copy_pending sur la valeur retournée pour savoir si la copie est toujours en cours :

>>> from huggingface_hub import duplicate_repo
>>> repo_url = duplicate_repo("openai/gdpval", repo_type="dataset")
>>> repo_url.files_copy_pending
True

Rechercher des Spaces

Le Hub fournit une API de recherche sémantique pour découvrir des Spaces. Vous pouvez effectuer des recherches à l'aide de requêtes en langage naturel avec search_spaces() :

>>> from huggingface_hub import search_spaces
>>> results = list(search_spaces("generate image"))
>>> results[0].id
'mrfakename/Z-Image-Turbo'

Pour plus de détails et d'options de filtrage, consultez le guide Gérer vos Spaces.

Téléverser et télécharger des fichiers

Maintenant que vous avez créé votre dépôt, vous souhaitez y pousser des modifications et y télécharger des fichiers.

Ces deux sujets méritent chacun leur propre guide. Veuillez consulter les guides téléversement et téléchargement pour apprendre à utiliser votre dépôt.

Copier les fichiers

Utilisez copy_files() pour copier des fichiers déjà hébergés sur le Hub d’un dépôt à un autre (ou même au sein du même dépôt) sans les télécharger ni les réenvoyer. Les fichiers individuels et les dossiers entiers sont pris en charge, et les fichiers suivis par Xet ou LFS sont copiés côté serveur par hachage.

>>> from huggingface_hub import copy_files

# Copy a single file from one repo to another
>>> copy_files(
...     "hf://username/source-model/config.json",
...     "hf://username/dest-model/config.json",
... )

# Copy an entire folder (a trailing "/" copies the folder *contents*, rsync-style)
>>> copy_files(
...     "hf://datasets/username/my-dataset/data/",
...     "hf://datasets/username/my-dataset-copy/data/",
... )

Ou via l’interface en ligne de commande, avec la commande unifiée hf cp (également disponible sous la forme hf repos cp) :

# Copy a single file between repositories
>>> hf cp hf://username/source-model/config.json hf://username/dest-model/config.json

# Copy a file from a repo to your local machine
>>> hf repos cp hf://username/my-model/config.json ./config.json

# Upload a local file to a repository
>>> hf repos cp ./model.safetensors hf://username/my-model/model.safetensors

copy_files (et hf cp) peut également copier des fichiers d’un dépôt vers un Bucket. La copie depuis un bucket vers un dépôt n’est pas prise en charge. Consultez le guide Buckets pour plus de détails.

Les copies côté serveur ne fonctionnent que dans la même zone de stockage.

Branches and tags

Les dépôts Git utilisent souvent des branches pour stocker différentes versions d'un même dépôt. Les étiquettes peuvent également être utilisées pour marquer un état spécifique de votre dépôt, par exemple lors de la publication d'une version. De manière plus générale, les branches et les étiquettes sont désignées sous le terme de références git.

Créer des branches et des étiquettes

Vous pouvez créer de nouvelles branches et étiquettes à l'aide de create_branch() et create_tag() :

>>> from huggingface_hub import create_branch, create_tag

# Create a branch on a Space repo from `main` branch
>>> create_branch("Matthijs/speecht5-tts-demo", repo_type="space", branch="handle-dog-speaker")

# Create a tag on a Dataset repo from `v0.1-release` branch
>>> create_tag("bigcode/the-stack", repo_type="dataset", revision="v0.1-release", tag="v0.1.1", tag_message="Bump release version.")

Ou via l'interface en ligne de commande :

>>> hf repos branch create Matthijs/speecht5-tts-demo handle-dog-speaker --repo-type space
>>> hf repos tag create bigcode/the-stack v0.1.1 --repo-type dataset --revision v0.1-release -m "Bump release version."

Vous pouvez utiliser les fonctions delete_branch() et delete_tag() de la même manière pour supprimer une branche ou un tag, ou hf repos branch delete et hf repos tag delete respectivement dans le CLI.

Lister toutes les branches et les étiquettes

Vous pouvez également lister les références git existantes d’un dépôt à l’aide de list_repo_refs() :

>>> from huggingface_hub import list_repo_refs
>>> list_repo_refs("bigcode/the-stack", repo_type="dataset")
GitRefs(
   branches=[
         GitRefInfo(name='main', ref='refs/heads/main', target_commit='18edc1591d9ce72aa82f56c4431b3c969b210ae3'),
         GitRefInfo(name='v1.1.a1', ref='refs/heads/v1.1.a1', target_commit='f9826b862d1567f3822d3d25649b0d6d22ace714')
   ],
   converts=[],
   tags=[
         GitRefInfo(name='v1.0', ref='refs/tags/v1.0', target_commit='c37a8cd1e382064d8aced5e05543c5f7753834da')
   ]
)

Modifier les paramètres du dépôt

Les dépôts sont dotés de certains paramètres que vous pouvez configurer. Dans la plupart des cas, vous le ferez manuellement sur la page des paramètres du dépôt dans votre navigateur. Vous devez disposer d'un accès en écriture à un dépôt pour le configurer (soit vous en êtes le propriétaire, soit vous faites partie d'une organisation). Dans cette section, nous verrons les paramètres que vous pouvez également configurer de manière programmatique à l'aide de huggingface_hub.

Certains paramètres sont spécifiques aux Spaces (matériel, variables d’environnement, …). Pour les configurer, veuillez consulter notre guide Gérer vos Spaces.

Mettre à jour la visibilité

Un dépôt peut être public ou privé. Un dépôt privé n’est visible que par vous ou par les membres de l’organisation dans laquelle se trouve le dépôt. Passez un dépôt en privé comme indiqué ci-dessous :

>>> from huggingface_hub import update_repo_settings
>>> update_repo_settings(repo_id=repo_id, private=True)

Ou via l'interface en ligne de commande :

>>> hf repos settings lysandre/test-private --private true

Configurer l'accès contrôlé

Pour offrir un meilleur contrôle sur l’utilisation des dépôts, le Hub permet aux auteurs de dépôts d’activer les requêtes d’accès pour leurs dépôts. Lorsque cette option est activée, l’utilisateur doit accepter de partager ses coordonnées (nom d’utilisateur et adresse e-mail) avec les auteurs du dépôt afin d’accéder aux fichiers. Un dépôt pour lequel les requêtes d’accès sont activées est appelé dépôt à accès contrôlé.

Vous pouvez définir un dépôt comme restreint à l'aide de update_repo_settings() :

>>> from huggingface_hub import HfApi

>>> api = HfApi()
>>> api.update_repo_settings(repo_id=repo_id, gated="auto")  # Set automatic gating for a model

Ou via l'interface en ligne de commande :

>>> hf repos settings lysandre/test-private --gated auto

Renommer votre dépôt

Vous pouvez renommer votre dépôt sur le Hub à l'aide de move_repo(). Grâce à cette méthode, vous pouvez également déplacer le dépôt d'un utilisateur vers une organisation. Dans ce cas, il existe quelques limitations dont vous devez tenir compte. Par exemple, vous ne pouvez pas transférer votre dépôt à un autre utilisateur.

>>> from huggingface_hub import move_repo
>>> move_repo(from_id="Wauplin/cool-model", to_id="huggingface/cool-model")

Ou via l'interface en ligne de commande :

>>> hf repos move Wauplin/cool-model huggingface/cool-model

Dépôts de noyaux

Le Hub prend en charge un type de dépôt "kernel" pour l'hébergement de noyaux de calcul. Il ne s'agit pas d'un type de dépôt entièrement compatible. Un ensemble limité de méthodes a été testé et est officiellement pris en charge :

• kernel_info()
• hf_hub_download()
• snapshot_download()
• list_repo_refs()
• list_repo_files()
• list_repo_tree()

Notez que create_repo() et delete_repo() sont également compatibles, mais qu’ils sont restreints à un petit sous-ensemble d’utilisateurs et d’organisations autorisés sur le Hub.

Pour créer, publier et utiliser des dépôts de noyaux, veuillez utiliser le package dédié kernels à la place. Consultez la documentation Kernels pour plus de détails.