Créer et partager des Model Cards

La bibliothèque huggingface_hub fournit une interface Python pour créer, partager et mettre à jour des Model Cards. Consultez la page de documentation dédiée 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(). Ici, nous chargeons la carte de nateraw/vit-base-beans.

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 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.

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() 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.

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 :

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 dans 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(). 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, qui est une fiche de modèle complète avec de nombreuses sections que vous pouvez remplir. En interne, il utilise Jinja2 pour remplir un fichier de modèle.

Notez que vous devrez avoir Jinja2 installé pour utiliser from_template. Vous pouvez le faire avec pip install Jinja2.

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()), vous pouvez pousser des cartes sur le Hub en appelant simplement ModelCard.push_to_hub(). Voyons comment faire…

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

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

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 allons le pousser sur le hub

card.push_to_hub(repo_id)

Vous pouvez consulter la carte résultante ici.

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 :

card.push_to_hub(repo_id, create_pr=True)

Un PR résultant créé à partir de cette commande peut être consulté ici.

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, Dataset Card et Spaces Settings. Voyons maintenant quelques exemples sur la manière de mettre à jour ces métadonnées.

Commençons par un premier exemple :

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

>>> 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.

>>> 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 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.

Notez que l'utilisation de cette fonction nécessite d'inclure l'attribut model_name dans ModelCardData.

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 :

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