Co mówi wynik pewności?
Wynik confidence w V2 opisuje informacje, na których opiera się jedna konkretna prognoza. Nie mierzy ogólnej dokładności usługi i nie ustala tożsamości płciowej danej osoby. Odczytuj go razem z confidence_kind, source i sample_count.
Ten przewodnik opisuje obecny kontrakt odpowiedzi V2 i proponowany protokół oceny. Testy kontraktu sprawdzają zachowanie odpowiedzi; nie są badaniem dokładności opartym na niezależnych etykietach referencyjnych. Data aktualizacji tej strony nie jest datą pomiaru dokładności.
Osobny profil bazy danych, sporządzony 26 września 2026 r., podaje liczbę dokumentów w każdej z dwóch kolekcji według ich metadanych oraz spójność liczbową 5000 losowo wybranych rekordów z każdej kolekcji. Te kontrole nie porównują prognoz z niezależnymi etykietami referencyjnymi, dlatego nie dają żadnego procentu dokładności.
Dwa rodzaje pewności, dwa znaczenia
Wyłącznie poglądowe obliczenie: jeśli wybrany rekord zawiera male = 90, female = 10 i total = 100, jego confidence wynosi 0.9. Te zmyślone liczby nie są zmierzonym wynikiem GenderAPI.io i nie oznaczają, że 90% osób o tym imieniu identyfikuje się jako mężczyźni.
Zapisane liczby wystąpień nie są tu przedstawiane jako niezależne i reprezentatywne obserwacje. Wynik AI nie jest skalibrowany względem tych liczb. Nie porównuj obu rodzajów jako wymiennych prawdopodobieństw i nie stosuj uniwersalnego progu pewności bez oceny dostosowanej do Twojego zastosowania.
| Pole odpowiedzi | Wynik ze zbioru danych | Wynik AI |
|---|---|---|
source | dataset | ai |
confidence_kind | observed_frequency, gdy zwracana jest płeć | model_reported, gdy zwracana jest płeć |
confidence | max(male, female) / total z zapisanych liczb wystąpień, gdy zwracana jest płeć; null przy dokładnie równych liczbach | Wynik podany przez model, większy niż 0,5 i nie większy niż 1, gdy zwracana jest płeć; w przeciwnym razie null |
sample_count | Łączna liczba zapisana w wybranym rekordzie; nie jest to wielkość próby w ocenie | null; liczba próbek ze zbioru danych nie jest podawana |
match | Wybrany kandydat, metoda dopasowania oraz zakres krajowy lub globalny | method ma wartość model_inference; name, scope i country mają wartość null |
Wyniki unknown, niejednoznaczne i błędy
Dla wyników ze zbioru danych nie ma uniwersalnego progu odrzucania przy niskiej pewności. Walidator odpowiedzi AI wymaga, aby wynik różny od null był większy niż 0,5; to ograniczenie kontraktu, a nie dowód jakości prognozy. Zachowaj null, zamiast zamieniać go na zerową pewność lub zgadywaną kategorię płci.
| Wynik | Zachowanie V2 | Sposób ujęcia w ocenie |
|---|---|---|
| Rozpoznany | result_status ma wartość identified, a gender ma wartość male lub female | Porównać z etykietą referencyjną i liczyć jako przypadek z odpowiedzią |
| Nieznany | gender i confidence mają wartość null; result_status ma wartość unknown | Zachować w próbie kwalifikujących się przypadków i liczyć oddzielnie od błędnej prognozy |
| Remis w zbiorze danych | Równe liczby male i female dają reason: ambiguous w trybie tylko ze zbiorem danych; fallback może zastąpić ten wynik wynikiem AI | Zapisać ostateczny wynik i wybrany tryb AI; nie liczyć niejednoznaczności jako dodatkowego wyniku |
| Niewystarczające informacje dla AI | Wynik unknown z AI ma source: ai i reason: insufficient_evidence | Liczyć jako unknown; poprawna odpowiedź JSON nie dowodzi trafności |
| Błąd zapytania lub elementu | Błędy HTTP i błędy elementów partii są wynikami operacyjnymi, a nie etykietami płci | Raportować błędy osobno; publikować ich liczbę i mianownik zamiast pomijać je bez informacji |
Oceniaj konfigurację, której faktycznie używasz
- Oddzielaj dane wejściowe typu imię, adres e-mail i nazwa użytkownika. Proces dla adresów e-mail lub nazw użytkowników obejmuje wyodrębnianie kandydatów, więc badanie oparte wyłącznie na imionach nie mierzy jego skuteczności od początku do końca.
- Oddzielaj wartości off, fallback i always w ai_mode. Bez forceToGenderize pojedyncze zapytania domyślnie korzystają z fallback, a partie z off. Fallback najpierw sprawdza zbiór danych, a gdy nie zwróci on płci, korzysta z AI. Łączny wynik może ukryć różnicę między wynikami ze zbioru danych i z AI.
- Oceniaj forceToGenderize osobno dla każdego obsługiwanego typu danych wejściowych. Może wywnioskować powiązanie z pseudonimu, nawet gdy name ma wartość null; alias nie dowodzi tożsamości właściciela konta.
- Zapisuj, czy podano country. Dla każdego kandydata pierwszeństwo ma rekord dla danego kraju, jeśli istnieje, a w przeciwnym razie używane jest wyszukiwanie globalne; sprawdź match.scope i match.country, aby zobaczyć, który rekord został wybrany.
- Raportuj wyniki według kontekstu kraju, systemu pisma i typu danych wejściowych, podając liczbę przypadków w każdym segmencie. Powiązanie regionalne nie oznacza narodowości ani miejsca zamieszkania.
- Ustal ewentualny próg pewności w aplikacji, zanim zmierzysz wydzieloną próbę testową. Publikuj zarówno surowy wynik API, jak i odmowy odpowiedzi wynikające z tego progu, osobno dla każdego confidence_kind.
Definicje wskaźników i mianowniki
W planowanej ocenie N oznacza liczbę kwalifikujących się przypadków z etykietą referencyjną. A = C + W to liczba przypadków, w których zwrócono płeć: C poprawnych i W błędnych. U oznacza wyniki unknown, a E błędy operacyjne po zastosowaniu wcześniej ustalonej polityki wykonania. Przy jednym ostatecznym wyniku na przypadek N = C + W + U + E. Publikuj te liczby przed wartościami procentowymi.
Jeśli N = 0, te wskaźniki liczone dla populacji są nieokreślone. Nie publikuj nieokreślonego wskaźnika jako 0%. Podawaj przedziały niepewności i metodę ich obliczenia; małe lub niereprezentatywne segmenty nie uzasadniają ogólnych twierdzeń o dokładności.
| Wskaźnik | Definicja | Opublikowany pomiar |
|---|---|---|
| Pokrycie odpowiedzi | A / N | Nie zmierzono |
| Dokładność dla przypadków z odpowiedzią | C / A; nieokreślona, jeśli A = 0 | Nie zmierzono |
| Odsetek błędów dla przypadków z odpowiedzią | W / A; nieokreślony, jeśli A = 0 | Nie zmierzono |
| Poprawne odpowiedzi wśród wszystkich kwalifikujących się przypadków | C / N; nie przedstawiaj tego jako dokładności dla przypadków z odpowiedzią | Nie zmierzono |
| Odsetek wyników unknown | U / N; niejednoznaczność można raportować jako podzbiór U | Nie zmierzono |
| Odsetek błędów operacyjnych | E / N; dodatkowo podziel błędy według stabilnego kodu błędu | Nie zmierzono |
| Kalibracja | Porównaj przedziały wyników z obserwowaną trafnością, osobno dla observed_frequency i model_reported; podaj sposób podziału na przedziały, liczebności i niepewność | Nie zmierzono |
Co musi zawierać powtarzalna ocena
Nie twórz etykiet referencyjnych, pytając inną usługę inferencji płci na podstawie imion o jej przypuszczenia. Bez odpowiedniego niezależnego punktu odniesienia porównanie mierzy zgodność, a nie zweryfikowaną dokładność. Jeśli etykiety referencyjne nie odpowiadają binarnemu wynikowi API, opisz to ograniczenie i zakres oceny, zamiast zmieniać etykiety osób, aby dopasować je do API.
| Element | Wymagana informacja | Obecne publiczne dowody |
|---|---|---|
| Populacja referencyjna | Pochodzenie etykiet referencyjnych i prawo do ich użycia; kryteria kwalifikacji, wykluczenia, dobór próby, usuwanie duplikatów i definicje segmentów | Nie opublikowano tu żadnego zweryfikowanego zbioru referencyjnego |
| Oddzielenie od danych źródłowych | Sprawdzenie nakładania się danych i wycieków; odróżnienie danych testowych używanych w rozwoju od niezależnej, wydzielonej oceny | Nie opublikowano tu żadnego raportu potwierdzającego oddzielenie |
| Wersja i wykonanie | Data wykonania, dokładna wersja API, migawka zbioru danych, wersja modelu lub dostawcy, gdy używana jest AI, prompty i ustawienia zapytań | Nie opublikowano tu żadnej wersji przeprowadzonej oceny |
| Wyniki | N, C, W, U, E, liczebności segmentów, przedziały ufności i analiza kalibracji | Nie opublikowano tu żadnych zmierzonych wartości skuteczności |
| Odtworzenie i przegląd | Kod oceny, powtarzalne wyniki zbiorcze, znane ograniczenia i wskazana osoba lub zespół odpowiedzialny za przegląd | Tylko protokół; brak zakończonej niezależnej oceny |
Korzystaj z wyniku, pamiętając o jego ograniczeniach
Powiązania imion i pseudonimów z płcią różnią się w zależności od języka, kraju i populacji. Zwrócona etykieta nie może ustalić tożsamości płciowej danej osoby. Zachowuj wyniki unknown, a pierwszeństwo dawaj informacjom przekazanym przez samą osobę. Nie opieraj na wywnioskowanej płci decyzji, które mają istotne skutki dla danej osoby.
Historia zmian
| Data | Wersja dokumentu | Zmiana |
|---|---|---|
| 2026-09-28 | 1.0.0 | Polska adaptacja rodzajów pewności V2, źródeł wyników, wyników unknown i mianowników oceny. Nie opublikowano żadnego nowego wyniku dokładności. |