Metodologia

1. Catálogo por grupo

O ponto de partida é um catálogo curado de 484 linhas de grupos étnicos, indexado por nome, com colunas normalizadas para terra natal, região, idioma, códigos ISO de idioma, códigos ISO de país, religião e uma URL da Wikipedia quando disponível. A taxonomia segue uma hierarquia padrão continente → sub-região → etnia: Américas, Europa, África, Ásia e Oceania no nível de continente; 23 sub-regiões; 484 grupos étnicos.

Este catálogo é anterior ao pipeline atual e é curado manualmente. Ele é publicado como a configuração ethnicities do dataset público no HuggingFace.

2. Coleta de pessoas notáveis

Para cada grupo com uma URL da Wikipedia, tentamos obter o artigo correspondente “List of {Ethnicity} people”. Quando esse artigo existe, extraímos nomes, descrições curtas de “conhecido por”, anos de nascimento e morte quando disponíveis e URLs de referência de cada pessoa. 291 de 484 grupos têm pelo menos um artigo desse tipo na Wikipedia; 193 não têm (geralmente grupos pequenos ou pouco conhecidos para os quais nenhuma página de lista foi escrita). A coleta produziu 13.094 linhas de pessoas no total, publicadas como a configuração notable_people.

3. Descoberta de URLs de imagens

Para cada pessoa coletada, seguimos a URL de referência até o artigo individual dessa pessoa na Wikipedia e extraímos a URL de uma imagem representativa, dando preferência à imagem principal da infobox do artigo e, na falta dela, à primeira imagem OpenGraph. 6,243 de 13,094 pessoas (47.7%) têm uma imagem localizável na Wikipedia; os ~52% restantes não têm imagem na infobox (muitas vezes figuras anteriores à fotografia ou pessoas de pouca projeção com artigos apenas em texto).

O upload.wikimedia.org da Wikimedia aplica limites de taxa agressivos por IP de origem. Limitamos o coletor a 2 requisições por segundo por IP de origem; taxas mais altas provocam HTTP 429 dentro dos lotes.

4. Anotação por LLM de visão

Cada imagem com URL localizável é enviada a um modelo de linguagem com visão com um prompt estruturado fixo que pede 14 campos de fenótipo, além de uma pontuação de confiança autodeclarada (0.0 a 1.0) e uma categoria de qualidade de imagem (high / medium / low / very_low). O prompt instrui explicitamente o modelo a usar o vocabulário Fitzpatrick I a VI para o tom de pele (aceitando intervalos quando apropriado), detectar a presença de prega epicântica como subcampo estruturado do formato dos olhos, tratar a fotografia como uma observação de uma pessoa (e não como protótipo de um estereótipo étnico), retornar unknown ou vazio para campos que não podem ser avaliados e indicar explicitamente obstruções (óculos, chapéu, maquiagem, rosto parcial).

O modelo usado é o perfil de inferência Anthropic Claude Sonnet 4.6 no AWS Bedrock (us.anthropic.claude-sonnet-4-6). Execuções piloto com modelos de nível superior não mostraram ganho mensurável de precisão com este prompt: a tarefa é uma extração estruturada de contexto curto com esquema fixo, que o Sonnet executa com qualidade total a um custo menor.

Estatísticas da execução: 5,668 imagens analisadas com sucesso; ~575 falharam (falhas de carregamento, erros do modelo, falhas de parsing ou entradas grandes demais que atingiram o limite de 5MB por imagem do Bedrock); concorrência = 4; vazão de ~0.42 imagens/segundo (limitada pela rede); custo total de $44.66 USD pelo preço de tabela do Bedrock.

A resposta estruturada é analisada e armazenada linha a linha. O JSON bruto original é mantido no banco de dados de origem (coluna ethnic_image_analysis.raw_json) para auditoria, mas não é redistribuído.

5. Sistema de vocabulário controlado

Além da análise legada de 14 campos, o pipeline agora define um vocabulário controlado abrangente que cobre 22 categorias anatômicas com 196 dimensões e 853 classes de vocabulário, com base em mais de 113 referências revisadas por pares. Cada arquivo de vocabulário é um documento JSON que especifica dimensões (com tipo: categorical / ordinal / numeric / structured), escala (com citação), descrição, valores válidos (com definições) e metadados de observabilidade (se a dimensão pode ser avaliada a partir de uma fotografia e com qual extensão visível mínima).

Um script gerador (scripts/generate-from-vocabulary.mjs) lê cada arquivo de vocabulário e produz quatro artefatos: um fragmento de prompt de análise para o LLM de visão, um modelo de banco de dados Prisma, uma função de agregação e uma página de documentação em Markdown. Adicionar uma nova dimensão significa editar um arquivo JSON e executar o gerador novamente; não há prompt de análise escrito à mão para manter em paralelo com o esquema.

Consulte o Atlas para navegar pelas 22 categorias, o Glossário para todos os 853 termos definidos ou o repositório do vocabulário público para os arquivos-fonte.

6. Agregação por grupo

Um agregador determinístico em SQL/JavaScript (sem LLM) gera um cartão-resumo por grupo a partir das linhas de observação de imagens de cada grupo. O agregador não usa LLM e pode ser executado novamente. Para cada grupo com pelo menos 3 observações de imagem, ele produz:

• Tamanho da amostra e distribuição por fonte
• Divisão por qualidade (percentuais high / medium / low / very_low)
• Confiança autodeclarada média
• Distribuição Fitzpatrick (proporção de linhas em cada faixa de I a VI)
• Distribuições de cor do cabelo, textura do cabelo e cor dos olhos
• Proporção de prega epicântica (sim / não / parcial)
• Linhas de ressalva condicionais: amostra pequena (N<10), amostra modesta (N<25), baixa qualidade, baixa confiança, “as pessoas notáveis da Wikipedia tendem a ser homens e figuras públicas, não representativas da população”

7. Pontuação de cobertura

Cada página de grupo étnico exibe uma pontuação de profundidade de dados de 0 a 100 com quatro componentes ponderados:

• Tamanho da amostra: 0 a 40 (contagem de imagens em escala logarítmica, com teto em n≥50)
• Qualidade: 0 a 30 (% de imagens com image_quality = "high")
• Confiança: 0 a 20 (confiança média autodeclarada pelo modelo)
• Diversidade de fontes: 0 a 10 (source_types distintos; atualmente sempre 0 ou 1, pois 100% vem da Wikipedia; preparado para o futuro)

A pontuação reflete a profundidade da cobertura com honestidade. Grupos para os quais a Wikipedia não tem cobertura fotográfica ficam em 0; grupos com cobertura abrangente se aproximam de 100. A pontuação fica em ethniclist.CoverageScore e é atualizada sempre que os dados subjacentes mudam.

8. Reprodutibilidade

Todo o código do pipeline é de código aberto sob Apache 2.0 em github.com/Agaveis/phenotype-catalog-pipeline. O artigo de metodologia está publicado em doi.org/10.5281/zenodo.20075617. O dataset está publicado sob CC BY 4.0 em huggingface.co/datasets/EthnicErotic/phenotype-catalog.

Para replicar o pipeline, é necessário: credenciais da AWS com acesso ao Bedrock em us-east-1, um banco de dados SQL Server com o esquema (ou uma adaptação para o banco de sua escolha), Node.js 18+, a CLI do HuggingFace para upload e cerca de $45 USD de orçamento de inferência de visão no Bedrock para a execução completa de 5,668 imagens.