Estimativa de Competência com MACE

Use o algoritmo MACE no Potato para estimar a competência dos anotadores, ponderar discordâncias e inferir rótulos de referência a partir de dados de anotação ruidosos.

O MACE (Multi-Annotator Competence Estimation) é um algoritmo EM Bayesiano Variacional que estima conjuntamente os rótulos verdadeiros de cada item e as pontuações de competência do anotador. Ele modela cada anotador como "conhecedor" (produz rótulos corretos) ou "adivinhador" (produz rótulos aleatórios), gerando uma pontuação de competência entre 0.0 e 1.0.

Quando Usar o MACE

O MACE é útil quando você tem vários anotadores rotulando os mesmos itens e quer:

Identificar quais anotadores são mais confiáveis
Produzir rótulos previstos de maior qualidade ponderando as contribuições dos anotadores
Detectar anotadores de baixa qualidade (spammers) automaticamente
Medir a incerteza dos rótulos (entropia) por item

O MACE funciona com tipos de anotação categóricos: radio, likert, select e multiselect. Não se aplica a anotações de texto livre, span, slider ou numéricas.

Como Funciona

Extração de dados: o Potato reúne todas as anotações de cada esquema de todos os anotadores, construindo uma matriz de itens por anotadores
Algoritmo EM: o MACE executa vários reinícios aleatórios do algoritmo EM Bayesiano Variacional, mantendo a solução com a melhor log-verossimilhança
Saída: para cada esquema, o MACE produz rótulos previstos, entropia dos rótulos (incerteza) e pontuações de competência por anotador
Disparo: o MACE é executado automaticamente após cada N novas anotações (configurável), ou pode ser disparado manualmente pela API de administração

Configuração

yaml

mace:
  enabled: true
 
  # Run MACE after every N new annotations
  trigger_every_n: 10
 
  # Minimum annotators per item before including in computation
  min_annotations_per_item: 3
 
  # Minimum eligible items before MACE will run
  min_items: 5
 
  # EM algorithm parameters
  num_restarts: 10
  num_iters: 50
  alpha: 0.5    # Prior for annotator spamming (Beta distribution)
  beta: 0.5     # Prior for guessing strategy (Dirichlet distribution)

Configuração Mínima

yaml

mace:
  enabled: true

Usa todos os valores padrão: dispara a cada 10 anotações, exige 3 anotadores por item, no mínimo 5 itens elegíveis, 10 reinícios com 50 iterações cada.

Referência de Configuração

Opção	Tipo	Padrão	Descrição
`enabled`	boolean	`false`	Habilitar o MACE
`trigger_every_n`	integer	`10`	Executar após cada N novas anotações
`min_annotations_per_item`	integer	`3`	Mínimo de anotadores por item (deve ser >= 2)
`min_items`	integer	`5`	Mínimo de itens elegíveis antes de executar
`num_restarts`	integer	`10`	Reinícios aleatórios para o EM
`num_iters`	integer	`50`	Iterações do EM por reinício
`alpha`	float	`0.5`	Prior para spamming do anotador
`beta`	float	`0.5`	Prior para estratégia de adivinhação

Endpoints da API de Administração

Todos os endpoints do MACE exigem autenticação de administrador pelo cabeçalho X-API-Key.

Visão Geral

bash

curl http://localhost:8000/admin/api/mace/overview \
  -H "X-API-Key: your-admin-key"

Retorna as pontuações de competência dos anotadores e o status do MACE:

json

{
  "enabled": true,
  "has_results": true,
  "schemas": ["sentiment"],
  "annotator_competence": {
    "user_1": {"average": 0.92, "per_schema": {"sentiment": 0.92}},
    "user_2": {"average": 0.85, "per_schema": {"sentiment": 0.85}},
    "user_3": {"average": 0.45, "per_schema": {"sentiment": 0.45}}
  },
  "total_annotations": 30,
  "annotations_until_next_run": 0
}

Previsões

bash

curl "http://localhost:8000/admin/api/mace/predictions?schema=sentiment" \
  -H "X-API-Key: your-admin-key"

Retorna os rótulos previstos e a entropia para cada item.

Disparo Manual

bash

curl -X POST http://localhost:8000/admin/api/mace/trigger \
  -H "X-API-Key: your-admin-key"

Interpretando os Resultados

Competência do Anotador

0.9 - 1.0: anotador altamente confiável
0.7 - 0.9: bom anotador, discordâncias ocasionais
0.5 - 0.7: anotador moderado, pode se beneficiar de treinamento adicional
Abaixo de 0.5: possível spammer ou anotador confuso

Entropia dos Rótulos

Próximo de 0.0: alta confiança no rótulo previsto
Acima de 0.5: incerteza moderada, o item pode ser genuinamente ambíguo
Próximo de log(num_labels): incerteza máxima, sem consenso

Integração com Adjudicação

Quando o MACE e a adjudicação estão habilitados, os rótulos previstos pelo MACE aparecem como um sinal adicional na interface de adjudicação:

yaml

adjudication:
  enabled: true
  adjudicator_users: ["admin"]
  min_annotations: 2
 
mace:
  enabled: true
  trigger_every_n: 10
  min_annotations_per_item: 2

Boas Práticas

Comece com os valores padrão - a configuração padrão funciona bem na maioria dos cenários
Monitore as pontuações de competência - use o painel de administração para acompanhar a qualidade dos anotadores ao longo do tempo
Combine com fases de treinamento - use o treinamento para qualificar os anotadores e, em seguida, o MACE para monitorar a qualidade contínua
Defina limites adequados - reduza min_annotations_per_item para projetos de anotação menores

Leituras Adicionais

Quality Control - Outros mecanismos de controle de qualidade
Admin Dashboard - Monitoramento do progresso da anotação
AI Support - Anotação assistida por IA

Para detalhes de implementação, consulte a documentação de origem.