# Créer et partager des Model Cards

La bibliothèque `huggingface_hub` fournit une interface Python pour créer, partager et mettre à jour les Model Cards. Consultez [la page de documentation dédiée](https://huggingface.co/docs/hub/models-cards) pour une vue plus approfondie de ce que sont les Model Cards sur le Hub et de leur fonctionnement interne.

## Charger une carte de modèle depuis le Hub

Pour charger une carte existante depuis le Hub, vous pouvez utiliser la fonction [ModelCard.load()](/docs/huggingface_hub/v2.4.0/fr/package_reference/cards#huggingface_hub.RepoCard.load). Ici, nous chargerons la carte de [`nateraw/vit-base-beans`](https://huggingface.co/nateraw/vit-base-beans).

```python
from huggingface_hub import ModelCard

card = ModelCard.load('nateraw/vit-base-beans')
```

Cette carte possède certains attributs utiles que vous pouvez souhaiter accéder ou exploiter :
  - `card.data` : Renvoie une instance de [ModelCardData](/docs/huggingface_hub/v2.4.0/fr/package_reference/cards#huggingface_hub.ModelCardData) contenant les métadonnées de la carte du modèle. Appelez `.to_dict()` sur cette instance pour obtenir la représentation sous forme de dictionnaire.
  - `card.text` : Renvoie le texte de la carte, *à l'exception de l'en-tête de métadonnées*.
  - `card.content` : Renvoie le contenu textuel de la carte, *y compris l'en-tête de métadonnées*.

## Créer des fiches de modèle

### À partir du texte

Pour initialiser une Model Card à partir de texte, il suffit de passer le contenu textuel de la carte à `ModelCard` lors de l’initialisation.

```python
content = """
---
language: en
license: mit
---

# My Model Card
"""

card = ModelCard(content)
card.data.to_dict() == {'language': 'en', 'license': 'mit'}  # True
```

Une autre façon de procéder consiste à utiliser des f-strings. Dans l'exemple suivant, nous :

- Utilisez [ModelCardData.to_yaml()](/docs/huggingface_hub/v2.4.0/fr/package_reference/cards#huggingface_hub.CardData.to_yaml) pour convertir les métadonnées définies en YAML afin de pouvoir insérer le bloc YAML dans la carte du modèle.
- Montrez comment vous pourriez utiliser une variable de modèle via des f-strings Python.

```python
card_data = ModelCardData(language='en', license='mit', library='timm')

example_template_var = 'nateraw'
content = f"""
---
{ card_data.to_yaml() }
---

# My Model Card

This model created by [@{example_template_var}](https://github.com/{example_template_var})
"""

card = ModelCard(content)
print(card)
```

L'exemple ci-dessus nous laisserait une carte qui ressemblerait à ceci :

```
---
language: en
license: mit
library: timm
---

# My Model Card

This model created by [@nateraw](https://github.com/nateraw)
```

### À partir d'un modèle Jinja

Si vous avez installé `Jinja2`, vous pouvez créer des Model Cards à partir d'un fichier de modèle jinja. Voici un exemple de base :

```python
from pathlib import Path

from huggingface_hub import ModelCard, ModelCardData

# Define your jinja template
template_text = """
---
{{ card_data }}
---

# Model Card for MyCoolModel

This model does this and that.

This model was created by [@{{ author }}](https://hf.co/{{author}}).
""".strip()

# Write the template to a file
Path('custom_template.md').write_text(template_text)

# Define card metadata
card_data = ModelCardData(language='en', license='mit', library_name='keras')

# Create card from template, passing it any jinja template variables you want.
# In our case, we'll pass author
card = ModelCard.from_template(card_data, template_path='custom_template.md', author='nateraw')
card.save('my_model_card_1.md')
print(card)
```

Le markdown de la carte résultante ressemble à ceci :

```
---
language: en
license: mit
library_name: keras
---

# Model Card for MyCoolModel

This model does this and that.

This model was created by [@nateraw](https://hf.co/nateraw).
```

Si vous mettez à jour card.data, la modification sera reflétée sur la carte elle-même.

```
card.data.library_name = 'timm'
card.data.language = 'fr'
card.data.license = 'apache-2.0'
print(card)
```

Maintenant, comme vous pouvez le voir, l'en-tête de métadonnées a été mis à jour :

```
---
language: fr
license: apache-2.0
library_name: timm
---

# Model Card for MyCoolModel

This model does this and that.

This model was created by [@nateraw](https://hf.co/nateraw).
```

Lorsque vous mettez à jour les données de la carte, vous pouvez vérifier qu'elle est toujours valide par rapport au Hub en appelant [ModelCard.validate()](/docs/huggingface_hub/v2.4.0/fr/package_reference/cards#huggingface_hub.RepoCard.validate). Cela garantit que la carte respecte toutes les règles de validation définies sur le Hugging Face Hub.

### À partir du modèle par défaut

Au lieu d’utiliser votre propre modèle, vous pouvez également utiliser le [modèle par défaut](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/templates/modelcard_template.md), qui est une fiche de modèle complète avec de nombreuses sections que vous pouvez remplir. En interne, il utilise [Jinja2](https://jinja.palletsprojects.com/en/3.1.x/) pour remplir un fichier de modèle.

> [!TIP]
> Notez que vous devrez avoir Jinja2 installé pour utiliser `from_template`. Vous pouvez le faire avec `pip install Jinja2`.

```python
card_data = ModelCardData(language='en', license='mit', library_name='keras')
card = ModelCard.from_template(
    card_data,
    model_id='my-cool-model',
    model_description="this model does this and that",
    developers="Nate Raw",
    repo="https://github.com/huggingface/huggingface_hub",
)
card.save('my_model_card_2.md')
print(card)
```

## Partager les fiches de modèle

Si vous êtes authentifié sur le Hugging Face Hub (en utilisant `hf auth login` ou [login()](/docs/huggingface_hub/v2.4.0/fr/package_reference/authentication#huggingface_hub.login)), vous pouvez pousser des cartes sur le Hub en appelant simplement [ModelCard.push_to_hub()](/docs/huggingface_hub/v2.4.0/fr/package_reference/cards#huggingface_hub.RepoCard.push_to_hub). Voyons comment faire...

Tout d'abord, nous allons créer un nouveau dépôt nommé 'hf-hub-modelcards-pr-test' dans l'espace de noms de l'utilisateur authentifié :

```python
from huggingface_hub import whoami, create_repo

user = whoami()['name']
repo_id = f'{user}/hf-hub-modelcards-pr-test'
url = create_repo(repo_id, exist_ok=True)
```

Ensuite, nous créerons une carte à partir du modèle par défaut (identique à celui défini dans la section ci-dessus) :

```python
card_data = ModelCardData(language='en', license='mit', library_name='keras')
card = ModelCard.from_template(
    card_data,
    model_id='my-cool-model',
    model_description="this model does this and that",
    developers="Nate Raw",
    repo="https://github.com/huggingface/huggingface_hub",
)
```

Enfin, nous le pousserons sur le hub

```python
card.push_to_hub(repo_id)
```

Vous pouvez consulter la carte résultante [ici](https://huggingface.co/nateraw/hf-hub-modelcards-pr-test/blob/main/README.md).

Si vous souhaitez plutôt publier une carte sous forme de demande de tirage, il vous suffit d’indiquer `create_pr=True` lors de l’appel de `push_to_hub` :

```python
card.push_to_hub(repo_id, create_pr=True)
```

Un PR résultant créé à partir de cette commande peut être consulté [ici](https://huggingface.co/nateraw/hf-hub-modelcards-pr-test/discussions/3).

## Mettre à jour les métadonnées

Dans cette section, nous verrons quelles sont les métadonnées présentes dans les cartes de dépôt et comment les mettre à jour.

`metadata` désigne une table de hachage (ou un contexte clé-valeur) qui fournit des informations de haut niveau sur un modèle, un jeu de données ou un Space. Ces informations peuvent inclure des détails tels que le `pipeline type`, le `model_id` ou la `model_description` du modèle. Pour plus de détails, vous pouvez consulter ces guides : [Model Card](https://huggingface.co/docs/hub/model-cards#model-card-metadata), [Dataset Card](https://huggingface.co/docs/hub/datasets-cards#dataset-card-metadata) et [Spaces Settings](https://huggingface.co/docs/hub/spaces-settings#spaces-settings). Voyons maintenant quelques exemples sur la manière de mettre à jour ces métadonnées.

Commençons par un premier exemple :

```python
>>> from huggingface_hub import metadata_update
>>> metadata_update("username/my-cool-model", {"pipeline_tag": "image-classification"})
```

Avec ces deux lignes de code, vous mettrez à jour les métadonnées pour définir un nouveau `pipeline_tag`.

Par défaut, vous ne pouvez pas mettre à jour une clé qui existe déjà sur la carte. Si vous souhaitez le faire, vous devez passer explicitement `overwrite=True` :

```python
>>> from huggingface_hub import metadata_update
>>> metadata_update("username/my-cool-model", {"pipeline_tag": "text-generation"}, overwrite=True)
```

Il arrive souvent que vous souhaitiez proposer des modifications à un dépôt pour lequel vous n'avez pas les droits d'écriture. Vous pouvez le faire en créant une PR sur ce dépôt, ce qui permettra aux propriétaires de passer en revue et de fusionner vos suggestions.

```python
>>> from huggingface_hub import metadata_update
>>> metadata_update("someone/model", {"pipeline_tag": "text-classification"}, create_pr=True)
```

## Inclure les résultats d'évaluation

Pour inclure les résultats d'évaluation dans les métadonnées `model-index`, vous pouvez passer un [EvalResult](/docs/huggingface_hub/v2.4.0/fr/package_reference/cards#huggingface_hub.EvalResult) ou une liste de `EvalResult` avec vos résultats d'évaluation associés. En interne, le `model-index` est créé lorsque vous appelez `card.data.to_dict()`. Pour plus d'informations sur le fonctionnement, consultez [cette section de la documentation du Hub](https://huggingface.co/docs/hub/models-cards#evaluation-results).

> [!TIP]
> Notez que l'utilisation de cette fonction nécessite d'inclure l'attribut `model_name` dans [ModelCardData](/docs/huggingface_hub/v2.4.0/fr/package_reference/cards#huggingface_hub.ModelCardData).

```python
card_data = ModelCardData(
    language='en',
    license='mit',
    model_name='my-cool-model',
    eval_results = EvalResult(
        task_type='image-classification',
        dataset_type='beans',
        dataset_name='Beans',
        metric_type='accuracy',
        metric_value=0.7
    )
)

card = ModelCard.from_template(card_data)
print(card.data)
```

Le `card.data` résultant doit ressembler à ceci :

```
language: en
license: mit
model-index:
- name: my-cool-model
  results:
  - task:
      type: image-classification
    dataset:
      name: Beans
      type: beans
    metrics:
    - type: accuracy
      value: 0.7
```

Si vous avez plusieurs résultats d'évaluation à partager, passez simplement une liste de `EvalResult` :

```python
card_data = ModelCardData(
    language='en',
    license='mit',
    model_name='my-cool-model',
    eval_results = [
        EvalResult(
            task_type='image-classification',
            dataset_type='beans',
            dataset_name='Beans',
            metric_type='accuracy',
            metric_value=0.7
        ),
        EvalResult(
            task_type='image-classification',
            dataset_type='beans',
            dataset_name='Beans',
            metric_type='f1',
            metric_value=0.65
        )
    ]
)
card = ModelCard.from_template(card_data)
card.data
```

Ce qui devrait vous laisser avec le `card.data` suivant :

```
language: en
license: mit
model-index:
- name: my-cool-model
  results:
  - task:
      type: image-classification
    dataset:
      name: Beans
      type: beans
    metrics:
    - type: accuracy
      value: 0.7
    - type: f1
      value: 0.65
```