Documenter les jeux de données et les modèles : fiches descriptives, déclarations de données et fiches de modèle

Trois standards de documentation se sont imposés pour les données d'apprentissage automatique : les déclarations de données et les fiches descriptives pour le jeu de données, les fiches de modèle pour ce que vous entraînez dessus. Ils se recoupent largement et aucun n'est facultatif si vous voulez que les données soient jugées fiables et réutilisées. Ce guide est une référence sur ce que chacun couvre et quand y recourir. Pour un parcours narratif de la rédaction de l'un d'eux, voyez le billet complémentaire sur comment documenter votre jeu de données d'annotation ; cette page est la comparaison des standards.

Pourquoi une documentation structurée plutôt qu'un README

Un jeu de données annoté sans documentation vieillit mal. Six mois plus tard, personne ne peut dire comment il a été échantillonné, qui l'a étiqueté ni ce qu'une étiquette était censée signifier, si bien que les données deviennent une boîte noire à laquelle on fait aveuglément confiance ou que l'on jette. Deux coûts précis reviennent : l'irreproductibilité (vous ne pouvez ni reconstruire le jeu de données ni expliquer un écart sans la méthode d'échantillonnage, la version des consignes et le panel d'annotateurs) et le biais caché (les étiquettes issues d'un panel restreint et non documenté charrient des angles morts qui restent invisibles jusqu'à ce qu'ils fassent surface en production). Les cadres ci-dessous existent pour rendre lisibles le qui et le comment avant que l'un ou l'autre ne pose problème.

Les trois standards

Chaque cadre vise un artefact et un public différents, mais ils ont été conçus pour s'emboîter.

Les déclarations de données (Bender and Friedman, 2018) sont le schéma propre au TAL. Elles caractérisent un jeu de données linguistique, la justification de la curation, la variété linguistique et ses locuteurs, la démographie des annotateurs, les consignes et l'usage prévu, afin qu'un lecteur puisse juger de la façon dont les résultats se généraliseront et des populations que les données sous-représentent. Recourez à une déclaration de données lorsque les données sont du texte et que la variété linguistique compte.

Les fiches descriptives pour jeux de données (Gebru et al., 2021) sont la version généraliste, empruntée à l'électronique, où chaque composant est livré avec une fiche descriptive. Elles posent un ensemble de questions standard couvrant la motivation, la composition, le processus de collecte, le prétraitement, les usages recommandés et la maintenance. Utilisez une fiche descriptive pour tout jeu de données d'apprentissage automatique, texte ou non ; elle recoupe largement une déclaration de données, de sorte que sur un jeu de données linguistique vous choisissez en réalité autour de quel ensemble de questions vous organiser, sans faire les deux à partir de zéro.

Les fiches de modèle (Mitchell et al., 2019) documentent le modèle, pas les données : son usage prévu et, surtout, ses performances ventilées par groupes démographiques et autres plutôt que sous forme d'un chiffre agrégé unique. Une fiche de modèle est l'endroit où un problème d'équité devient visible.

Les trois forment une chaîne. Une fiche descriptive ou une déclaration de données documente les données ; une fiche de modèle documente ce qui a été construit dessus ; et la section démographie des annotateurs de la première est exactement ce qui rend interprétable l'évaluation par groupes de la dernière. Documentez bien l'annotation et vous aurez déjà parcouru l'essentiel du chemin vers une fiche de modèle défendable.

La reproductibilité est le quatrième pilier

Documentation et reproductibilité sont le même objectif sous deux angles. Pineau et al. (2021) ont rendu compte du programme de reproductibilité de NeurIPS et l'ont condensé en une liste de vérification de reproductibilité : indiquez les données exactes, les étapes de collecte et de prétraitement, la configuration d'évaluation et assez de détails pour réexécuter le travail. Pour un projet d'annotation en particulier, les faits critiques pour la reproductibilité sont ceux qu'une fiche descriptive demande déjà : comment les éléments ont été échantillonnés, quelle version des consignes a été utilisée, qui a annoté et comment le désaccord a été traité. Si vous pouvez répondre à cela, le jeu de données est à la fois documenté et reproductible ; sinon, c'est une lacune à combler avant la publication, pas après.

Une liste de vérification pour la publication

Avant de publier, assurez-vous de pouvoir répondre :

• Comment les éléments ont-ils été échantillonnés, et à partir de quelle source ?
• De quelle variété linguistique s'agit-il, et qui a rédigé le texte source ?
• Qui l'a annoté, combien de personnes, et quelle est la composition démographique du panel ?
• Quelles consignes ont-ils suivies, et quelle version ?
• Le désaccord a-t-il été agrégé en une étiquette de référence ou conservé sous forme de distribution ? Rendez compte de l'accord dans les deux cas.
• À quoi ce jeu de données sert-il, et à quoi ne devrait-il pas servir ?

Le faire dans Potato

L'essentiel de la documentation d'un jeu de données existe déjà sous forme d'artefacts du projet, vous ne partez donc pas d'une page blanche. La configuration est de la documentation : le YAML consigne les schémas, les jeux d'étiquettes et la structure de la tâche, versionnés à côté des données, et les instructions que vous avez rédigées sont la section des consignes mot pour mot. Si vous avez mené une phase d'étude préalable, la démographie des annotateurs est déjà stockée par annotateur ; agrégez-la en distributions pour la section démographie des annotateurs. Et l'export conserve l'annotateur et l'horodatage sur chaque étiquette, si bien que la provenance voyage avec les données au lieu d'être supprimée :

{
  "id": "doc_001",
  "annotations": { "sentiment": "positive" },
  "annotator": "user_1",
  "timestamp": "2024-01-15T10:30:00Z"
}

Lorsque vous publiez sur le Hub, générez la fiche du jeu de données comme dernière étape de l'export et remplissez ses sections à partir de la configuration, des consignes et de la démographie d'étude préalable dont vous disposez déjà.

Pour aller plus loin

• Comment documenter votre jeu de données d'annotation, le parcours narratif avec une déclaration de données travaillée.
• Collecter la démographie des annotateurs de façon responsable, pour réussir la section démographie des annotateurs.
• Rédiger des consignes d'annotation, qui font aussi office de section des consignes.
• Exporter des annotations pour le ML, pour extraire proprement étiquettes et métadonnées.