Que vous indique un score de confiance ?
Le score confidence de V2 décrit les éléments qui étayent une prédiction donnée. Il ne mesure pas la précision globale du service et n’établit pas l’identité de genre d’une personne. Lisez-le avec confidence_kind, source et sample_count.
Ce guide présente le contrat de réponse V2 actuel et un protocole d’évaluation proposé. Les tests de contrat vérifient le comportement des réponses ; ils ne constituent pas une étude de précision fondée sur des étiquettes de référence indépendantes. La date de révision de cette page n’est pas une date de mesure de la précision.
Un profil distinct de la base de données, observé le 26 septembre 2026, indique le nombre de documents de chacune des deux collections d’après leurs métadonnées, ainsi que la cohérence numérique de 5 000 enregistrements tirés au hasard dans chaque collection. Ces contrôles ne comparent pas les prédictions à des étiquettes de référence indépendantes : ils ne fournissent donc aucun pourcentage de précision.
Deux types de confiance, deux significations
Calcul purement illustratif : si un enregistrement sélectionné stocke male = 90, female = 10 et total = 100, sa confidence vaut 0.9. Ces comptes inventés ne sont pas un résultat mesuré de GenderAPI.io et n’affirment pas que 90 % des personnes portant ce prénom s’identifient comme hommes.
Les comptes stockés ne sont pas présentés ici comme des observations indépendantes et représentatives. Le score de l’IA n’est pas calibré par rapport à ces comptes. Ne comparez pas les deux types comme des probabilités interchangeables et n’appliquez pas de seuil de confiance universel sans évaluation adaptée à votre usage.
| Champ de réponse | Résultat du jeu de données | Résultat de l’IA |
|---|---|---|
source | dataset | ai |
confidence_kind | observed_frequency lorsqu’un genre est renvoyé | model_reported lorsqu’un genre est renvoyé |
confidence | max(male, female) / total des comptes stockés lorsqu’un genre est renvoyé ; null en cas d’égalité exacte des comptes | Score déclaré par le modèle, supérieur à 0,5 et au plus égal à 1 lorsqu’un genre est renvoyé ; sinon null |
sample_count | Total stocké dans l’enregistrement sélectionné ; ce n’est pas la taille d’un échantillon d’évaluation | null ; aucun nombre d’échantillons du jeu de données n’est fourni |
match | Candidat sélectionné, méthode de correspondance et portée propre au pays ou globale | method vaut model_inference ; name, scope et country valent null |
Résultats inconnus, ambigus et erreurs
Il n’existe pas de seuil universel de rejet pour faible confiance applicable aux résultats du jeu de données. Le validateur des réponses de l’IA exige qu’un score non null soit supérieur à 0,5 : c’est une contrainte du contrat, pas une preuve de qualité prédictive. Conservez null au lieu de le convertir en confiance de zéro ou en catégorie de genre devinée.
| Résultat | Comportement de V2 | Traitement dans l’évaluation |
|---|---|---|
| Identifié | result_status vaut identified et gender vaut male ou female | Comparer à l’étiquette de référence et compter comme cas répondu |
| Inconnu | gender et confidence valent null ; result_status vaut unknown | Conserver dans l’échantillon éligible et compter séparément d’une prédiction erronée |
| Égalité dans le jeu de données | Des comptes male et female identiques produisent reason: ambiguous en mode jeu de données seul ; fallback peut remplacer ce résultat par un résultat de l’IA | Enregistrer le résultat final et le mode d’IA choisi ; ne pas compter l’ambiguïté comme un résultat supplémentaire |
| Éléments insuffisants pour l’IA | Un résultat inconnu de l’IA utilise source: ai et reason: insufficient_evidence | Compter comme inconnu ; une réponse JSON valide ne prouve pas l’exactitude |
| Erreur de requête ou d’élément | Les erreurs HTTP et les erreurs d’éléments de lot sont des résultats opérationnels, pas des étiquettes de genre | Signaler les échecs séparément ; publier leur nombre et leur dénominateur au lieu de les écarter discrètement |
Évaluez la configuration que vous utilisez réellement
- Séparez les entrées de type nom, e-mail et nom d’utilisateur. Un flux e-mail ou nom d’utilisateur inclut l’extraction de candidats : une étude portant uniquement sur des noms ne mesure pas ses performances de bout en bout.
- Séparez les valeurs off, fallback et always de ai_mode. Sans forceToGenderize, les requêtes unitaires utilisent fallback par défaut et les lots utilisent off. Fallback interroge d’abord le jeu de données, puis l’IA si aucun genre n’est renvoyé. Un score combiné peut masquer un écart entre les résultats du jeu de données et ceux de l’IA.
- Évaluez forceToGenderize séparément pour chaque type d’entrée pris en charge. Il peut déduire une association à partir d’un surnom même lorsque name vaut null ; un pseudonyme ne prouve pas l’identité du titulaire du compte.
- Notez si country a été fourni. Pour chaque candidat, l’enregistrement propre au pays est privilégié lorsqu’il existe, avec une recherche globale en repli ; consultez match.scope et match.country pour savoir quel enregistrement a été retenu.
- Présentez les résultats par contexte de pays, système d’écriture et type d’entrée, avec le nombre de cas de chaque segment. Une association régionale n’indique ni la nationalité ni le lieu de résidence.
- Fixez tout seuil de confiance applicatif avant de mesurer l’échantillon réservé à l’évaluation. Publiez à la fois le résultat brut de l’API et les abstentions de l’application dues à ce seuil, séparément pour chaque confidence_kind.
Définitions des indicateurs et dénominateurs
Pour une évaluation planifiée, N est le nombre de cas éligibles dotés d’une étiquette de référence. A = C + W est le nombre de cas avec un genre renvoyé : C corrects, W incorrects. U désigne les résultats inconnus et E les erreurs opérationnelles après application de la politique d’exécution définie à l’avance. Avec un seul résultat final par cas, N = C + W + U + E. Publiez ces effectifs avant les pourcentages.
Si N = 0, ces taux calculés sur la population ne sont pas définis. Ne publiez pas un taux non défini sous la forme 0 %. Indiquez les intervalles d’incertitude et la méthode utilisée pour les calculer ; des segments petits ou non représentatifs ne permettent pas d’affirmations générales sur la précision.
| Indicateur | Définition | Mesure publiée |
|---|---|---|
| Couverture des réponses | A / N | Non mesuré |
| Précision sur les cas répondus | C / A ; non défini si A = 0 | Non mesuré |
| Taux d’erreur sur les cas répondus | W / A ; non défini si A = 0 | Non mesuré |
| Réponses correctes sur l’ensemble des cas éligibles | C / N ; à ne pas présenter comme la précision sur les cas répondus | Non mesuré |
| Taux d’inconnus | U / N ; l’ambiguïté peut être présentée comme un sous-ensemble de U | Non mesuré |
| Taux d’erreurs opérationnelles | E / N ; ventiler aussi les erreurs par code d’erreur stable | Non mesuré |
| Calibration | Comparer les tranches de score à l’exactitude observée, séparément pour observed_frequency et model_reported ; indiquer le découpage, les effectifs et l’incertitude | Non mesuré |
Ce qu’une évaluation reproductible doit inclure
Ne créez pas d’étiquettes de référence en demandant ses estimations à un autre service d’inférence à partir des noms. Sans référence indépendante appropriée, une comparaison mesure une concordance, pas une exactitude vérifiée. Si les étiquettes de référence ne correspondent pas à la sortie binaire de l’API, documentez cette limite et le périmètre de l’évaluation sans réétiqueter les personnes pour les adapter à l’API.
| Élément | Information à documenter | Preuve publique actuelle |
|---|---|---|
| Population de référence | Origine et droit d’utilisation des étiquettes de référence ; éligibilité, exclusions, échantillonnage, dédoublonnage et définition des segments | Aucun jeu de référence revu n’est publié ici |
| Séparation des données sources | Contrôle des recouvrements et des fuites ; distinction entre jeux de développement et évaluation indépendante réservée | Aucun rapport de séparation vérifiée n’est publié ici |
| Version et exécution | Date d’exécution, version exacte de l’API, instantané du jeu de données, version du modèle ou du fournisseur lorsque l’IA est utilisée, prompts et paramètres de requête | Aucune version d’évaluation exécutée n’est publiée ici |
| Résultats | N, C, W, U, E, effectifs par segment, intervalles de confiance et analyse de calibration | Aucune valeur de performance mesurée n’est publiée ici |
| Reproduction et revue | Code d’évaluation, résultats agrégés reproductibles, limites connues et responsabilité de revue identifiable | Protocole uniquement ; aucune évaluation indépendante achevée |
Utilisez le résultat en tenant compte de ses limites
Les associations entre noms, pseudonymes et genre varient selon les langues, les pays et les populations. Une étiquette renvoyée ne peut pas établir l’identité de genre d’une personne. Conservez les résultats inconnus et donnez la priorité aux informations fournies par la personne elle-même. N’utilisez pas un genre inféré pour fonder des décisions aux conséquences importantes pour un individu.
Historique des révisions
| Date | Version du document | Modification |
|---|---|---|
| 2026-09-28 | 1.0.0 | Adaptation française des types de confiance V2, des sources de résultat, des résultats inconnus et des dénominateurs d’évaluation. Aucun nouveau résultat de précision n’est publié. |