Che cosa indica un valore di confidenza?
Il valore confidence di V2 descrive le evidenze su cui si basa una singola previsione. Non misura l'accuratezza complessiva del servizio e non stabilisce l'identità di genere di una persona. Leggilo insieme a confidence_kind, source e sample_count.
Questa guida descrive l'attuale contratto di risposta di V2 e un protocollo di valutazione proposto. I test del contratto verificano il comportamento delle risposte; non sono uno studio sull'accuratezza con etichette di riferimento indipendenti. La data di aggiornamento della pagina non è la data di una misurazione dell'accuratezza.
Un profilo separato del database, datato 26 settembre 2026, riporta il numero di documenti di ciascuna delle due collezioni secondo i relativi metadati e la coerenza dei contatori in 5.000 voci selezionate casualmente per collezione. Questi controlli non confrontano le previsioni con etichette di riferimento indipendenti e quindi non forniscono alcun valore percentuale di accuratezza.
Due tipi di confidenza, due significati
Un calcolo puramente illustrativo: se la voce selezionata contiene male = 90, female = 10 e total = 100, il suo valore confidence è 0.9. Questi numeri inventati non sono un risultato misurato di GenderAPI.io e non significano che il 90% delle persone con quel nome si identifichi come uomo.
Le frequenze memorizzate non vengono presentate qui come osservazioni indipendenti e rappresentative. Un valore dell'IA non è calibrato rispetto a queste frequenze. Non confrontare i due tipi come probabilità intercambiabili e non usare una soglia di confidenza universale senza una valutazione per il tuo caso d'uso.
| Campo della risposta | Risultato del set di dati | Risultato dell'IA |
|---|---|---|
source | dataset | ai |
confidence_kind | observed_frequency quando viene restituito un genere | model_reported quando viene restituito un genere |
confidence | max(male, female) / total dalle frequenze memorizzate quando viene restituito un genere; null in caso di frequenze esattamente in parità | Un valore riportato dal modello, maggiore di 0,5 e al massimo 1, quando viene restituito un genere; altrimenti null |
sample_count | Il conteggio totale memorizzato nella voce selezionata; non è la dimensione del campione di una valutazione | null; non viene indicato alcun conteggio del campione del set di dati |
match | Candidato selezionato, metodo di corrispondenza e ambito specifico del paese o globale | method è model_inference; name, scope e country sono null |
Risultati sconosciuti, ambigui ed errori
Per i risultati del set di dati non esiste una soglia universale al di sotto della quale una confidenza bassa venga scartata. La convalida delle risposte dell'IA richiede che un valore diverso da null sia maggiore di 0,5; è una condizione del contratto e non una prova della qualità della previsione. Conserva null invece di convertirlo in una confidenza pari a zero o in una categoria di genere indovinata.
| Risultato | Comportamento di V2 | Trattamento nella valutazione |
|---|---|---|
| Identificato | result_status è identified e gender è male o female | Confronta con l'etichetta di riferimento e conta come caso con risposta |
| Sconosciuto | gender e confidence sono null; result_status è unknown | Mantieni nel campione dei casi ammissibili e conta separatamente da una previsione errata |
| Frequenze in parità nel set di dati | Frequenze in parità per male e female producono reason: ambiguous nella modalità basata solo sul set di dati; il fallback può sostituire il risultato con un risultato dell'IA | Registra il risultato finale e la modalità IA scelta; non contare l'ambiguità come un risultato aggiuntivo |
| Evidenze insufficienti per l'IA | Un risultato sconosciuto dell'IA ha source: ai e reason: insufficient_evidence | Conta come unknown; una risposta JSON valida non dimostra che il risultato sia corretto |
| Errore della richiesta o di un elemento | Gli errori HTTP e gli errori dei singoli elementi di un batch sono esiti operativi, non etichette di genere | Riporta gli errori separatamente; pubblica il loro numero e il denominatore invece di ometterli tacitamente |
Valutare la configurazione che usi davvero
- Tieni separati gli input di tipo nome, indirizzo email e nome utente. Il flusso per indirizzi email e nomi utente include l'estrazione dei candidati, quindi uno studio basato solo sui nomi non misura le prestazioni del flusso dall'inizio alla fine.
- Tieni separati i valori off, fallback e always di ai_mode. Senza forceToGenderize, le richieste singole usano fallback per impostazione predefinita e i batch off. Il fallback consulta prima il set di dati e usa l'IA se non viene restituito un genere. Un risultato aggregato può nascondere la differenza tra i risultati del set di dati e quelli dell'IA.
- Valuta forceToGenderize separatamente per ogni tipo di input supportato. Può dedurre un'associazione da un nickname anche quando name è null; un alias non indica l'identità del titolare dell'account.
- Registra se country è stato indicato. Per ogni candidato ha la precedenza la voce specifica del paese, se esiste, altrimenti viene usata la ricerca globale; controlla match.scope e match.country per sapere quale voce è stata selezionata.
- Riporta i risultati per contesto del paese, sistema di scrittura e tipo di input e indica il numero di casi in ogni segmento. Un'associazione regionale non implica né la nazionalità né il luogo di residenza.
- Stabilisci un'eventuale soglia di confidenza della tua applicazione prima di misurare un campione di test tenuto da parte. Pubblica sia il risultato non modificato dell'API sia le risposte trattenute dalla soglia, separatamente per ogni confidence_kind.
Definizioni delle metriche e dei denominatori
Nella valutazione prevista, N è il numero di casi ammissibili con etichetta di riferimento. A = C + W è il numero di casi in cui è stato restituito un genere: C corretti e W errati. U indica i risultati sconosciuti ed E gli errori operativi dopo l'applicazione di una regola di esecuzione stabilita in anticipo. Con un risultato finale per caso vale N = C + W + U + E. Pubblica questi conteggi prima dei valori percentuali.
Se N = 0, le metriche riferite all'intera popolazione non sono definite. Non pubblicare una metrica non definita come 0%. Indica gli intervalli di incertezza e il modo in cui sono stati calcolati; segmenti piccoli o non rappresentativi non giustificano affermazioni generali sull'accuratezza.
| Metrica | Definizione | Misurazione pubblicata |
|---|---|---|
| Copertura delle risposte | A / N | Non misurata |
| Accuratezza sui casi con risposta | C / A; non definita quando A = 0 | Non misurata |
| Tasso di errore sui casi con risposta | W / A; non definito quando A = 0 | Non misurato |
| Risposte corrette su tutti i casi ammissibili | C / N; non presentarla come accuratezza sui casi con risposta | Non misurata |
| Quota di risultati sconosciuti | U / N; l'ambiguità può essere riportata come sottoinsieme di U | Non misurata |
| Quota di errori operativi | E / N; suddividi inoltre gli errori per codice di errore stabile | Non misurata |
| Calibrazione | Confronta gli intervalli di valori con la correttezza osservata, separatamente per observed_frequency e model_reported; indica la suddivisione in intervalli, il numero di casi e l'incertezza | Non misurata |
Che cosa deve includere una valutazione riproducibile
Non creare etichette di riferimento chiedendo la valutazione a un altro servizio di determinazione del genere dai nomi. Senza un riferimento indipendente adeguato, un confronto di questo tipo misura la concordanza, non un'accuratezza verificata. Se le etichette di riferimento non corrispondono ai risultati binari dell'API, descrivi questo limite e l'ambito della valutazione invece di adattare le etichette delle persone all'API.
| Componente | Informazioni richieste | Evidenze pubbliche attuali |
|---|---|---|
| Popolazione di riferimento | Origine delle etichette di riferimento e diritto di usarle; criteri di inclusione ed esclusione, procedura di campionamento, rimozione dei duplicati e definizioni dei segmenti | Nessun set di dati di riferimento verificato è stato pubblicato qui |
| Separazione dai dati di origine | Controllo delle sovrapposizioni e delle fughe di dati; separazione tra i dati di test dello sviluppo e una valutazione indipendente tenuta da parte | Nessun rapporto che confermi la separazione è stato pubblicato qui |
| Versione ed esecuzione | Data di esecuzione, versione esatta dell'API, istantanea del set di dati, versione del modello o del fornitore quando viene usata l'IA, prompt e impostazioni delle richieste | Nessuna versione di una valutazione eseguita è stata pubblicata qui |
| Risultati | N, C, W, U, E, numero di casi per segmento, intervalli di confidenza e analisi della calibrazione | Nessun valore di prestazione misurato è stato pubblicato qui |
| Riproduzione e revisione | Codice di valutazione, risultati aggregati riproducibili, limiti noti e una persona o un team indicati per nome come responsabili della revisione | Solo protocollo; nessuna valutazione indipendente completata |
Usare il risultato nel rispetto dei suoi limiti
Le associazioni tra nomi o nickname e genere variano tra lingue, paesi e popolazioni. Un'etichetta restituita non può stabilire l'identità di genere di una persona. Conserva i risultati sconosciuti e dai la precedenza a ciò che la persona dichiara. Non prendere decisioni con conseguenze rilevanti per una persona sulla base di un genere dedotto.
Cronologia delle modifiche
| Data | Versione del documento | Modifica |
|---|---|---|
| 2026-09-28 | 1.0.0 | Versione italiana dei tipi di confidenza di V2, delle fonti dei risultati, dei risultati sconosciuti e dei denominatori della valutazione. Non è stato pubblicato alcun nuovo valore di accuratezza. |