O que um valor de confiança informa?
O valor confidence da V2 descreve as evidências por trás de uma única previsão. Ele não mede a precisão do serviço como um todo e não determina a identidade de gênero de uma pessoa. Leia o valor junto com confidence_kind, source e sample_count.
Este guia descreve o contrato de resposta atual da V2 e um protocolo de avaliação proposto. Os testes de contrato verificam o comportamento das respostas; eles não são um estudo de precisão com rótulos de referência independentes. A data de atualização desta página não é a data de uma medição de precisão.
Um perfil separado do banco de dados, datado de 26 de setembro de 2026, informa para cada uma das duas coleções o número de documentos segundo os metadados e a consistência dos contadores em 5.000 registros selecionados aleatoriamente por coleção. Essas verificações não comparam previsões com rótulos de referência independentes e, portanto, não fornecem nenhuma porcentagem de precisão.
Dois tipos de confiança, dois significados
Um exemplo de cálculo ilustrativo: se o registro selecionado contém male = 90, female = 10 e total = 100, o valor confidence é 0.9. Esses números inventados não são um resultado medido da GenderAPI.io e não significam que 90% das pessoas com esse nome se identificam como homens.
As frequências armazenadas não são apresentadas aqui como observações independentes e representativas. Um valor da IA não é calibrado em relação a essas frequências. Não compare os dois tipos como probabilidades intercambiáveis e não use um limite universal de confiança sem avaliar o seu próprio caso de uso.
| Campo da resposta | Resultado do conjunto de dados | Resultado da IA |
|---|---|---|
source | dataset | ai |
confidence_kind | observed_frequency quando um gênero é retornado | model_reported quando um gênero é retornado |
confidence | max(male, female) / total das frequências armazenadas quando um gênero é retornado; null com frequências exatamente empatadas | Um valor informado pelo modelo, maior que 0,5 e no máximo 1, quando um gênero é retornado; caso contrário, null |
sample_count | A contagem total armazenada no registro selecionado; não é o tamanho da amostra de uma avaliação | null; nenhum tamanho de amostra do conjunto de dados é informado |
match | Candidato selecionado, método de correspondência e escopo específico do país ou global | method é model_inference; name, scope e country são null |
Resultados desconhecidos e ambíguos e erros
Para resultados do conjunto de dados, não existe um limite universal abaixo do qual um valor de confiança baixo seja rejeitado. A validação das respostas da IA exige que um valor diferente de null seja maior que 0,5. Essa é uma condição do contrato, e não uma prova da qualidade da previsão. Preserve null em vez de convertê-lo em um valor de confiança zero ou em uma categoria de gênero adivinhada.
| Resultado | Comportamento na V2 | Tratamento na avaliação |
|---|---|---|
| Identificado | result_status é identified, e gender é male ou female | Compare com o rótulo de referência e conte como caso respondido |
| Desconhecido | gender e confidence são null; result_status é unknown | Mantenha o caso na amostra de casos relevantes e conte-o separadamente de uma previsão incorreta |
| Frequências empatadas no conjunto de dados | Frequências iguais para male e female geram reason: ambiguous no modo que usa apenas o conjunto de dados; o fallback pode substituir esse resultado por um resultado da IA | Registre o resultado final e o modo de IA escolhido; não conte a ambiguidade como um resultado adicional |
| Evidências insuficientes para a IA | Um resultado desconhecido da IA tem source: ai e reason: insufficient_evidence | Conte como unknown; uma resposta JSON válida não prova que o resultado está correto |
| Erro na requisição ou em um item | Erros HTTP e erros em itens individuais de um lote são falhas operacionais, não rótulos de gênero | Relate os erros separadamente; publique a quantidade e o denominador em vez de omiti-los silenciosamente |
Avaliar a configuração que você realmente usa
- Mantenha separadas as entradas do tipo nome, endereço de e-mail e nome de usuário. O processamento de endereços de e-mail e nomes de usuário inclui a extração de candidatos, então um estudo feito só com nomes não mede o desempenho desse processamento como um todo.
- Mantenha separados os valores off, fallback e always de ai_mode. Sem forceToGenderize, as requisições individuais usam fallback por padrão, e os lotes usam off por padrão. O fallback consulta primeiro o conjunto de dados e usa a IA se nenhum gênero for retornado. Uma pontuação agregada pode esconder a diferença entre os resultados do conjunto de dados e os da IA.
- Avalie forceToGenderize separadamente para cada tipo de entrada compatível. A opção pode deduzir uma associação a partir de um apelido, mesmo quando name é null; um alias não indica nada sobre a identidade da pessoa titular da conta.
- Registre se country foi informado. Para cada candidato, o registro específico do país tem prioridade se existir; caso contrário, é usada a consulta global. Verifique match.scope e match.country para ver qual registro foi selecionado.
- Relate os resultados por contexto de país, escrita e tipo de entrada e informe o número de casos em cada segmento. Uma associação regional não indica nacionalidade nem residência.
- Defina um eventual limite de confiança na sua aplicação antes de medir uma amostra de teste separada. Publique tanto o resultado bruto da API quanto as respostas descartadas pelo limite, separadamente para cada confidence_kind.
Definições das métricas e dos denominadores
Na avaliação planejada, N é o número de casos relevantes com um rótulo de referência. A = C + W é o número de casos em que um gênero foi retornado: C corretos e W incorretos. U representa os resultados desconhecidos e E os erros operacionais após a aplicação de uma regra de execução definida previamente. Com um único resultado final por caso, vale N = C + W + U + E. Publique essas quantidades antes das porcentagens.
Se N = 0, as métricas da população inteira não estão definidas. Não publique uma métrica indefinida como 0%. Informe os intervalos de incerteza e como eles foram calculados. Segmentos pequenos ou não representativos não justificam afirmações gerais sobre precisão.
| Métrica | Definição | Medição publicada |
|---|---|---|
| Cobertura de respostas | A / N | Não medida |
| Precisão nos casos respondidos | C / A; indefinida se A = 0 | Não medida |
| Taxa de erro nos casos respondidos | W / A; indefinida se A = 0 | Não medida |
| Respostas corretas entre todos os casos relevantes | C / N; não apresente isso como precisão nos casos respondidos | Não medida |
| Taxa de resultados desconhecidos | U / N; a ambiguidade pode ser relatada como um subconjunto de U | Não medida |
| Taxa de erros operacionais | E / N; divida também os erros por código de erro estável | Não medida |
| Calibração | Compare faixas de pontuação com a correção observada, separadamente para observed_frequency e model_reported; informe a divisão em faixas, o número de casos e a incerteza | Não medida |
O que uma avaliação reproduzível precisa conter
Não crie rótulos de referência pedindo previsões a outro serviço de identificação de gênero por nomes. Sem uma referência independente adequada, essa comparação mede concordância, e não precisão verificada. Se os rótulos de referência não se encaixarem nos resultados binários da API, descreva essa limitação e o escopo da avaliação em vez de adaptar os rótulos das pessoas à API.
| Parte | Informações necessárias | Evidências públicas atuais |
|---|---|---|
| População de referência | Origem dos rótulos de referência e direito de usá-los; critérios de inclusão e exclusão, procedimento de amostragem, remoção de duplicatas e definições dos segmentos | Nenhum conjunto de dados de referência verificado foi publicado aqui |
| Separação dos dados de origem | Verificação de sobreposição e vazamento de dados; separação entre os dados de teste do desenvolvimento e uma avaliação independente e separada | Nenhum relatório que confirme a separação foi publicado aqui |
| Versão e execução | Data da execução, versão exata da API, snapshot do conjunto de dados, versão do modelo ou do provedor se a IA for usada, prompts e configurações das requisições | Nenhuma versão de uma avaliação concluída foi publicada aqui |
| Resultados | N, C, W, U, E, número de casos por segmento, intervalos de confiança e análise de calibração | Nenhum valor de desempenho medido foi publicado aqui |
| Reprodução e revisão | Código da avaliação, resultados agregados reproduzíveis, limitações conhecidas e uma pessoa ou equipe nomeada responsável pela revisão | Apenas um protocolo; nenhuma avaliação independente concluída |
Usar o resultado dentro dos seus limites
As associações entre nomes ou apelidos e gênero variam conforme o idioma, o país e a população. Um rótulo retornado não pode determinar a identidade de gênero de uma pessoa. Preserve os resultados desconhecidos e dê prioridade ao que a própria pessoa declara. Não use um gênero inferido como base para decisões com consequências relevantes para uma pessoa.
Histórico de alterações
| Data | Versão do documento | Alteração |
|---|---|---|
| 2026-09-29 | 1.0.0 | Versão em português dos tipos de confiança da V2, das fontes dos resultados, dos resultados desconhecidos e dos denominadores da avaliação. Nenhum novo valor de precisão foi publicado. |