F1, NDCG : vérifier ce que calcule réellement une métrique

Par Elisha Bajemon, Ingénieur IA chez TW3 Partners. Dernière mise à jour : 5 novembre 2026.

En bref

Auditer un indicateur d’apprentissage automatique consiste à vérifier ce qu’il mesure et comment il est calculé, avant de s’en servir pour choisir un modèle. Pour une direction, la question est de savoir quelles erreurs le résultat permet d’apprécier. Nous recommandons de demander une définition écrite, les données évaluées et les règles de calcul avec chaque résultat soumis à décision. Un indicateur, aussi appelé métrique, doit pouvoir être relu à partir de ces éléments. Pour évaluer l’ordre des résultats, la documentation scikit-learn de NDCG, sans date décrit un score entre 0 et 1, sous les conditions précisées dans le corps. Pour évaluer l’attribution de catégories, elle décrit F1, également sans date de publication indiquée. Le corps de cet article explicite ces notions et propose une méthode de revue applicable à une équipe data.

1. Que faut-il demander avant de comparer des modèles ?

Demandez une définition de la mesure et un périmètre d’évaluation avec chaque résultat. Pour TW3, ce dossier doit permettre de relier la décision envisagée aux erreurs que l’équipe cherche à mesurer. Il peut s’agir de vérifier l’attribution de catégories ou d’évaluer l’ordre dans lequel des éléments sont proposés.

La distinction est concrète dans la documentation scikit-learn, sans date : f1_score reçoit des catégories attendues et des catégories prédites ; ndcg_score utilise des pertinences de référence et des scores qui déterminent un classement. La revue commence donc par le sens des données fournies au calcul.

Consignez l’origine des références, les observations retenues et les exclusions. Faites préciser quelle version du modèle a produit les sorties et quelle version du calcul les a évaluées. Joignez les paramètres au tableau de résultats pour permettre au relecteur de refaire la comparaison dans les mêmes conditions.

Nous recommandons de formuler la décision attendue avant de commenter une variation de score. L’équipe peut ensuite expliquer pourquoi la mesure retenue convient à cet usage. Cette étape relève de la méthode proposée par le cabinet ; elle ne constitue pas un résultat d’évaluation d’un système particulier.

2. Comment vérifier la formule du F1 ?

Vérifiez que le F1 résulte des prédictions et des catégories attendues, selon la formule annoncée. La documentation scikit-learn de la précision et du rappel, sans date définit la précision comme la part des vrais positifs parmi les éléments prédits positifs. Le rappel est la part des vrais positifs parmi les éléments réellement positifs.

Pour lire ces définitions, un vrai positif est un élément correctement reconnu comme appartenant à la catégorie recherchée. Un faux positif est attribué à cette catégorie à tort. Un faux négatif appartient à cette catégorie, mais le modèle ne l’a pas reconnu comme tel. La précision rapporte les vrais positifs à la somme des vrais et faux positifs ; le rappel les rapporte à la somme des vrais positifs et des faux négatifs.

Selon la documentation officielle de f1_score, sans date, F1 est la moyenne harmonique de la précision et du rappel, avec des contributions égales. Sa formule s’écrit :

F1 = 2 × TP / (2 × TP + FP + FN)

TP désigne les vrais positifs, FP les faux positifs et FN les faux négatifs. Dans cette fonction, y_true contient les valeurs attendues et y_pred les prédictions du classificateur.

Pour la revue, demandez les comptes utilisés dans cette formule et leur correspondance avec les données évaluées. Faites expliquer les erreurs en termes métier avant d’examiner la moyenne. Conservez la précision et le rappel à côté du F1 dans le dossier de décision : le relecteur dispose ainsi des termes qui entrent dans sa définition.

3. Quels paramètres peuvent changer le sens d’un F1 ?

Les classes retenues, leur mode de regroupement et le traitement des cas indéfinis font partie de la définition à vérifier. La documentation scikit-learn de f1_score, sans date décrit ces conventions.

En classification binaire, pos_label désigne la classe positive évaluée lorsque le mode de moyenne est binary. Pour plusieurs classes, micro rassemble les comptes de vrais positifs, faux positifs et faux négatifs avant le calcul. Le mode macro calcule une moyenne non pondérée des mesures par classe ; weighted pondère ces mesures par le nombre d’occurrences réelles de chaque classe. Le paramètre labels fixe les classes retenues lorsque average diffère de binary.

Dans le dossier de revue, inscrivez le mode choisi en toutes lettres et explicitez sa conséquence pour le métier. Demandez notamment si l’on veut donner le même poids à chaque catégorie dans la moyenne ou tenir compte de leur fréquence. Conservez aussi la liste des classes incluses, afin de rendre le périmètre de comparaison visible.

F1 est indéfini lorsque vrais positifs, faux positifs et faux négatifs sont tous absents. La fonction prévoit alors une convention réglée par zero_division. Si cette option vaut np.nan, les valeurs concernées sont exclues de la moyenne.

Documentez la convention retenue et signalez les classes concernées dans le rapport. Pour comparer des versions d’un modèle, commencez par vérifier que ces choix de calcul ont été conservés ou que leur changement est expliqué.

4. Que faut-il contrôler dans une mesure NDCG ?

Contrôlez les pertinences de référence, l’ordre évalué et la profondeur du classement. La documentation officielle de ndcg_score de scikit-learn, sans date décrit une somme des pertinences réelles, ordonnées selon les scores prédits et affectées d’une décote logarithmique. Cette décote réduit la contribution selon le rang. La somme obtenue, appelée DCG, est divisée par le meilleur gain possible, appelé IDCG, correspondant au classement idéal.

Les entrées jouent des rôles distincts. y_true porte les pertinences de référence ; y_score porte les scores qui déterminent l’ordre évalué. La documentation décrit un résultat compris entre 0 et 1, tout en précisant que des pertinences négatives peuvent le faire sortir de cet intervalle.

Le paramètre k limite le calcul aux premiers éléments du classement ; sans limite renseignée, toutes les sorties sont considérées. Les égalités entre scores demandent également une convention : la fonction moyenne les ex æquo par défaut. Activer ignore_ties suppose leur absence dans les scores utilisés pour ordonner les éléments.

Pour la revue, faites expliciter qui a défini les pertinences et selon quels critères. Demandez de conserver les scores qui ont déterminé l’ordre, avec les valeurs de référence correspondantes. Reliez le choix de la profondeur à l’usage prévu : quelle partie du classement entre dans la décision ?

Avant de comparer des résultats, vérifiez que les évaluations utilisent les mêmes conventions de pertinence et de profondeur. Faites apparaître le traitement des ex æquo dans la spécification. Cette fiche de calcul donne au relecteur un point de départ précis pour examiner une différence entre modèles.

5. Comment un nom historique peut-il masquer une autre formule ?

Un identifiant conservé dans les données peut désigner une formule différente de celle attendue sous ce nom. Elisha Bajemon et André-Louis Rochet l’explicitent dans Scoring Without the Engine, prépublication déposée sur arXiv le 7 septembre 2026. Leur spécification du mode regex_only fournit une illustration de ce contrôle documentaire.

Le champ citation_f1 combine arithmétiquement des termes de présence et de couverture de citations repérées par motifs. Les lettres P et R y ont des définitions propres, distinctes de la précision et du rappel d’un classificateur. En présence de citations, Q représente leur confiance moyenne mise à l’échelle. La formule décrite dans les annexes de cette prépublication du 7 septembre 2026 est :

citation_f1 = 0,50 × P + 0,30 × R + 0,20 × Q

Le champ ndcg_score est, lui, un composite de qualité de la structure des titres. Le rapport classique DCG/IDCG est calculé et enregistré comme métadonnée de référence, mais reste hors de sa formule. Les auteurs maintiennent ces identifiants pour la compatibilité avec les données diffusées.

Ces écarts sont déclarés dans la spécification. Le README de TW3-Partners-OS, sans date de publication indiquée, à la version référencée précise que le scoreur ayant produit les captures est absent du dépôt public. Cette lecture porte donc sur les définitions publiées. La pratique à retenir pour un audit est de suivre la formule jusqu’à la valeur effectivement utilisée, en distinguant les données de référence des termes agrégés.

6. Comment consigner une métrique pour permettre sa revue ?

Consignez la définition, les paramètres et l’usage du résultat dans une fiche de mesure jointe à l’évaluation. Le tableau suivant propose une trame de travail TW3 fondée sur les paramètres décrits dans les documentations scikit-learn de F1 et de NDCG, sans date de publication indiquée.

Ajoutez à cette fiche la version de la bibliothèque, la configuration exécutée et le périmètre des données. Identifiez aussi l’emplacement où le résultat est repris : rapport de comparaison, règle de sélection ou indicateur agrégé. Le relecteur doit pouvoir retrouver ce passage sans avoir à déduire l’usage d’un nom de colonne.

Nous recommandons de rendre séparément la conclusion sur le calcul et celle sur l’usage de la mesure. Pour la première, rapprochez les entrées archivées du résultat obtenu avec la configuration annoncée. Pour la seconde, expliquez pourquoi les erreurs prises en compte correspondent à la décision envisagée. Inscrivez toute réserve à côté de la conclusion concernée, avec la vérification restant à mener et son responsable.

FAQ

Quelles pièces demander avec un F1 ?
La trame proposée ici comprend les catégories attendues et prédites, les comptes d’erreurs et les paramètres de calcul. Joignez le périmètre des données et la version de la configuration exécutée au résultat présenté.

Comment choisir entre les moyennes macro et weighted ?
Selon la documentation scikit-learn de F1, sans date, macro donne le même poids aux mesures par classe ; weighted les pondère par les occurrences réelles. Faites justifier ce choix au regard des catégories que la décision doit prendre en compte.

Que déclarer quand un F1 est indéfini ?
Déclarez la valeur renvoyée et son traitement dans la moyenne. La documentation scikit-learn de F1, sans date prévoit zero_division ; son option np.nan exclut les valeurs concernées de la moyenne.

La profondeur du classement fait-elle partie de la définition de NDCG ?
La documentation scikit-learn de NDCG, sans date prévoit le paramètre k pour limiter le calcul aux premiers éléments. Indiquez sa valeur avec le résultat afin que le périmètre évalué soit explicite.

Comment conclure un audit de métrique ?
Présentez la concordance entre la définition et le calcul, puis l’usage que l’équipe entend faire du résultat. La proposition de TW3 consiste à documenter ces conclusions séparément, avec les pièces qui permettent leur revue.

Pour aller plus loin

• Trois erreurs trouvées et corrigées avant publication : l’audit interne d’un papier de recherche appliquée
• Valider un indicateur bon marché qui remplace une mesure coûteuse : le protocole de Scoring Without the Engine
• Variables quasi constantes en machine learning : repérer un artefact d’extraction
• Importance des variables LightGBM : que signifie le gain affiché ?

Sources

• scikit-learn, documentation officielle de f1_score, sans date, consultée le 9 octobre 2026.
• scikit-learn, documentation officielle de precision_recall_fscore_support, sans date, consultée le 9 octobre 2026.
• scikit-learn, documentation officielle de ndcg_score, sans date, consultée le 9 octobre 2026.
• Elisha Bajemon et André-Louis Rochet, TW3 Partners, Scoring Without the Engine: Validating a Deterministic, Manipulation-Resistant Content Score for Generative Engines, End to End, prépublication déposée sur arXiv le 7 septembre 2026. Texte intégral et annexes, consultés le 9 octobre 2026.
• TW3-Partners-OS, README, version cd755f5c590bb559692e0192afc9128a0f644262, sans date de publication indiquée, consulté le 9 octobre 2026.