Pytorch
TensorFlow

#
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 :

✏️ Essayez Prenez le modèle et le tokenizer associés au checkpoint `bert-base-cased` et téléchargez-les vers un dépôt dans votre espace en utilisant la méthode `push_to_hub()`. Vérifiez que le dépôt apparaît correctement sur votre page avant de le supprimer.

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.

✏️ Lors de la création du dépôt à partir de l'interface web, le fichier .gitattributes est automatiquement configuré pour considérer les fichiers avec certaines extensions, comme .bin et .h5, comme des fichiers volumineux, et git-lfs les suivra sans aucune configuration nécessaire de votre part.

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 :