Démarrer avec les dépôts

Ce guide, accessible aux débutants, vous aidera à acquérir les compétences de base nécessaires pour créer et gérer votre dépôt sur le Hub. Chaque section s’appuie sur la précédente, n’hésitez donc pas à choisir votre point de départ !

Prérequis

Ce document montre comment gérer les dépôts via l’interface web ainsi que via le terminal. Aucune exigence n’est requise si vous travaillez avec l’interface utilisateur. Si vous souhaitez travailler avec le terminal, veuillez suivre ces instructions d’installation.

Si git n'est pas encore disponible en tant que commande CLI, vous devrez installer Git pour votre plateforme. Vous devrez également installer Git-Xet, qui sera utilisé pour gérer les fichiers volumineux tels que les images et les poids des modèles.

Pour pouvoir télécharger et téléverser de gros fichiers depuis Git, vous devez installer l'extension Git Xet.

Pour pouvoir pousser votre code sur le Hub, vous devez vous authentifier d’une manière ou d’une autre. La méthode la plus simple consiste à installer le hf CLI et à exécuter la commande de connexion :

# Install hf:
#   brew install hf
#   or
#   pip install hf
hf auth login

Le contenu de la section Prise en main de ce document est également disponible en vidéo !

Créer un dépôt

Grâce à l’interface web du Hub, vous pouvez facilement créer des dépôts, ajouter des fichiers (même de grande taille !), explorer des modèles, visualiser des différences, et bien plus encore. Il existe trois types de dépôts sur le Hub, et dans ce guide, vous allez créer un dépôt de modèle à des fins de démonstration. Pour des informations sur la création et la gestion des modèles, des jeux de données et des Spaces, consultez leur documentation respective.

1. Pour créer un nouveau dépôt, visitez huggingface.co/new :

2. Spécifiez le propriétaire du dépôt : il peut s’agir de vous ou de l’une des organisations auxquelles vous êtes affilié.

3. Saisissez le nom de votre modèle. Ce sera également le nom du dépôt.

4. Précisez si vous souhaitez que votre modèle soit public ou privé.

5. Spécifiez la licence. Vous pouvez laisser le champ License vide pour le moment. Pour en savoir plus sur les licences, consultez la documentation Licenses.

Après avoir créé votre dépôt de modèle, vous devriez voir une page semblable à celle-ci :

Notez que le Hub vous invite à créer une Model Card, dont vous pouvez découvrir les détails dans la documentation des Model Cards. Inclure une Model Card dans votre dépôt de modèle est une bonne pratique, mais comme nous ne créons pour l'instant qu'un dépôt de test, nous pouvons passer cette étape.

Ajouter des fichiers à un dépôt (interface web)

Pour ajouter des fichiers à votre dépôt via l’interface web, commencez par sélectionner l’onglet Fichiers, accédez au répertoire souhaité, puis cliquez sur Ajouter un fichier. Vous aurez alors la possibilité de créer un nouveau fichier ou de téléverser un fichier directement depuis votre ordinateur.

Créer un nouveau fichier

Choisir de créer un nouveau fichier vous amène à l’écran d’éditeur suivant, où vous pouvez choisir un nom pour votre fichier, ajouter du contenu et enregistrer votre fichier avec un message qui résume vos modifications. Au lieu de committer directement le nouveau fichier sur la branche main de votre dépôt, vous pouvez sélectionner Open as a pull request pour créer une Pull Request.

Téléversement d'un fichier

Si vous choisissez Téléverser un fichier, vous pourrez sélectionner un fichier local à téléverser, accompagné d’un message résumant vos modifications apportées au dépôt.

Comme lors de la création de nouveaux fichiers, vous pouvez sélectionner Open as a pull request pour créer une Pull Request plutôt que d'ajouter vos modifications directement à la branche main de votre dépôt.

Ajouter des fichiers à un dépôt (CLI)

Vous pouvez téléverser des fichiers dans votre dépôt directement depuis le terminal à l’aide de l’interface en ligne de commande hf. Utilisez la commande hf upload pour envoyer des fichiers locaux ou des dossiers entiers :

# Upload a single file to your model repo
hf upload your-username/your-model-name model.safetensors

# Upload an entire directory
hf upload your-username/your-model-name ./my-model-directory

# Upload to a dataset repo
hf upload your-username/your-dataset-name ./data --repo-type dataset

La CLI hf gère automatiquement les fichiers volumineux — aucune configuration supplémentaire n'est requise.

Ajouter des fichiers à un dépôt (git)

Clonage des dépôts

Télécharger des dépôts sur votre machine locale est appelé clonage. Vous pouvez utiliser les commandes suivantes pour charger votre dépôt et y naviguer :

git clone https://huggingface.co/<your-username>/<your-model-name>
cd <your-model-name>

Ou pour un dépôt de jeu de données :

git clone https://huggingface.co/datasets/<your-username>/<your-dataset-name>
cd <your-dataset-name>

Vous pouvez cloner via SSH avec la commande suivante :

git clone git@hf.co:<your-username>/<your-model-name>
cd <your-model-name>

Vous devrez ajouter votre clé publique SSH à vos paramètres utilisateur pour pousser des modifications ou accéder aux dépôts privés.

Configuration

C’est le moment, vous pouvez ajouter tous les fichiers que vous voulez au dépôt ! 🔥

Avez-vous des fichiers de plus de 10 Mo ? Ces fichiers doivent être suivis avec git-xet, que vous pouvez initialiser avec :

git xet install

Lorsque vous utilisez Hugging Face pour créer un dépôt, Hugging Face fournit automatiquement une liste des extensions de fichiers courantes pour les gros fichiers de Machine Learning dans le fichier .gitattributes, que git-xet utilise pour suivre efficacement les modifications apportées à vos gros fichiers. Toutefois, vous devrez peut-être ajouter de nouvelles extensions si vos types de fichiers ne sont pas déjà gérés. Vous pouvez le faire avec git xet track "*.your_extension".

Pousser des fichiers

Vous pouvez utiliser Git pour enregistrer de nouveaux fichiers ainsi que toute modification apportée à des fichiers existants sous forme d’un ensemble de modifications appelé commit, que l’on peut considérer comme une « révision » de votre projet. Pour créer un commit, vous devez add les fichiers afin d’indiquer à Git que nous prévoyons d’enregistrer les modifications, puis commit ces modifications. Pour synchroniser le nouveau commit avec le Hugging Face Hub, vous devez ensuite push le commit vers le Hub.

# Create any files you like! Then...
git add .
git commit -m "First model version"  # You can choose any descriptive message
git push

Et c’est terminé ! Vous pouvez consulter votre dépôt sur Hugging Face avec tous les fichiers récemment ajoutés. Par exemple, dans la capture d’écran ci-dessous, l’utilisateur a ajouté un certain nombre de fichiers. Notez que certains fichiers de cet exemple ont une taille de 1.04 GB, le dépôt utilise donc Xet pour les suivre.

Si vous avez cloné le dépôt via HTTP, il est possible que l’on vous demande de saisir votre nom d’utilisateur et votre mot de passe à chaque opération de push. La méthode la plus simple pour éviter cette répétition est de passer à SSH plutôt qu’à HTTP. Sinon, si vous devez utiliser HTTP, il peut être utile de configurer un git credential helper pour préremplir automatiquement votre nom d’utilisateur et votre mot de passe.

Afficher l’historique d’un dépôt

Chaque fois que vous effectuez le cycle add-commit-push, le dépôt conserve la trace de toutes les modifications apportées à vos fichiers. L’interface utilisateur vous permet d’explorer les fichiers du modèle et les commits, et de visualiser la différence (également appelée diff) introduite par chaque commit. Pour consulter l’historique, vous pouvez cliquer sur le lien History: X commits.

Vous pouvez cliquer sur un commit individuel pour voir les modifications introduites par ce commit :