# Huggingface_Hub

## Docs

- [Un client Python pour le Hugging Face Hub](https://huggingface.co/docs/huggingface_hub/main/fr/index.md)
- [Installation](https://huggingface.co/docs/huggingface_hub/main/fr/installation.md)
- [Démarrage rapide](https://huggingface.co/docs/huggingface_hub/main/fr/quick-start.md)
- [Intégrez votre framework de ML avec le Hub](https://huggingface.co/docs/huggingface_hub/main/fr/guides/integrations.md)

### Un client Python pour le Hugging Face Hub
https://huggingface.co/docs/huggingface_hub/main/fr/index.md

# Un client Python pour le Hugging Face Hub 


La librairie `huggingface_hub` vous permet d'interagir avec le
[Hugging Face Hub](https://hf.co), une plateforme de machine learning
pour créer et collaborer. Découvrez des modèles pré-
entrainés et des datasets pour vos projets ou jouez avec des centraines
d'applications hébergées sur le Hub. Vous pouvez aussi
créer et partager vos propres modèles et datasets avec la communauté.
La librairie `huggingface_hub` offre une manière simple de faire toutes
ces choses avec Python.

Lisez le [guide d'introduction rapide](quick-start) pour vous lancer avec la librairie
`huggingface_hub`. Vous apprendrez à télécharger des fichiers depuis le Hub,
à créer un dépôt et upload des fichiers vers le Hub. Continuez à lire pour
apprendre le management de dépôt sur le Hub, comment interagir avec les discussions
ou même comment accéder à l'API d'inférence.

<div class="mt-10">
  <div class="w-full flex flex-col space-y-4 md:space-y-0 md:grid md:grid-cols-2 md:gap-y-4 md:gap-x-5">

    <a class="!no-underline border dark:border-gray-700 p-5 rounded-lg shadow hover:shadow-lg" href="./guides/overview">
      <div class="w-full text-center bg-gradient-to-br from-indigo-400 to-indigo-500 rounded-lg py-1.5 font-semibold mb-5 text-white text-lg leading-relaxed">Vue d'ensemble</div>
      <p class="text-gray-700">Guides pratiques pour vous aider à atteindre un but en particulier. Lisez ces guides pour apprendre comment utiliser huggingface_hub pour résoudre des problèmes concrets.</p>
    </a>

    <a class="!no-underline border dark:border-gray-700 p-5 rounded-lg shadow hover:shadow-lg" href="./package_reference/overview">
      <div class="w-full text-center bg-gradient-to-br from-purple-400 to-purple-500 rounded-lg py-1.5 font-semibold mb-5 text-white text-lg leading-relaxed">Références</div>
      <p class="text-gray-700">Description exhaustive des classes et méthodes présentes dans huggingface_hub.</p>
    </a>

    <a class="!no-underline border dark:border-gray-700 p-5 rounded-lg shadow hover:shadow-lg" href="./concepts/git_vs_http">
      <div class="w-full text-center bg-gradient-to-br from-pink-400 to-pink-500 rounded-lg py-1.5 font-semibold mb-5 text-white text-lg leading-relaxed">Guides conceptuels</div>
      <p class="text-gray-700">Explications permettant d'avoir une meilleure compréhension de la philosophie derrière huggingface_hub.</p>
    </a>

  </div>
</div>

<!-- 
<a class="!no-underline border dark:border-gray-700 p-5 rounded-lg shadow hover:shadow-lg" href="./tutorials/overview"
  ><div class="w-full text-center bg-gradient-to-br from-blue-400 to-blue-500 rounded-lg py-1.5 font-semibold mb-5 text-white text-lg leading-relaxed">Tutoriaux</div>
  <p class="text-gray-700">Apprenez les bases et familiarisez vous avec l'utilisation de huggingface_hub pour intéragir avec le Hub 🤗 depuis le code!</p>
</a> -->

## Contributions

Toutes les contributions au projet `huggingface_hub` sont les bienvenues et valorisées à la même hauteur.
🤗 En plus de l'ajout ou de la correction de bug dans le code, vous
pouvez également aider à améliorer la documentation en vérifiant qu'elle est exacte et
à jour, répondre à des questions sur des issues, et demander de nouvelles fonctionnalités
qui amélioreront la librairie. Regardez le [guide de contribution](https://github.com/huggingface/huggingface_hub/blob/main/CONTRIBUTING.md)
pour en savoir plus sur comment commencer à travailler sur une issue, comment faire une pull request et comment tester vos contributions pour
vérifier que vos modifications fonctionnent comme prévu.

Les contributeurs doivent aussi respecter notre [code de conduite](https://github.com/huggingface/huggingface_hub/blob/main/CODE_OF_CONDUCT.md) (en anglais) pour créer un espace collaboratif inclusif et bienveillant envers tout le monde.

<EditOnGithub source="https://github.com/huggingface/huggingface_hub/blob/main/docs/source/fr/index.md" />

### Installation
https://huggingface.co/docs/huggingface_hub/main/fr/installation.md

# Installation

Avant de commencer, vous allez avoir besoin de préparer votre environnement
en installant les packages appropriés.

`huggingface_hub` est testée sur **Python 3.9+**.

## Installation avec pip

Il est fortement recommandé d'installer `huggingface_hub` dans un [environnement virtuel](https://docs.python.org/3/library/venv.html).
Si vous n'êtes pas familier avec les environnements virtuels Python, suivez ce [guide](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/). Un environnement virtuel sera utile lorsque vous devrez gérer des plusieurs projets en parallèle
afin d'éviter les problèmes de compatibilité entre les différentes dépendances.

Commencez par créer un environnement virtuel à l'emplacement de votre projet:

```bash
python -m venv .env
```

Activez l'environnement virtuel sur Linux et macOS:

```bash
source .env/bin/activate
```

Activez l'environnement virtuel sur Windows:

```bash
.env/Scripts/activate
```

Maintenant, vous êtes prêts à installer `hugginface_hub` [depuis PyPi](https://pypi.org/project/huggingface-hub/):

```bash
pip install --upgrade huggingface_hub
```

Une fois l'installation terminée, rendez-vous à la section [vérification](#verification-de-l-installation) pour s'assurer que tout fonctionne correctement.

### Installation des dépendances optionnelles

Certaines dépendances de `huggingface_hub` sont [optionnelles](https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#optional-dependencies) car elles ne sont pas nécessaire pour faire marcher les fonctionnalités principales de `huggingface_hub`.
Toutefois, certaines fonctionnalités de `huggingface_hub` ne seront pas disponibles si les dépendances optionnelles ne sont pas installées

Vous pouvez installer des dépendances optionnelles via `pip`:
```bash
#Installation des dépendances spécifiques à Pytorch et au CLI.
pip install 'huggingface_hub[cli,torch]'
```

Voici une liste des dépendances optionnelles dans `huggingface_hub`:
- `cli` fournit une interface d'invite de commande plus pratique pour `huggingface_hub`.
- `fastai`, `torch` sont des dépendances pour utiliser des fonctionnalités spécifiques à un framework.
- `dev` permet de contribuer à la librairie. Cette dépendance inclut `testing` (pour lancer des tests), `typing` (pour lancer le vérifieur de type) et `quality` (pour lancer des linters).



### Installation depuis le code source

Dans certains cas, il est intéressant d'installer `huggingface_hub` directement depuis le code source.
Ceci vous permet d'utiliser la version `main`, contenant les dernières mises à jour, plutôt que
d'utiliser la dernière version stable. La version `main` est utile pour rester à jour sur les
derniers développements, par exemple si un bug est corrigé depuis la dernière version officielle
mais que la nouvelle version n'a pas encore été faite.

Toutefois, cela signifie que la version `main` peut ne pas être stable. Nous travaillons
afin de rendre la version `main` aussi stable que possible, et la plupart des problèmes sont résolus
en quelques heures ou jours. Si vous avez un problème, ouvrez une issue afin que
nous puissions la régler au plus vite !

```bash
pip install git+https://github.com/huggingface/huggingface_hub
```

Lorsque vous installez depuis le code source, vous pouvez préciser la branche depuis laquelle installer. Cela permet de tester une nouvelle fonctionnalité ou un bug-fix qui n'a pas encore été merge:

```bash
pip install git+https://github.com/huggingface/huggingface_hub@ma-branche
```

Une fois l'installation terminée, rendez-vous à la section [vérification](#verification-de-l-installation) pour s'assurer que tout fonctionne correctement.

### Installation éditable

L'installation depuis le code source vous permet de mettre en place une [installation éditable](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs). Cette installation sert surtout si vous comptez contribuer à `huggingface_hub`
et que vous avez besoin de tester rapidement des changements dans le code. Pour cela, vous devez cloner le projet `huggingface_hub` sur votre machine.

```bash
# Commencez par cloner le dépôt en local
git clone https://github.com/huggingface/huggingface_hub.git

# Ensuite, installez-le avec le flag -e
cd huggingface_hub
pip install -e .
```

Python regardera maintenant à l'intérieur du dossier dans lequel vous avez cloné le dépôt en
plus des chemins de librairie classiques. Par exemple, si vos packages Python sont installés dans
`./.venv/lib/python3.13/site-packages/`, Python regardera aussi dans le dossier que vous avez
cloné `./huggingface_hub/`.

## Installation avec conda

Si vous avez plutôt l'habitude d'utiliser conda, vous pouvez installer `huggingface_hub` en utilisant le [channel conda-forge](https://anaconda.org/conda-forge/huggingface_hub):


```bash
conda install -c conda-forge huggingface_hub
```

Une fois l'installation terminée, rendez-vous à la section [vérification](#verification-de-l-installation) pour s'assurer que tout fonctionne correctement.

## Vérification de l'installation

Une fois installée, vérifiez que `huggingface_hub` marche correctement en lançant la commande suivante:

```bash
python -c "from huggingface_hub import model_info; print(model_info('gpt2'))"
```

Cette commande va récupérer des informations sur le modèle [gpt2](https://huggingface.co/gpt2) depuis le Hub.
La sortie devrait ressembler à ça:

```text
Model Name: gpt2
Tags: ['pytorch', 'tf', 'jax', 'tflite', 'rust', 'safetensors', 'gpt2', 'text-generation', 'en', 'doi:10.57967/hf/0039', 'transformers', 'exbert', 'license:mit', 'has_space']
Task: text-generation
```

## Les limitations Windows

Afin de démocratiser le machine learning au plus grand nombre, nous avons développé `huggingface_hub`
de manière cross-platform et en particulier, pour qu'elle fonctionne sur une maximum de systèmes d'exploitation différents. Toutefois
`huggingface_hub` connaît dans certains cas des limitations sur Windows.
Nous avons listé ci-dessous les problèmes connus. N'hésitez pas à nous signaler si vous rencontrez un problème
non documenté en ouvrant une [issue sur Github](https://github.com/huggingface/huggingface_hub/issues/new/choose).

- Le cache de `huggingface_hub` a besoin des symlinks pour mettre en cache les fichiers installés depuis le Hub.
Sur windows, vous devez activer le mode développeur pour lancer ou lancer votre script en tant qu'administrateur
afin de faire fonctionner les symlinks. S'ils ne sont pas activés, le système de cache fonctionnera toujours mais
de manière sous-optimale. Consultez les [limitations du cache](./guides/manage-cache#limitations) pour plus de détails.
- Les noms de fichiers sur le Hub peuvent avoir des caractères spéciaux (par exemple `"path/to?/my/file"`).
Windows est plus restrictif sur les [caractères spéciaux](https://learn.microsoft.com/en-us/windows/win32/intl/character-sets-used-in-file-names)
ce qui rend ces fichiers ininstallables sur Windows. Heureusement c'est un cas assez rare.
Contactez le propriétaire du dépôt si vous pensez que c'est une erreur ou contactez nous
pour que nous cherchions une solution.


## Prochaines étapes

Une fois que `huggingface_hub` est installé correctement sur votre machine, vous aurez peut-être besoin de
[configurer les variables d'environnement](package_reference/environment_variables) ou de [lire un de nos guides](guides/overview)
pour vous lancer.


<EditOnGithub source="https://github.com/huggingface/huggingface_hub/blob/main/docs/source/fr/installation.md" />

### Démarrage rapide
https://huggingface.co/docs/huggingface_hub/main/fr/quick-start.md

# Démarrage rapide

Le [Hugging Face Hub](https://huggingface.co/) est le meilleur endroit pour partager des
modèles de machine learning, des démos, des datasets et des métriques. La librairie
`huggingface_hub` vous aide à intéragir avec le Hub sans sortir de votre environnement de
développement. Vous pouvez: créer et gérer des dépôts facilement, télécharger et upload des
fichiers, et obtenir des modèles et des métadonnées depuis le Hub.

## Installation

Pour commencer, installez la librairie `huggingface_hub`:

```bash
pip install --upgrade huggingface_hub
```

Pour plus de détails, vérifiez le guide d'[installation](installation)

## Télécharger des fichiers

Les dépôts sur le Hub utilisent le versioning Git, les utilisateurs peuvent
télécharger un fichier, ou un dépôt entier. Vous pouvez utiliser la fonction `hf_hub_download()`
pour télécharger des fichiers. Cette fonction téléchargera et mettra dans le cache un fichier
sur votre disque local. La prochaine fois que vous aurez besoin de ce fichier, il sera chargé
depuis votre cache de façon à ce que vous n'ayez pas besoin de le retélécharger.

Vous aurez besoin de l'id du dépôt et du nom du fichier que vous voulez télécharger.
Par exemple, pour télécharger le fichier de configuration du
modèle [Pegasus](https://huggingface.co/google/pegasus-xsum):

```py
>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download(repo_id="google/pegasus-xsum", filename="config.json")
```

Pour télécharger une version spécifique du fichier, utilisez le paramètre `revision` afin
de spécifier le nom de la branche, le tag ou le hash de commit. Si vous décidez d'utiliser
le hash de commit, vous devez renseigner le hash entier et pas le hash court de 7 caractères:

```py
>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download(
...     repo_id="google/pegasus-xsum", 
...     filename="config.json", 
...     revision="4d33b01d79672f27f001f6abade33f22d993b151"
... )
```

Pour plus de détails et d'options, consultez la réference de l'API pour `hf_hub_download()`.

## Connexion

Dans la plupart des cas, vous devez être connectés avec un compte Hugging Face pour interagir
avec le Hub: pour télécharger des dépôts privés, upload des fichiers, créer des pull
requests...
[Créez un compte](https://huggingface.co/join) si vous n'en avez pas déjà un et connectez
vous pour obtenir votre [token d'authentification](https://huggingface.co/docs/hub/security-tokens)
depuis vos [paramètres](https://huggingface.co/settings/tokens). Le token
est utilisé pour authentifier votre identité au Hub.

Une fois que vous avez votre token d'authentification, lancez la commande suivante
dans votre terminal:

```bash
hf auth login
# ou en utilisant une varible d'environnement:
hf auth login --token $HUGGINGFACE_TOKEN
```

Sinon, vous pouvez vous connecter en utilisant `login()` dans un notebook ou
un script:

```py
>>> from huggingface_hub import login
>>> login()
```

Il est aussi possible de se connecter automatiquement sans qu'on vous demande votre token en
passant le token dans `login()` de cette manière: `login(token="hf_xxx")`. Si vous choisissez
cette méthode, faites attention lorsque vous partagez votre code source. Une bonne pratique est
de charger le token depuis un trousseau sécurisé au lieu de l'enregistrer en clair dans votre
codebase/notebook.

Vous ne pouvez être connecté qu'à un seul compte à la fois. Si vous connectez votre machine à un autre compte,
vous serez déconnecté du premier compte. Vérifiez toujours le compte que vous utilisez avec la commande
`hf auth whoami`. Si vous voulez gérer plusieurs compte dans le même script, vous pouvez passer votre
token à chaque appel de méthode. C'est aussi utile si vous ne voulez pas sauvegarder de token sur votre machine.

> [!WARNING]
> Une fois que vous êtes connectés, toutes les requêtes vers le Hub (même les méthodes qui ne nécessite pas explicitement
> d'authentification) utiliseront votre token d'authentification par défaut. Si vous voulez supprimer l'utilisation implicite
> de votre token, vous devez définir la variable d'environnement `HF_HUB_DISABLE_IMPLICIT_TOKEN`.

## Créer un dépôt

Une fois que vous avez créé votre compte et que vous vous êtes connectés,
vous pouvez créer un dépôt avec la fonction `create_repo()`:

```py
>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.create_repo(repo_id="super-cool-model")
```

Si vous voulez que votre dépôt soit privé, alors:

```py
>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.create_repo(repo_id="super-cool-model", private=True)
```

Les dépôts privés ne seront visible que par vous.

> [!TIP]
> Pour créer un dépôt ou push du contenu sur le Hub, vous devez fournir un token
> d'authentification qui a les permissions `write`. Vous pouvez choisir la permission
> lorsque vous générez le token dans vos [paramètres](https://huggingface.co/settings/tokens).

## Upload des fichiers

Utilisez la fonction `upload_file()` pour ajouter un fichier à votre dépôt.
Vous devez spécifier:

1. Le chemin du fichier à upload.
2. Le chemin du fichier dans le dépôt.
3. L'id du dépôt dans lequel vous voulez ajouter le fichier.

```py
>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.upload_file(
...     path_or_fileobj="/home/lysandre/dummy-test/README.md",
...     path_in_repo="README.md",
...     repo_id="lysandre/test-model",
... )
```

Pour upload plus d'un fichier à la fois, consultez le guide [upload](./guides/upload)
qui détaille plusieurs méthodes pour upload des fichiers (avec ou sans Git).

## Prochaines étapes

La librairie `huggingface_hub` permet à ses utilisateurs d'intéragir facilementavec le Hub via
Python. Pour en apprendre plus sur comment gérer vos fichiers
et vos dépôts sur le Hub, nous vous recommandons de lire notre [guide conceptuel](./guides/overview)
pour :

- [Gérer votre dépôt](./guides/repository).
- [Télécharger](./guides/download) des fichiers depuis le Hub.
- [Upload](./guides/upload) des fichiers vers le Hub.
- [Faire des recherches dans le Hub](./guides/search) pour votre modèle ou dataset.
- [Accédder à l'API d'inférence](./guides/inference) pour faire des inférences rapides.

<EditOnGithub source="https://github.com/huggingface/huggingface_hub/blob/main/docs/source/fr/quick-start.md" />

### Intégrez votre framework de ML avec le Hub
https://huggingface.co/docs/huggingface_hub/main/fr/guides/integrations.md

# Intégrez votre framework de ML avec le Hub

Le Hugging Face Hub facilite l'hébergement et le partage de modèles et de jeux de données.
Des [dizaines de librairies](https://huggingface.co/docs/hub/models-libraries) sont intégrées à cet écosystème. La communauté travaille constamment à en intégrer de nouvelles et contribue ainsi à faciliter la collaboration dans le milieu du machine learning. La librairie `huggingface_hub` joue un rôle clé dans ce processus puisqu'elle permet d'interagir avec le Hub depuis n'importe quel script Python.

Il existe quatre façons principales d'intégrer une bibliothèque au Hub :
1. **Push to Hub**  implémente une méthode pour upload un modèle sur le Hub. Cela inclut les paramètres du modèle, sa fiche descriptive (appelée [Model Card](https://huggingface.co/docs/huggingface_hub/how-to-model-cards)) et toute autre information pertinente liée au modèle (par exemple, les logs d'entraînement). Cette méthode est souvent appelée `push_to_hub()`.
2. **Download from Hub** implémente une méthode pour charger un modèle depuis le Hub. La méthode doit télécharger la configuration et les poids du modèle puis instancier celui-ci. Cette méthode est souvent appelée `from_pretrained` ou `load_from_hub()`.
3. **Widgets** affiche un widget sur la page d'accueil de votre modèle dans le Hub. Les widgets permettent aux utilisateurs de rapidement tester un modèle depuis le navigateur.

Dans ce guide, nous nous concentrerons sur les deux premiers sujets. Nous présenterons les deux approches principales que vous pouvez utiliser pour intégrer une librairie, avec leurs avantages et leurs inconvénients. Tout est résumé à la fin du guide pour vous aider à choisir entre les deux. Veuillez garder à l'esprit que ce ne sont que des conseils, et vous êtes libres de les adapter à votre cas d'usage.

Si les Widgets vous intéressent, vous pouvez suivre [ce guide](https://huggingface.co/docs/hub/models-adding-libraries#set-up-the-inference-api). Dans les deux cas, vous pouvez nous contacter si vous intégrez une librairie au Hub et que vous voulez être listé [dans la documentation officielle](https://huggingface.co/docs/hub/models-libraries).

## Une approche flexible: les helpers

La première approche pour intégrer une librairie au Hub est d'implémenter les méthodes `push_to_hub` et `from_pretrained` 
vous-même. Ceci vous donne une flexibilité totale sur le choix du fichier que vous voulez upload/download et sur comment
gérer les inputs spécifiques à votre framework. Vous pouvez vous référer aux guides : [upload des fichiers](./upload)
et [télécharger des fichiers](./download) pour en savoir plus sur la manière de faire. Par example, c'est de cette manière que l'intégration
de FastAI est implémentée (voir `push_to_hub_fastai()` et `from_pretrained_fastai()`).

L'implémentation peut varier entre différentes librairies, mais le workflow est souvent similaire.

### from_pretrained

Voici un exemple classique pour implémenter la méthode `from_pretrained`:

```python
def from_pretrained(model_id: str) -> MyModelClass:
   # Téléchargement des paramètres depuis le Hub
   cached_model = hf_hub_download(
      repo_id=repo_id,
      filename="model.pkl",
      library_name="fastai",
      library_version=get_fastai_version(),
   )

   # Instanciation du modèle
    return load_model(cached_model)
```

### push_to_hub

La méthode `push_to_hub` demande souvent un peu plus de complexité pour gérer la création du dépôt git, générer la model card et enregistrer les paramètres.
Une approche commune est de sauvegarder tous ces fichiers dans un dossier temporaire, les transférer sur le Hub avant de les supprimer localement.

```python
def push_to_hub(model: MyModelClass, repo_name: str) -> None:
   api = HfApi()

   # Créez d'un dépôt s'il n'existe pas encore, et obtenez le repo_id associé
   repo_id = api.create_repo(repo_name, exist_ok=True).repo_id

   # Sauvegardez tous les fichiers dans un chemin temporaire, et pushez les en un seul commit
   with TemporaryDirectory() as tmpdir:
      tmpdir = Path(tmpdir)

      # Sauvegardez les poids
      save_model(model, tmpdir / "model.safetensors")

      # Générez la model card
      card = generate_model_card(model)
      (tmpdir / "README.md").write_text(card)

      # Sauvegardez les logs
      # Sauvegardez le métriques d'évaluation
      # ...

      # Pushez vers le Hub
      return api.upload_folder(repo_id=repo_id, folder_path=tmpdir)
```

Ceci n'est qu'un exemple. Si vous êtes intéressés par des manipulations plus complexes (supprimer des fichiers distants,
upload des poids à la volée, maintenir les poids localement, etc.) consultez le guide [upload des fichiers](./upload).

### Limitations

Bien que très flexible, cette approche a quelques défauts, particulièrement en termes de maintenance. Les utilisateurs
d'Hugging Face sont habitués à utiliser certaines fonctionnalités lorsqu'ils travaillent avec `huggingface_hub`. Par exemple,
lors du chargement de fichiers depuis le Hub, il est commun de passer des paramètres tels que:
- `token`: pour télécharger depuis un dépôt privé
- `revision`: pour télécharger depuis une branche spécifique
- `cache_dir`: pour paramétrer la mise en cache des fichiers
- `force_download`: pour désactiver le cache
- `api_endpoint`/`proxies`: pour configurer la session HTTP

Lorsque vous pushez des modèles, des paramètres similaires sont utilisables:
- `commit_message`: message de commit personnalisé
- `private`: crée un dépôt privé s'il en manque un
- `create_pr`: crée une pull request au lieu de push vers `main`
- `branch`: push vers une branche au lieu de push sur `main`
- `allow_patterns`/`ignore_patterns`: filtre les fichiers à upload
- `token`
- `api_endpoint`
- ...

Tous ces paramètres peuvent être ajoutés aux implémentations vues ci-dessus et passés aux méthodes de `huggingface_hub`.
Toutefois, si un paramètre change ou qu'une nouvelle fonctionnalité est ajoutée, vous devrez mettre à jour votre package.
Supporter ces paramètres implique aussi plus de documentation à maintenir de votre côté. Dans la prochaine section, nous allons voir comment dépasser ces limitations.

## Une approche plus complexe: l'héritage de classe

Comme vu ci-dessus, deux méthodes principales sont à inclure dans votre librairie pour l'intégrer avec le Hub:
la méthode permettant d'upload des fichiers (`push_to_hub`) et celle pour télécharger des fichiers (`from_pretrained`).
Vous pouvez implémenter ces méthodes vous-même mais cela a des inconvénients. Pour gérer ça, `huggingface_hub` fournit
un outil qui utilise l'héritage de classe. Regardons comment ça marche !

Dans beaucoup de cas, une librairie définit déjà les modèles comme des classes Python. La classe contient les
propriétés du modèle et des méthodes pour charger, lancer, entraîner et évaluer le modèle. Notre approche est d'étendre
cette classe pour inclure les fonctionnalités upload et download en utilisant les mixins. Une [mixin](https://stackoverflow.com/a/547714)
est une classe qui est faite pour étendre une classe existante avec une liste de fonctionnalités spécifiques en utilisant l'héritage de classe.
`huggingface_hub` offre son propre mixin, le `ModelHubMixin`. La clef ici est de comprendre son comportement et comment le customiser.

La classe `ModelHubMixin` implémente 3 méthodes *public* (`push_to_hub`, `save_pretrained` et `from_pretrained`). Ce
sont les méthodes que vos utilisateurs appelleront pour charger/enregistrer des modèles avec votre librairie.
`ModelHubMixin` définit aussi 2 méthodes *private* (`_save_pretrained` et `from_pretrained`). Ce sont celles que vous
devez implémenter. Ainsi, pour intégrer votre librairie, vous devez :

1. Faire en sorte que votre classe Model hérite de `ModelHubMixin`.
2. Implémenter les méthodes privées:
    - `_save_pretrained()`: méthode qui prend en entrée un chemin vers un directory et qui sauvegarde le modèle. 
    Vous devez écrire toute la logique pour dump votre modèle de cette manière: model card, poids du modèle, fichiers de configuration,
    et logs d'entraînement. Toute information pertinente pour ce modèle doit être gérée par cette méthode. Les
    [model cards](https://huggingface.co/docs/hub/model-cards) sont particulièrement importantes pour décrire votre modèle. Vérifiez
    [notre guide d'implémentation](./model-cards) pour plus de détails.
    - `_from_pretrained()`: **méthode de classe** prenant en entrée un `model_id` et qui retourne un modèle instancié.
    Cette méthode doit télécharger un ou plusieurs fichier(s) et le(s) charger.
3. Fini!

L'avantage d'utiliser `ModelHubMixin` est qu'une fois que vous vous êtes occupés de la sérialisation et du chargement du fichier,
vous êtes prêts. Vous n'avez pas besoin de vous soucier de la création du dépôt, des commits, des pull requests ou des révisions.
Tout ceci est géré par le mixin et est disponible pour vos utilisateurs. Le Mixin s'assure aussi que les méthodes publiques sont
bien documentées et que les annotations de typage sont spécifiées.

### Un exemple concret: PyTorch

Un bon exemple de ce que nous avons vu ci-dessus est `PyTorchModelHubMixin`, notre intégration pour le framework PyTorch.
C'est une intégration prête à l'emploi.

#### Comment l'utiliser ?

Voici comment n'importe quel utilisateur peut charger/enregistrer un modèle Pytorch depuis/vers le Hub:

```python
>>> import torch
>>> import torch.nn as nn
>>> from huggingface_hub import PyTorchModelHubMixin

# 1. Définissez votre modèle Pytorch exactement comme vous êtes habitués à le faire
>>> class MyModel(nn.Module, PyTorchModelHubMixin): # héritage multiple
...     def __init__(self):
...         super().__init__() 
...         self.param = nn.Parameter(torch.rand(3, 4))
...         self.linear = nn.Linear(4, 5)

...     def forward(self, x):
...         return self.linear(x + self.param)
>>> model = MyModel()

# 2. (optionnel) Sauvegarder le modèle dans un chemin local
>>> model.save_pretrained("path/to/my-awesome-model")

# 3. Pushez les poids du modèle vers le Hub
>>> model.push_to_hub("my-awesome-model")

# 4. initialisez le modèle depuis le Hub
>>> model = MyModel.from_pretrained("username/my-awesome-model")
```

#### Implémentation

L'implémentation est très succincte (voir [ici](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/hub_mixin.py)).

1. Premièrement, faites hériter votre classe de `ModelHubMixin`:

```python
from huggingface_hub import ModelHubMixin

class PyTorchModelHubMixin(ModelHubMixin):
   (...)
```

2. Implémentez la méthode `_save_pretrained`:

```py
from huggingface_hub import ModelCard, ModelCardData

class PyTorchModelHubMixin(ModelHubMixin):
   (...)

   def _save_pretrained(self, save_directory: Path):
      """Générez une model card et enregistrez les poids d'un modèle Pytroch vers un chemin local."""
      model_card = ModelCard.from_template(
         card_data=ModelCardData(
            license='mit',
            library_name="pytorch",
            ...
         ),
         model_summary=...,
         model_type=...,
         ...
      )
      (save_directory / "README.md").write_text(str(model))
      torch.save(obj=self.module.state_dict(), f=save_directory / "pytorch_model.bin")
```

3. Implémentez la méthode `_from_pretrained`:

```python
class PyTorchModelHubMixin(ModelHubMixin):
   (...)

   @classmethod # Doit absolument être une méthode de clase !
   def _from_pretrained(
      cls,
      *,
      model_id: str,
      revision: str,
      cache_dir: str,
      force_download: bool,
      local_files_only: bool,
      token: Union[str, bool, None],
      map_location: str = "cpu", # argument supplémentaire
      strict: bool = False, # argument supplémentaire
      **model_kwargs,
   ):
      """Chargez les poids pré-entrainés et renvoyez les au modèle chargé."""
      if os.path.isdir(model_id): # Peut être un chemin local
         print("Loading weights from local directory")
         model_file = os.path.join(model_id, "pytorch_model.bin")
      else: # Ou un modèle du Hub
         model_file = hf_hub_download( # Téléchargez depuis le Hub, en passant le mêmes arguments d'entrée
            repo_id=model_id,
            filename="pytorch_model.bin",
            revision=revision,
            cache_dir=cache_dir,
            force_download=force_download,
            token=token,
            local_files_only=local_files_only,
         )

      # Chargez le modèle et reoutnez une logique personnalisée dépendant de votre framework
      model = cls(**model_kwargs)
      state_dict = torch.load(model_file, map_location=torch.device(map_location))
      model.load_state_dict(state_dict, strict=strict)
      model.eval()
      return model
```

Et c'est fini ! Votre librairie permet maintenant aux utilisateurs d'upload et de télécharger des fichiers vers et depuis le Hub.

## Comparaison

Résumons rapidement les deux approches que nous avons vu avec leurs avantages et leurs défauts. Le tableau ci-dessous
est purement indicatif. Votre framework aura peut-êre des spécificités à prendre en compte. Ce guide
est ici pour vous donner des indications et des idées sur comment gérer l'intégration. Dans tous les cas,
n'hésitez pas à nous contacter si vous avez une question !

<!-- Généré en utilisant https://www.tablesgenerator.com/markdown_tables -->
|            Intégration            |                                                                             Utilisant des helpers                                                                              |                                         Utilisant `ModelHubMixin`                                         |
| :-------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------: |
|      Expérience utilisateur       |                                                           `model = load_from_hub(...)`<br>`push_to_hub(model, ...)`                                                            |                     `model = MyModel.from_pretrained(...)`<br>`model.push_to_hub(...)`                      |
|             Flexible              |                                                        Très flexible.<br>Vous controllez complètement l'implémentation.                                                        |                     Moins flexible.<br>Votre framework doit avoir une classe de modèle.                     |
|            Maintenance            | Plus de maintenance pour ajouter du support pour la configuration, et de nouvelles fonctionnalités. Peut aussi nécessiter de fixx des problèmes signalés par les utilisateurs. | Moins de maintenance vu que la plupart des intégrations avec le Hub sont implémentés dans `huggingface_hub` |
| Documentation / Anotation de type |                                                                               A écrire à la main                                                                               |                                  Géré partiellement par `huggingface_hub`.                                  |


<EditOnGithub source="https://github.com/huggingface/huggingface_hub/blob/main/docs/source/fr/guides/integrations.md" />
