# Precisão e confiança na GenderAPI.io V2

> Entenda o que significam os tipos de confiança da V2, como funcionam os resultados desconhecidos e como a precisão é avaliada. Este guia não publica nenhum valor de precisão medido.

Canonical HTML: https://www.genderapi.io/pt/accuracy-methodology

Last reviewed: 2026-09-29

## 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.

- [Campos da resposta na V2](https://www.genderapi.io/pt/docs/v2/responses)
- [Perfil datado do banco de dados e seus limites](https://www.genderapi.io/pt/data-provenance)

## 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.

- [Modos de IA e interpretação de apelidos](https://www.genderapi.io/pt/docs/v2/ai-options)
- [Parâmetros da requisição](https://www.genderapi.io/pt/docs/v2/request-parameters)

## 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.

- [Fontes de dados e limites das informações sobre a origem](https://www.genderapi.io/pt/data-provenance)
- [Fale com a GenderAPI.io sobre evidências de avaliação](https://www.genderapi.io/pt/contact)

## 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. |