Che cosa significa source in V2?
Il campo source indica quale percorso ha prodotto il risultato finale: la ricerca nel set di dati memorizzato, un'inferenza dell'IA o nessuna fonte selezionata. Non è un riferimento all'editore originale di una voce, né una prova di licenza, né una garanzia che l'inferenza sia corretta.
Questa guida descrive l'attuale contratto di risposta di V2 e un profilo del database elaborato da GenderAPI.io. Le osservazioni che seguono sono misurazioni di inventario e controlli di coerenza; un catalogo verificato delle fonti originali e una valutazione indipendente dell'accuratezza non sono ancora stati pubblicati.
| source | Significato | Che cosa non indica |
|---|---|---|
dataset | È stata selezionata una voce memorizzata; con frequenze esattamente in parità il genere può comunque essere sconosciuto | Editore originale, metodo di raccolta, licenza, età della voce o indipendenza delle osservazioni |
ai | La risposta finale proviene dal percorso di inferenza dell'IA configurato; gender può comunque essere null | Un campione conteggiato, un riferimento al set di dati o un'accuratezza calibrata della previsione |
none | Nella modalità basata solo sul set di dati non è stata selezionata alcuna voce memorizzata per il risultato finale | Che l'input non abbia una possibile associazione del nome in tutte le popolazioni e in tutte le lingue |
Profilo del database: 26 settembre 2026
I metadati delle collezioni sono stati letti il 2026-09-26T15:28:18.227Z e i campioni casuali sono stati estratti il 2026-09-26T15:31:54.045Z. I due conteggi di documenti provengono, ciascuno separatamente, dai metadati collStats di MongoDB della rispettiva collezione e non da un conteggio completo indipendente. La collezione generale contiene voci di nomi e la collezione specifica per paese coppie di nome e paese. Non sommare i due numeri per ottenere un totale di nomi unici o di persone uniche.
Per ogni collezione, MongoDB ha selezionato casualmente 5.000 documenti e ha calcolato lato server i controlli aggregati riportati di seguito. Il rapporto pubblico non contiene nomi né dati grezzi. Sono osservazioni effettuate da GenderAPI.io sul database in produzione, non una verifica indipendente né un set di dati di valutazione congelato. I controlli riguardano la coerenza dei contatori, non l'accuratezza delle previsioni, il numero di persone o di nomi unici né la copertura dell'API.
| Osservazione | Voci generali | Voci specifiche per paese |
|---|---|---|
| Collezione | general | country-specific |
| Numero di documenti secondo i metadati | 2.483.220 | 4.080.692 |
| Chiave univoca memorizzata | name | name + country |
| Documenti selezionati casualmente | 5.000 | 5.000 |
| Controlli numerici non superati nel campione | 0 | 0 |
| male + female diverso da total nel campione | 0 | 0 |
| Frequenze in parità per male e female nel campione | 124 | 94 |
| Campo updated_at presente nel campione | 667 / 5.000 | 741 / 5.000 |
Che cosa mostrano i controlli del database
Il controllo numerico richiede che total sia un intero sicuro positivo e che le frequenze male e female siano finite e comprese tra zero e total. Un controllo separato confronta male + female con total. Tutti i contatori dei campioni hanno superato i controlli; ciò non significa che ogni voce delle collezioni sia coerente né che una previsione sia corretta.
Frequenze in parità per male e female sono state rilevate in 124 voci del campione della collezione generale e in 94 voci del campione della collezione specifica per paese. Si tratta di frequenze memorizzate uguali, non di identità ambigue verificate in modo indipendente né di una quota di risultati sconosciuti dell'API. I risultati effettivi dell'API dipendono dall'input, dalla disponibilità di Redis, dalla selezione dei candidati e dalle impostazioni dell'IA.
Un inventario separato del campo country nella collezione generale, eseguito il 2026-09-26T15:33:13.811Z, ha rilevato 244 valori memorizzati distinti: 239 nel formato di due lettere maiuscole e 5 in un altro formato. La conformità ISO, la distribuzione delle voci per paese e la copertura dei paesi supportati non sono state misurate. Questi numeri non sono il numero di paesi supportati.
In nessuno dei campioni sono stati rilevati campi relativi alla fonte o alla licenza. Ciò non dimostra che le informazioni di provenienza manchino in ogni voce o nei sistemi esterni: la presenza o l'assenza di un campo non prova la licenza di una fonte. Il campo updated_at era presente in alcune voci come valore numerico, ma i suoi valori e il suo significato non sono stati verificati; non indica né l'attualità dei dati né un piano di aggiornamento.
V2 esegue le ricerche nel set di dati tramite Redis. Il 26 settembre 2026 GenderAPI.io, in qualità di titolare del sistema, ha confermato che MongoDB e Redis contengono lo stesso set di dati. L'equivalenza si basa su questa conferma: non è stato effettuato alcun confronto indipendente tra i due database e questo controllo resta da svolgere. L'inventario sopra descrive le voci memorizzate; la copertura delle risposte dell'API dipende inoltre dagli input inviati, dalla corrispondenza dei candidati e dalle impostazioni dell'IA. I campioni sono stati estratti senza un seed fisso, letti senza un'istantanea congelata ed elaborati senza etichette di riferimento indipendenti; non consentono di misurare l'accuratezza delle previsioni, la calibrazione o la copertura delle risposte.
Tracciare le informazioni nella risposta
| Campo | Significato | Limite |
|---|---|---|
input | Ripete il tipo, il valore e il contesto del paese inviati | Un valore di input non è un dato di identità verificato in modo indipendente |
match.name / match.method | Indica il candidato selezionato e se è stato normalizzato, estratto come parte o sottostringa oppure dedotto dal modello | Una corrispondenza su una parte non garantisce che sia stato estratto un vero nome proprio dal nome completo o dall'identificativo |
match.scope / match.country | Indica se la voce selezionata proviene dalla ricerca specifica del paese o da quella globale | L'indicazione di un paese non garantisce che fosse disponibile una voce specifica per quel paese |
sample_count | Il conteggio totale memorizzato nella voce selezionata; null nell'inferenza dell'IA | Non indica necessariamente persone uniche, osservazioni raccolte in modo indipendente o la dimensione del campione di una valutazione dell'accuratezza |
confidence / confidence_kind | Distingue un rapporto calcolato da frequenze memorizzate da un valore riportato dal modello | Nessuno dei due valori è una probabilità verificata dell'identità di genere di una persona |
country / country_source | Metadati del paese della voce restituita o un'associazione del nome con un paese riportata dall'IA, se disponibili | Non indicano né la nazionalità né il luogo di residenza né un'origine verificata e non dimostrano che il paese inviato abbia trovato corrispondenza |
Come la corrispondenza dell'input influisce sul risultato
La ricerca nel set di dati normalizza il testo e ne ricava i candidati. Per gli indirizzi email i candidati provengono dalla parte prima della @; per i nomi utente viene rimossa una @ iniziale facoltativa. Le normali ricerche di indirizzi email e nomi utente possono inoltre controllare sottostringhe di lunghezza limitata. Se esistono più voci candidate, viene scelta quella con il conteggio totale memorizzato più alto; può trattarsi di una parte diversa dal nome proprio previsto.
Quando viene indicato un contesto del paese, per ogni candidato la ricerca controlla la voce specifica del paese e, se non esiste, la voce globale. Il risultato finale riporta la corrispondenza selezionata. Una voce ambigua specifica del paese non viene sostituita automaticamente dalla voce globale per quel candidato.
Il normale prompt dell'IA cerca un nome proprio riconoscibile. forceToGenderize consente inoltre associazioni basate su nickname personali o alias: in questa modalità un genere diverso da null insieme a name: null è un risultato valido. Si tratta di compiti di inferenza diversi che vanno valutati separatamente.
Ricerca nel set di dati e trattamento con l'IA
Quando viene usata l'IA, V2 trasmette type, value e il contesto del paese inviati al servizio di inferenza dell'IA configurato. Per gli indirizzi email il prompt chiede al modello di ignorare il dominio e il suffisso dopo il segno più; ciò non garantisce che questi caratteri vengano rimossi dal valore prima che l'IA lo elabori. Se il tuo flusso richiede una previsione basata solo sul set di dati, usa ai_mode: off senza forceToGenderize.
La convalida della risposta dell'IA controlla i campi JSON, i loro tipi e la loro coerenza reciproca. Non dimostra che il nome restituito, l'associazione di genere o l'associazione con un paese siano corretti. Il risultato pubblico non contiene né un identificativo o una versione del modello né una fonte che giustifichi la sua inferenza.
| Opzione | Percorso di inferenza | Informazioni restituite |
|---|---|---|
| ai_mode: off | Solo ricerca nel set di dati | Metadati della voce selezionata oppure un risultato sconosciuto senza voce selezionata |
| ai_mode: fallback | Consulta prima il set di dati; usa l'IA se non è stato restituito un genere | Informazioni del percorso finale, non un campione combinato di set di dati e IA |
| ai_mode: always | Usa direttamente il percorso di inferenza dell'IA configurato | Un valore riportato dal modello oppure un risultato sconosciuto con confidenza null; sample_count è sempre null |
| forceToGenderize: true | Consulta il set di dati e, se il risultato resta aperto, usa l'IA tenendo conto dei nickname | Informazioni del set di dati oppure un'associazione tramite nickname riportata dal modello; name può essere null |
Documentazione delle fonti non ancora pubblicata
Nessun catalogo verificato delle fonti è stato pubblicato qui. Il contratto di risposta e il comportamento dell'implementazione non bastano da soli per verificare l'origine dei dati, il diritto di usare una fonte, la sua rappresentatività o la qualità delle sue etichette. Prima di formulare affermazioni su fonti specifiche, le informazioni seguenti devono essere documentate e verificate.
Questa panoramica della documentazione non stabilisce se le fonti originali siano o meno concesse in licenza, né se siano complete o incomplete. Descrive i limiti delle evidenze disponibili pubblicamente. Contatta GenderAPI.io se il tuo caso d'uso richiede la valutazione di una determinata fonte.
| Evidenza | Documentazione richiesta | Stato pubblico |
|---|---|---|
| Origine e diritto di utilizzo | Fonte o editore indicati per nome, periodo di raccolta, licenza o un'altra base documentata per l'utilizzo | Nessun catalogo verificato è stato pubblicato qui |
| Cronologia dell'elaborazione | Trasformazioni, normalizzazione, rimozione dei duplicati, aggregazione e ogni contributo sintetico o generato da un modello | Non risulta dall'etichetta source: dataset |
| Copertura della popolazione | Copertura di paesi e sistemi di scrittura, procedura di campionamento, definizioni delle etichette e distorsioni documentate | Nessun dato di copertura valutato in modo indipendente è stato pubblicato qui |
| Attualità | Identificativi delle istantanee, date di aggiornamento delle singole fonti e un piano di aggiornamento supportato | La risposta V2 non contiene né informazioni sull'attualità delle singole voci né un identificativo dell'istantanea |
| Qualità e correzioni | Risultati della convalida, controlli delle sovrapposizioni, gestione di correzioni e cancellazioni e responsabilità della revisione | Nessun risultato di revisione per le singole fonti è stato pubblicato qui |
Protezione dei dati, trattamento e uso responsabile
L'origine delle fonti, il trattamento dei dati personali e le condizioni legali sono questioni distinte. Ruoli nel trattamento, periodi di conservazione, fornitori e condizioni contrattuali sono descritti nelle policy attualmente pubblicate. Questa guida tecnica non introduce nuovi impegni sulla conservazione dei dati e non attesta la conformità normativa.
Invia solo i dati di cui il tuo flusso ha bisogno. Conserva i tipi di confidenza e i risultati sconosciuti e non presentare un'inferenza come l'identità dichiarata da una persona. Non prendere decisioni con conseguenze rilevanti per una persona sulla base di un genere dedotto.
Evidenze sull'accuratezza e cronologia delle modifiche
L'etichetta della fonte spiega il percorso di inferenza, non la sua qualità misurata. La guida sull'accuratezza mostra come distinguere tra risultati delle risposte, copertura delle risposte, errori e le informazioni necessarie per una valutazione riproducibile.
| Data | Versione del documento | Modifica |
|---|---|---|
| 2026-09-28 | 1.0.0 | Versione italiana dell'inventario datato di MongoDB, dei controlli di coerenza nei campioni, dei campi V2 source e match, dei limiti del trattamento con l'IA e delle lacune ancora presenti nel catalogo delle fonti. L'equivalenza tra MongoDB e Redis si basa sulla conferma di GenderAPI.io del 26 settembre 2026; il confronto indipendente resta da svolgere. Non sono stati aggiunti né un valore percentuale di accuratezza né un'affermazione sulla licenza delle fonti. |