Partage de modèles pré-entraînés

Dans les étapes ci-dessous, nous allons examiner les moyens les plus simples de partager des modèles pré-entraînés sur le 🤗 Hub. Il existe des outils et des services disponibles qui permettent de simplifier le partage et la mise à jour des modèles directement sur le Hub, que nous allons explorer ci-dessous.

Nous encourageons tous les utilisateurs qui entraînent des modèles à contribuer en les partageant avec la communauté. Le partage des modèles, même s’ils ont été entraînés sur des jeux de données très spécifiques, aidera les autres, en leur faisant gagner du temps, des ressources de calcul et en leur donnant accès à des artefacts entraînés utiles. À votre tour, vous pourrez bénéficier du travail effectué par les autres !

Il y a trois façons de créer de nouveaux dépôts de modèles :

• en utilisant l’API push_to_hub,
• en utilisant la bibliothèque Python huggingface_hub,
• en utilisant l’interface web.

Une fois que vous avez créé un dépôt, vous pouvez y charger des fichiers via git et git-lfs. Nous allons vous guider dans la création de dépôts de modèles et le téléchargement de fichiers dans les sections suivantes.

Utilisation de l’API push_to_hub

La façon la plus simple de télécharger des fichiers vers le Hub est d’utiliser l’API push_to_hub.

Avant d’aller plus loin, vous devrez générer un jeton d’authentification afin que l’API huggingface_hub sache qui vous êtes et à quels espaces de noms vous avez accès en écriture. Assurez-vous que vous êtes dans un environnement où vous avez installé transformers (voir la Configuration). Si vous êtes dans un notebook, vous pouvez utiliser la fonction suivante pour vous connecter :

from huggingface_hub import notebook_login

notebook_login()

Dans un terminal, vous pouvez exécuter :

huggingface-cli login

Dans les deux cas, vous serez invité à saisir votre nom d’utilisateur et votre mot de passe, qui sont les mêmes que ceux que vous utilisez pour vous connecter au Hub. Si vous n’avez pas encore de profil pour le Hub, vous devez en créer un ici.

Super ! Votre jeton d’authentification est maintenant stocké dans votre dossier de cache. Créons quelques dépôts !

Si vous avez joué avec l’API Trainer pour entraîner un modèle, le moyen le plus simple de le télécharger sur le Hub est de définir push_to_hub=True lorsque vous définissez vos TrainingArguments :

from transformers import TrainingArguments

training_args = TrainingArguments(
    "bert-finetuned-mrpc", save_strategy="epoch", push_to_hub=True
)

Lorsque vous appelez trainer.train(), le Trainer téléchargera alors votre modèle vers le Hub à chaque fois qu’il sera sauvegardé (ici à chaque époque) dans un dépôt dans votre espace personnel. Ce dépôt sera nommé comme le répertoire de sortie que vous avez choisi (ici bert-finetuned-mrpc) mais vous pouvez choisir un nom différent avec hub_model_id = "a_different_name".

Pour télécharger votre modèle vers une organisation dont vous êtes membre, passez-le simplement avec hub_model_id = "my_organization/my_repo_name".

Une fois que votre entraînement est terminé, vous devriez faire un dernier trainer.push_to_hub() pour télécharger la dernière version de votre modèle. Cela générera également une carte pour le modèle avec toutes les métadonnées pertinentes, rapportant les hyperparamètres utilisés et les résultats d’évaluation ! Voici un exemple du contenu que vous pourriez trouver dans une telle carte de modèle :

A un niveau inférieur, l’accès au Hub peut être fait directement sur les modèles, les tokenizers et les objets de configuration via leur méthode push_to_hub(). Cette méthode s’occupe à la fois de la création du dépôt et de l’envoi les fichiers du modèle et du tokenizer directement dans le dépôt. Aucune manipulation manuelle n’est nécessaire, contrairement à l’API que nous verrons plus loin.

Pour avoir une idée de son fonctionnement, commençons par initialiser un modèle et un tokenizer :

from transformers import AutoModelForMaskedLM, AutoTokenizer

checkpoint = "camembert-base"

model = AutoModelForMaskedLM.from_pretrained(checkpoint)
tokenizer = AutoTokenizer.from_pretrained(checkpoint)

Vous êtes libre de faire ce que vous voulez avec ces objets : ajouter des tokens au tokenizer, entraîner le modèle, le finetuner. Une fois que vous êtes satisfait du modèle, des poids et du tokenizer obtenus, vous pouvez utiliser la méthode push_to_hub() directement disponible sur l’objet model :

model.push_to_hub("dummy-model")

Cela va créer le nouveau dépôt dummy-model dans votre profil et le remplir avec les fichiers du modèle. Faites la même chose avec le tokenizer, de sorte que tous les fichiers sont maintenant disponibles dans ce dépôt :

tokenizer.push_to_hub("dummy-model")

Si vous appartenez à une organisation, il suffit de spécifier l’argument organization pour télécharger dans l’espace de cette organisation :

tokenizer.push_to_hub("dummy-model", organization="huggingface")

Si vous souhaitez utiliser un jeton Hugging Face spécifique, vous pouvez également le spécifier à la méthode push_to_hub() :

tokenizer.push_to_hub("dummy-model", organization="huggingface", use_auth_token="<TOKEN>")

Maintenant, dirigez-vous sur Hub pour trouver votre modèle nouvellement téléchargé : https://huggingface.co./user-or-organization/dummy-model.

Cliquez sur l’onglet « Fichiers et versions » et vous devriez voir les fichiers visibles dans la capture d’écran suivante :

Comme vous l’avez vu, la méthode push_to_hub() accepte plusieurs arguments, ce qui permet de télécharger vers un dépôt ou un espace d’organisation spécifique, ou d’utiliser un jeton d’API différent. Nous vous recommandons de jeter un coup d’œil à la spécification de la méthode disponible directement dans la documentation de 🤗 Transformers pour avoir une idée de ce qui est possible.

La méthode push_to_hub() est soutenue par le package Python huggingface_hub, qui offre une API directe au Hub. C’est intégré à 🤗 Transformers et à plusieurs autres bibliothèques d’apprentissage automatique, comme allenlp. Bien que nous nous concentrions sur l’intégration via 🤗 Transformers dans ce chapitre, son intégration dans votre propre code ou bibliothèque est simple.

Passez à la dernière section pour voir comment télécharger des fichiers dans votre dépôt nouvellement créé !

Utilisation de la bibliothèque Python huggingface_hub

La bibliothèque Python huggingface_hub est un package qui offre un ensemble d’outils pour les hubs des modèles et des jeux de données. Elle fournit des méthodes et des classes simples pour des tâches courantes telles qu’obtenir et gérer des informations à propos des dépôts sur le Hub. Elle fournit des APIs simples qui fonctionnent au-dessus de git pour gérer le contenu de ces dépôts et pour intégrer le Hub dans vos projets et bibliothèques.

De la même manière que pour l’utilisation de l’API push_to_hub, vous devrez avoir votre jeton d’API enregistré dans votre cache. Pour ce faire, vous devrez utiliser la commande login de la CLI, comme mentionné dans la section précédente (encore une fois, assurez-vous de faire précéder ces commandes du caractère ! si vous les exécutez dans Google Colab) :

huggingface-cli login

Le package huggingface_hub offre plusieurs méthodes et classes qui sont utiles pour notre objectif. Tout d’abord, il y a quelques méthodes pour gérer la création, la suppression des dépôts, et autres :

from huggingface_hub import (
    # Gestion des utilisateurs
    login,
    logout,
    whoami,

    # Création et gestion du dépôt
    create_repo,
    delete_repo,
    update_repo_visibility,

    # Et quelques méthodes pour récupérer/changer des informations sur le contenu
    list_models,
    list_datasets,
    list_metrics,
    list_repo_files,
    upload_file,
    delete_file,
)

De plus, elle offre la très puissante classe Repository pour gérer un dépôt local. Nous allons explorer ces méthodes et cette classe dans les prochaines sections pour comprendre comment les exploiter.

La méthode create_repo peut être utilisée pour créer un nouveau dépôt sur le Hub :

from huggingface_hub import create_repo

create_repo("dummy-model")

Ceci créera le dépôt dummy-model dans votre espace. Si vous le souhaitez, vous pouvez spécifier à quelle organisation le dépôt doit appartenir en utilisant l’argument organization :

from huggingface_hub import create_repo

create_repo("dummy-model", organization="huggingface")

Cela créera le dépôt dummy-model dans l’espace de nom huggingface, en supposant que vous appartenez à cette organisation. D’autres arguments qui peuvent être utiles sont :

• private, afin de spécifier si le dépôt doit être visible des autres ou non,
• token, si vous voulez remplacer le jeton stocké dans votre cache par un jeton donné,
• repo_type, si vous souhaitez créer un dataset ou un space au lieu d’un modèle. Les valeurs acceptées sont "dataset" et "space".

Une fois que le dépôt est créé, nous devons y ajouter des fichiers ! Passez à la section suivante pour voir les trois façons dont cela peut être géré.

Utilisation de l’interface web

L’interface web offre des outils pour gérer les dépôts directement dans le Hub. En utilisant l’interface, vous pouvez facilement créer des dépôts, ajouter des fichiers (même de grande taille !), explorer des modèles, visualiser les différences, et bien plus encore.

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

Tout d’abord, indiquez le propriétaire du dépôt : il peut s’agir de vous ou de l’une des organisations auxquelles vous êtes affilié. Si vous choisissez une organisation, le modèle sera présenté sur la page de l’organisation et chaque membre de l’organisation aura la possibilité de contribuer au dépôt.

Ensuite, saisissez le nom de votre modèle. Ce sera également le nom du dépôt. Enfin, vous pouvez préciser si vous souhaitez que votre modèle soit public ou privé. Les modèles privés sont cachés de la vue du public.

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

C’est là que votre modèle sera hébergé. Pour commencer à le remplir, vous pouvez ajouter un fichier README directement depuis l’interface web.

Le fichier README est en Markdown. N’hésitez pas à vous lâcher avec lui ! La troisième partie de ce chapitre est consacrée à la construction d’une carte de modèle. Celles-ci sont d’une importance capitale pour valoriser votre modèle, car c’est par elles que vous indiquez aux autres ce qu’il peut faire.

Si vous regardez l’onglet « Files and versions », vous verrez qu’il n’y a pas encore beaucoup de fichiers : juste le README.md que vous venez de créer et le fichier .gitattributes qui garde la trace des gros fichiers.

Nous allons maintenant voir comment ajouter de nouveaux fichiers.

Téléchargement des fichiers du modèle

Le système de gestion des fichiers sur le Hub est basé sur git pour les fichiers ordinaires et git-lfs (qui signifie Git Large File Storage) pour les fichiers plus importants.

Dans la section suivante, nous passons en revue trois façons différentes de télécharger des fichiers sur le Hub : par huggingface_hub et par des commandes git.

L’approche `upload_file’

L’utilisation de upload_file ne nécessite pas que git et git-lfs soient installés sur votre système. Il pousse les fichiers directement vers le 🤗 Hub en utilisant des requêtes HTTP POST. Une limitation de cette approche est qu’elle ne gère pas les fichiers dont la taille est supérieure à 5 Go. Si vos fichiers ont une taille supérieure à 5 Go, veuillez suivre les deux autres méthodes détaillées ci-dessous.

L’API peut être utilisée comme suit :

from huggingface_hub import upload_file

upload_file(
    "<path_to_file>/config.json",
    path_in_repo="config.json",
    repo_id="<namespace>/dummy-model",
)

Ceci téléchargera le fichier config.json disponible à <path_to_file> à la racine du dépôt en tant que config.json, vers le dépôt dummy-model. D’autres arguments qui peuvent être utiles sont :

• token, si vous souhaitez remplacer le jeton stocké dans votre cache par un jeton donné,
• repo_type, si vous souhaitez télécharger vers un dataset ou un space au lieu d’un modèle. Les valeurs acceptées sont "dataset" et "space".

La classe Repository

La classe Repository gère un dépôt local d’une manière similaire à git. Elle abstrait la plupart des problèmes que l’on peut rencontrer avec git pour fournir toutes les fonctionnalités dont nous avons besoin.

L’utilisation de cette classe nécessite l’installation de git et de git-lfs, donc assurez-vous que git-lfs est installé (voir ici pour les instructions d’installation) et configuré avant de commencer.

Afin de commencer à jouer avec le dépôt que nous venons de créer, nous pouvons commencer par l’initialiser dans un dossier local en clonant le dépôt distant :

from huggingface_hub import Repository

repo = Repository("<path_to_dummy_folder>", clone_from="<namespace>/dummy-model")

Cela a créé le dossier <path_to_dummy_folder> dans notre répertoire de travail. Ce dossier ne contient que le fichier .gitattributes car c’est le seul fichier créé lors de l’instanciation du dépôt par create_repo.

A partir de maintenant, nous pouvons utiliser plusieurs des méthodes traditionnelles de git :

repo.git_pull()
repo.git_add()
repo.git_commit()
repo.git_push()
repo.git_tag()

Et d’autres encore ! Nous vous recommandons de jeter un coup d’œil à la documentation de Repository disponible ici pour une vue d’ensemble de toutes les méthodes disponibles.

Actuellement, nous avons un modèle et un tokenizer que nous voulons pousser vers le Hub. Nous avons réussi à cloner le dépôt, nous pouvons donc enregistrer les fichiers dans ce dépôt.

Nous nous assurons d’abord que notre clone local est à jour en récupérant les dernières modifications :

repo.git_pull()

Une fois que c’est fait, nous sauvegardons les fichiers du modèle et du tokenizer :

model.save_pretrained("<path_to_dummy_folder>")
tokenizer.save_pretrained("<path_to_dummy_folder>")

Le <path_to_dummy_folder> contient maintenant tous les fichiers du modèle et du tokenizer. Nous suivons le flux de travail git habituel en ajoutant des fichiers à la zone de transit, en les validant et en les poussant vers le Hub :

repo.git_add()
repo.git_commit("Add model and tokenizer files")
repo.git_push()

Félicitations ! Vous venez de pousser vos premiers fichiers sur le Hub.

L’approche basée sur git

Il s’agit de l’approche la plus basique pour télécharger des fichiers : nous le ferons directement avec git et git-lfs. La plupart des difficultés sont abstraites par les approches précédentes, mais il y a quelques réserves avec la méthode suivante, nous allons donc suivre un cas d’utilisation plus complexe.

L’utilisation de cette classe nécessite l’installation de git et de git-lfs, donc assurez-vous d’avoir git-lfs installé et configuré avant de commencer.

Commencez par initialiser git-lfs :

git lfs install

Updated git hooks.
Git LFS initialized.

Une fois que c’est fait, la première étape consiste à cloner votre dépôt de modèles :

git clone https://huggingface.co./<namespace>/<your-model-id>

Mon nom d’utilisateur est lysandre et j’ai utilisé le nom de modèle dummy, donc pour moi la commande ressemble à ce qui suit :

git clone https://huggingface.co/lysandre/dummy

J’ai maintenant un dossier nommé dummy dans mon répertoire de travail. Je peux cd dans ce dossier et jeter un coup d’oeil à son contenu :

cd dummy && ls

README.md

Si vous venez de créer votre dépôt en utilisant la méthode create_repo du Hub, ce dossier devrait seulement contenir un fichier caché .gitattributes. Si vous avez suivi les instructions de la section précédente pour créer un dépôt en utilisant l’interface web, le dossier devrait contenir un seul fichier README.md à côté du fichier caché .gitattributes, comme indiqué ici.

L’ajout d’un fichier de taille normale, comme un fichier de configuration, un fichier de vocabulaire, ou tout autre fichier de moins de quelques mégaoctets, est fait exactement comme on le ferait dans n’importe quel système basé sur git. Cependant, les fichiers plus volumineux doivent être enregistrés via git-lfs afin de les pousser vers huggingface.co.

Revenons un peu à Python pour générer un modèle et un tokenizer que nous souhaitons « commiter » dans notre dépôt fictif :

from transformers import AutoModelForMaskedLM, AutoTokenizer

checkpoint = "camembert-base"

model = AutoModelForMaskedLM.from_pretrained(checkpoint)
tokenizer = AutoTokenizer.from_pretrained(checkpoint)

# Faites ce que vous voulez avec le modèle, entraînez-le, finetunez-le...

model.save_pretrained("<path_to_dummy_folder>")
tokenizer.save_pretrained("<path_to_dummy_folder>")

Maintenant que nous avons sauvegardé quelques artefacts de modèle et de tokenizer, regardons à nouveau le dossier dummy :

ls

config.json  pytorch_model.bin  README.md  sentencepiece.bpe.model  special_tokens_map.json tokenizer_config.json  tokenizer.json

Si vous regardez la taille des fichiers (par exemple, avec ls -lh), vous devriez voir que le fichier d’état du modèle (pytorch_model.bin) est la seule exception, avec plus de 400 Mo.

Nous pouvons maintenant aller de l’avant et procéder comme nous le ferions habituellement avec des dépôts Git traditionnels. Nous pouvons ajouter tous les fichiers à l’environnement Git en utilisant la commande git add :

git add .

Nous pouvons alors jeter un coup d’œil aux fichiers :

git status

On branch main
Your branch is up to date with 'origin/main'.

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
  modified:   .gitattributes
	new file:   config.json
	new file:   pytorch_model.bin
	new file:   sentencepiece.bpe.model
	new file:   special_tokens_map.json
	new file:   tokenizer.json
	new file:   tokenizer_config.json

De même, nous pouvons nous assurer que git-lfs suit les bons fichiers en utilisant sa commande status :

git lfs status

On branch main
Objects to be pushed to origin/main:


Objects to be committed:

	config.json (Git: bc20ff2)
	pytorch_model.bin (LFS: 35686c2)
	sentencepiece.bpe.model (LFS: 988bc5a)
	special_tokens_map.json (Git: cb23931)
	tokenizer.json (Git: 851ff3e)
	tokenizer_config.json (Git: f0f7783)

Objects not staged for commit:

Nous pouvons voir que tous les fichiers ont Git comme gestionnaire, sauf pytorch_model.bin et sentencepiece.bpe.model, qui ont LFS. Super !

Passons aux étapes finales, committing et pushing vers le dépôt distant huggingface.co :

git commit -m "First model version"

[main b08aab1] First model version
 7 files changed, 29027 insertions(+)
  6 files changed, 36 insertions(+)
 create mode 100644 config.json
 create mode 100644 pytorch_model.bin
 create mode 100644 sentencepiece.bpe.model
 create mode 100644 special_tokens_map.json
 create mode 100644 tokenizer.json
 create mode 100644 tokenizer_config.json

Le chargement peut prendre un peu de temps, en fonction de la vitesse de votre connexion Internet et de la taille de vos fichiers :

git push

Uploading LFS objects: 100% (1/1), 433 MB | 1.3 MB/s, done.
Enumerating objects: 11, done.
Counting objects: 100% (11/11), done.
Delta compression using up to 12 threads
Compressing objects: 100% (9/9), done.
Writing objects: 100% (9/9), 288.27 KiB | 6.27 MiB/s, done.
Total 9 (delta 1), reused 0 (delta 0), pack-reused 0
To https://huggingface.co./lysandre/dummy
   891b41d..b08aab1  main -> main

Si nous jetons un coup d’œil au dépôt du modèle, lorsque cette opération est terminée, nous pouvons voir tous les fichiers récemment ajoutés :

L’interface utilisateur vous permet d’explorer les fichiers du modèle et les commits et de voir la différence introduite par chaque commit :