Fiches de modèle

Qu'est-ce que les Model Cards ?

Les fiches de modèle sont des fichiers qui accompagnent les modèles et fournissent des informations pratiques. En interne, les fiches de modèle sont de simples fichiers Markdown avec des métadonnées supplémentaires. Les fiches de modèle sont essentielles pour la découvrabilité, la reproductibilité et le partage ! Vous pouvez trouver une fiche de modèle sous forme de fichier README.md dans n’importe quel dépôt de modèle.

La carte du modèle doit décrire :

• le modèle
• ses usages prévus et ses limites potentielles, y compris les biais et les considérations éthiques, comme détaillé dans Mitchell, 2018
• les paramètres d'entraînement et les informations expérimentales (vous pouvez intégrer ou lier une plateforme de suivi des expériences pour référence)
• quels jeux de données ont été utilisés pour entraîner votre modèle
• les résultats d'évaluation du modèle

Le modèle de carte de modèle est disponible ici.

La manière de remplir chaque section de la carte de modèle est décrite dans la carte de modèle annotée.

Les fiches de modèle sur le Hub comportent deux parties clés, avec des informations qui se chevauchent :

• Métadonnées
• Descriptions textuelles

Métadonnées de la carte de modèle

Un dépôt de modèle affiche son README.md sous forme de carte de modèle. La carte de modèle est un fichier Markdown avec une section YAML en haut qui contient des métadonnées sur le modèle.

Les métadonnées que vous ajoutez à la carte du modèle facilitent sa découverte et son utilisation. Par exemple :

• Permettre aux utilisateurs de filtrer les modèles sur https://huggingface.co/models.
• Affichage de la licence du modèle.
• L’ajout de jeux de données aux métadonnées insère un message Datasets used to train: sur votre page de modèle et lie les jeux de données correspondants, s’ils sont disponibles sur le Hub.

Les identifiants de jeu de données et de langue sont ceux répertoriés sur les pages Datasets et Languages.

Ajouter des métadonnées à votre carte de modèle

Il existe plusieurs façons d'ajouter des métadonnées à votre carte de modèle, notamment :

• Utilisation de l'interface utilisateur des métadonnées
• Modifier directement la section YAML du fichier README.md
• Via la bibliothèque Python huggingface_hub, consultez la documentation pour plus de détails.

De nombreuses bibliothèques avec intégration au Hub ajoutent automatiquement des métadonnées à la carte du modèle lors de son téléversement.

Utilisation de l'interface utilisateur des métadonnées

Vous pouvez ajouter des métadonnées à votre carte de modèle à l’aide de l’interface de métadonnées. Pour accéder à cette interface, rendez-vous sur la page du modèle et cliquez sur le bouton Edit model card situé dans le coin supérieur droit de la carte de modèle. Un éditeur s’ouvre alors, affichant le fichier README.md de la carte de modèle ainsi qu’une interface pour modifier les métadonnées.

Cette interface vous permet d’ajouter des métadonnées clés à votre carte de modèle, et de nombreux champs seront complétés automatiquement en fonction des informations que vous fournissez. L’utilisation de l’interface est la méthode la plus simple pour ajouter des métadonnées à votre carte de modèle, mais elle ne prend pas en charge tous les champs de métadonnées. Si vous souhaitez ajouter des métadonnées non prises en charge par l’interface, vous pouvez modifier directement la section YAML du fichier README.md.

Modification de la section YAML du fichier README.md

Vous pouvez également modifier directement la section YAML du fichier README.md. Si la carte du modèle ne comporte pas encore de section YAML, vous pouvez en ajouter une en insérant trois --- en haut du fichier, puis en incluant toutes les métadonnées pertinentes, et en fermant la section avec un autre groupe de --- comme dans l’exemple ci-dessous :

---
language: 
  - "List of ISO 639-1 code for your language"
  - lang1
  - lang2
thumbnail: "url to a thumbnail used in social sharing"
tags:
- tag1
- tag2
license: "any valid license identifier"
datasets:
- dataset1
- dataset2
base_model: "base model Hub identifier"
---

Vous pouvez consulter la spécification détaillée des métadonnées de la carte du modèle ici.

Spécifier une bibliothèque

Vous pouvez spécifier les bibliothèques prises en charge dans la section métadonnées de la carte du modèle. En savoir plus sur nos bibliothèques prises en charge ici. La bibliothèque sera spécifiée dans l'ordre de priorité suivant :

1. Spécifier library_name dans la carte du modèle (recommandé si votre modèle n’est pas un modèle transformers). Ces informations peuvent être ajoutées via l’interface de métadonnées ou directement dans la section YAML de la carte du modèle :

library_name: flair

2. Avoir un tag portant le nom d'une bibliothèque prise en charge

tags:
- flair

Si ce n’est pas spécifié, le Hub tentera de détecter automatiquement le type de bibliothèque. Toutefois, cette approche est déconseillée, et les créateurs de dépôts doivent utiliser library_name explicitement autant que possible.

1. En examinant la présence de fichiers tels que *.nemo ou *.mlmodel, le Hub peut déterminer si un modèle provient de NeMo ou de CoreML.
2. Par le passé, si rien n’était détecté et qu’un fichier config.json était présent, on supposait que la bibliothèque était transformers. Pour les dépôts de modèles créés après août 2024, ce n’est plus le cas, il faut donc définir explicitement library_name: transformers.

Spécifier un modèle de base

Si votre modèle est un fine-tune, un adaptateur ou une version quantifiée d’un modèle de base, vous pouvez spécifier le modèle de base dans la section métadonnées de la carte du modèle. Ces informations peuvent également servir à indiquer si votre modèle est une fusion de plusieurs modèles existants. Ainsi, le champ base_model peut être soit un identifiant de modèle unique, soit une liste d’un ou plusieurs base_models (spécifiés par leurs identifiants Hub).

base_model: HuggingFaceH4/zephyr-7b-beta

Cette métadonnée sera utilisée pour afficher le modèle de base sur la page du modèle. Les utilisateurs peuvent également utiliser ces informations pour filtrer les modèles par modèle de base ou pour trouver les modèles dérivés d'un modèle de base spécifique :

Pour un modèle affiné :

Pour un adaptateur (LoRA, PEFT, etc.) :

Pour une version quantifiée d'un autre modèle :

Pour une fusion de deux modèles ou plus :

Dans le cas de fusion, vous spécifiez une liste de deux base_models ou plus :

base_model:
- Endevor/InfinityRP-v1-7B
- l3utterfly/mistral-7b-v0.1-layla-v4

Le Hub infère le type de relation entre le modèle actuel et le modèle de base ("adapter", "merge", "quantized", "finetune"), mais vous pouvez également le définir explicitement si nécessaire : base_model_relation: quantized par exemple.

Spécifier une nouvelle version

Si une nouvelle version de votre modèle est disponible sur le Hub, vous pouvez la spécifier dans un champ new_version.

Par exemple, sur l3utterfly/mistral-7b-v0.1-layla-v3 :

new_version: l3utterfly/mistral-7b-v0.1-layla-v4

Cette métadonnée sera utilisée pour afficher un lien vers la dernière version d’un modèle sur la page du modèle. Si le modèle lié dans new_version possède également un champ new_version, la toute dernière version sera toujours affichée.

Spécifier un jeu de données

Vous pouvez spécifier les jeux de données utilisés pour entraîner votre modèle dans la section métadonnées de la carte du modèle. Les jeux de données seront affichés sur la page du modèle et les utilisateurs pourront filtrer les modèles par jeu de données. Vous devez utiliser l’identifiant du jeu de données du Hub, qui est le même que le nom du dépôt du jeu de données, en tant qu’identifiant :

datasets:
- stanfordnlp/imdb
- HuggingFaceFW/fineweb

Spécifier un bucket

Vous pouvez spécifier les bacs de stockage liés à votre modèle dans la section métadonnées de la carte du modèle. Les bacs seront affichés sous forme d’étiquettes sur la page du modèle et les pages des bacs liés afficheront en retour le modèle. Vous devez utiliser l’identifiant de bac du Hub, qui est identique au nom du dépôt du bac :

buckets:
- my-org/my-bucket
- my-org/another-bucket

Spécifier une tâche (pipeline_tag)

Vous pouvez spécifier le pipeline_tag dans les métadonnées de la carte du modèle. Le pipeline_tag indique le type de tâche pour laquelle le modèle est destiné. Cette étiquette sera affichée sur la page du modèle et les utilisateurs peuvent filtrer les modèles sur le Hub par tâche. Cette étiquette est également utilisée pour déterminer quel widget utiliser pour le modèle et quelles API utiliser en arrière-plan.

Pour les modèles transformers, le tag de pipeline est inféré automatiquement à partir du fichier config.json du modèle, mais vous pouvez le remplacer dans les métadonnées de la carte modèle si nécessaire. La modification de ce champ dans l’interface utilisateur des métadonnées garantit que le tag de pipeline est valide. D’autres bibliothèques avec une intégration au Hub ajoutent également automatiquement le tag de pipeline aux métadonnées de la carte modèle.

Spécifier une licence

Vous pouvez spécifier la licence dans la section métadonnées de la carte du modèle. La licence sera affichée sur la page du modèle et les utilisateurs pourront filtrer les modèles par licence. En utilisant l'interface utilisateur des métadonnées, vous verrez un menu déroulant des licences les plus courantes.

Si nécessaire, vous pouvez également spécifier une licence personnalisée en ajoutant other comme valeur de licence et en indiquant le nom et un lien vers la licence dans les métadonnées.

# Example from https://huggingface.co/coqui/XTTS-v1
---
license: other
license_name: coqui-public-model-license
license_link: https://coqui.ai/cpml
---

Si la licence n'est pas disponible via une URL, vous pouvez lier un fichier LICENSE stocké dans le dépôt du modèle.

Résultats d'évaluation

Vous pouvez spécifier les résultats d’évaluation de votre modèle de manière structurée dans les métadonnées de la carte du modèle. Les résultats sont analysés par le Hub et affichés dans un widget sur la page du modèle. Voici un exemple de l’apparence pour le modèle bigcode/starcoder :

La spécification de métadonnées initiale était basée sur la spécification model-index de Papers with code. Cela nous a permis d’indexer directement les résultats dans les classements de Papers with code lorsque cela était approprié. Il était également possible de lier la source à partir de laquelle les résultats d’évaluation ont été calculés.

NOUVEAU : Nous avons un nouveau format de métadonnées plus simple pour les résultats d'évaluation. Consultez-le dans la page de documentation dédiée.

Voici un exemple partiel d’un model-index qui décrivait le score de 01-ai/Yi-34B sur le benchmark ARC. Le résultat provenait du Open LLM Leaderboard, qui est défini comme la source :

---
model-index:
  - name: Yi-34B
    results:
      - task:
          type: text-generation
        dataset:
          name: ai2_arc
          type: ai2_arc
        metrics:
          - name: AI2 Reasoning Challenge (25-Shot)
            type: AI2 Reasoning Challenge (25-Shot)
            value: 64.59
        source:
          name: Open LLM Leaderboard
          url: https://huggingface.co/spaces/open-llm-leaderboard/open_llm_leaderboard
---

Pour plus de détails sur la façon de formater ces données, consultez les spécifications de la carte de modèle.

Émissions de CO2

La carte du modèle est également un excellent endroit pour afficher des informations sur l'impact CO₂ de votre modèle. Consultez notre guide sur le suivi et la déclaration des émissions de CO₂ pour en savoir plus.

Lier un article

Si la carte du modèle inclut un lien vers une page Paper (sur HF ou un résumé/PDF Arxiv), le Hugging Face Hub extrait l’identifiant arXiv et l’inclut dans les étiquettes du modèle avec le format arxiv:<PAPER ID>. En cliquant sur l’étiquette, vous pouvez :

• Visiter la page du Paper
• Filtrer les autres modèles du Hub qui citent le même article.

En savoir plus sur les pages Paper ici.

Texte de la carte de modèle

Les détails sur la manière de remplir la partie lisible par l’humain de la carte modèle (afin qu’elle puisse être imprimée, découpée et collée, etc.) sont disponibles dans la Carte modèle annotée.

FAQ

Comment les étiquettes de modèle sont-elles déterminées ?

Chaque page de modèle répertorie tous les tags du modèle dans l’en-tête de la page, sous le nom du modèle. Ils sont principalement calculés à partir des métadonnées de la carte du modèle, bien que certains soient ajoutés automatiquement, comme décrit dans Activer un widget.

Puis-je ajouter des balises personnalisées à mon modèle ?

Oui, vous pouvez ajouter des balises personnalisées à votre modèle en les ajoutant au champ tags des métadonnées de la carte du modèle. L’interface des métadonnées suggère certaines balises populaires, mais vous pouvez ajouter n’importe quelle balise. Par exemple, vous pouvez indiquer que votre modèle est axé sur la finance en ajoutant une balise finance.

Comment indiquer que mon modèle n'est pas adapté à tous les publics

Vous pouvez ajouter le tag not-for-all-audiences aux métadonnées de votre carte de modèle. Lorsque ce tag est présent, un message s’affiche sur la page du modèle pour indiquer que celui-ci ne s’adresse pas à tous les publics. Les utilisateurs peuvent cliquer sur ce message pour afficher la carte de modèle.

Comment afficher des images différentes pour le mode sombre et le mode clair ?

Vous pouvez afficher différentes versions d'une image, optimisées pour chaque thème. Cette fonctionnalité est particulièrement utile pour les logos, les diagrammes ou les captures d'écran qui nécessitent des schémas de couleurs distincts afin de préserver la visibilité et l'esthétique en modes clair et sombre. Pour utiliser cette fonctionnalité, vous devez fournir les deux versions de votre image.

Pour les images téléversées via l’éditeur Markdown

Lorsque vous téléchargez une image directement depuis l’éditeur Markdown (en utilisant le glisser-déposer), ajoutez le fragment d’URI #hf-light-mode-only ou #hf-dark-mode-only à la fin de l’URL de l’image pour spécifier le thème dans lequel elle doit s’afficher :

Image only displays when viewing in light mode
![Logo](https://huggingface.co/proxy/cdn-uploads.huggingface.co/production/uploads/logo-light.png#hf-light-mode-only)

Image only displays when viewing in dark mode
![Logo](https://huggingface.co/proxy/cdn-uploads.huggingface.co/production/uploads/logo-dark.png#hf-dark-mode-only)

Pour les images déjà hébergées

Si vous souhaitez référencer des images déjà hébergées sans les réenvoyer, utilisez les balises HTML <img> avec les classes Tailwind CSS suivantes pour spécifier le thème dans lequel elles doivent s’afficher :

// Image only displays when viewing in dark mode
<img class="hidden dark:block" src="https://hf.co/logo-dark.png" alt="Logo" />

// Image only displays when viewing in light mode
<img class="dark:hidden" src="https://hf.co/logo-light.png" alt="Logo" />

Puis-je écrire du LaTeX dans ma carte de modèle ?

Oui ! Le Hub utilise la bibliothèque de mise en forme mathématique KaTeX pour afficher les formules mathématiques côté serveur avant l’analyse du Markdown.

Vous devez utiliser les délimiteurs suivants :

• $$ ... $$ pour le mode d’affichage
• \\(...\\) pour le mode en ligne (pas d'espace entre les barres obliques et la parenthèse).

Ensuite, vous pourrez écrire : $$\LaTeX$$ $$\mathrm{MSE} = \left(\frac{1}{n}\right)\sum_{i=1}^{n}(y_{i} - x_{i})^{2}$$ $$E=mc^2$$