O motor de rotulagem

O motor de rotulagem rotula um conjunto de dados com modelos e usa pessoas para medir com que frequência os modelos erram. Você declara em um contrato o que os rótulos finais precisam satisfazer, por exemplo "no máximo 5% dos rótulos de máquina aceitos estão errados, com 90% de confiança". O motor pede às pessoas os rótulos de que precisa para testar essa afirmação, aceita os rótulos de máquina que o teste sustenta e envia os itens restantes para pessoas. O resultado é o conjunto de dados mais um certificado que registra o que foi testado e com quantos rótulos humanos.

O motor está disponível a partir do Potato 2.11. O servidor de anotação, a linha de comando potato label, a REST API, o servidor MCP e um Python SDK o controlam sobre o mesmo arquivo engine.sqlite no diretório da tarefa.

Quando o motor serve para um estudo

O motor compensa quando as pessoas não conseguem rotular tudo e um modelo consegue rotular a maior parte. Se as pessoas vão rotular todos os itens de qualquer forma, o motor não acrescenta nada, e uma estratégia de atribuição comum é a melhor escolha. Três situações se encaixam:

• Você tem mais itens do que as pessoas conseguem rotular e um modelo que acerta na maioria das vezes.
• Você precisa relatar a qualidade dos rótulos, e não só que um modelo os produziu, para um artigo, a publicação de um conjunto de dados ou um conjunto de treino que outra pessoa vai usar.
• Você está avaliando um modelo ou um agente com um juiz LLM e precisa saber se o juiz pode substituir as pessoas.

Da predição do modelo ao rótulo final

O motor guarda as predições de máquina, as solicitações a pessoas e os resultados dos contratos em um só armazenamento, e todo item passa pelas mesmas seis etapas:

1. Fontes são os modelos. Uma fonte pode ser um LLM, um modelo de visão e linguagem, um modelo de decisão (Laya, Jev ou OpenJev), um detector de objetos, um juiz LLM, um modelo treinado com os próprios rótulos do estudo, um júri de outras fontes ou rótulos que você já tem. Cada fonte registra uma confiança com cada predição.
2. A cascata ordena as fontes. Um item vai para a primeira fonte e, se o contrato não aceitar essa resposta, a fonte seguinte tenta. Depois da última fonte, o item vai para uma pessoa.
3. Solicitações são o que o motor pede às pessoas. Cada solicitação registra por que foi feita (por exemplo, calibração, certificação, verificação, auditoria), a probabilidade de seu item ter sido sorteado e se a pessoa podia ver uma resposta de máquina. As solicitações de calibração são sorteadas ao acaso e são sempre cegas.
4. Contratos testam os rótulos de máquina contra os rótulos humanos da amostra aleatória. Metade dessa amostra (a divisão dev) escolhe a regra de aceitação, e a outra metade (a divisão cert) a testa. O status de um contrato é met, insufficient (faltam rótulos, com uma estimativa de quantos), infeasible, violated ou stale.
5. A resolução dá a cada item seu rótulo final. O rótulo é um rótulo de máquina aceito sob um contrato cumprido, o rótulo de uma pessoa ou pendente.
6. O certificado registra o resultado de cada contrato, a cascata com as versões de modelo e de prompt, quantos rótulos humanos foram para cada finalidade, o gasto com modelos e um resumo criptográfico do registro de chamadas.

Regras por trás das garantias

Um contrato cumprido é uma afirmação estatística sobre a amostra aleatória que as pessoas rotularam, e ele vale por causa da forma como essa amostra é sorteada e usada. O motor impõe cinco regras:

• Solicitações cegas não mostram nenhuma resposta de máquina. Enquanto uma pessoa tem em mãos uma solicitação de calibração, certificação ou auditoria, o servidor retém todas as respostas de máquina para aquele item. As pré-anotações, o juiz inline, o assistente de IA (que responde 403) e os botões de ajuda de IA ficam todos desligados. Um rótulo dado depois de ver a resposta da máquina não é uma verificação independente dessa resposta.
• Seleção e teste usam rótulos diferentes. Os limiares são escolhidos com os rótulos dev e testados com os rótulos cert. Cada novo teste com os rótulos cert é feito em um nível mais rigoroso, então certificar de novo até um teste passar não infla a confiança.
• Só pessoas certificam. Anotadores de máquina podem participar da inferência do rótulo final, nunca dos rótulos contra os quais um contrato é testado.
• Uma mudança torna o certificado obsoleto. Mudar uma fonte, um prompt, um limiar ou o esquema marca todos os contratos afetados como stale e move seus rótulos aceitos para pending_recert até que o contrato seja testado de novo. Os rótulos humanos são mantidos.
• Predições de máquina não ocupam vagas de anotador. As predições do motor não contam para os limites de anotadores por item.

O motor não verifica se os rótulos humanos estão certos. Todo contrato mede as máquinas contra as pessoas que rotularam a amostra, então um contrato testado contra pessoas pouco confiáveis certifica concordância com pessoas pouco confiáveis. Use o controle de qualidade, a sobreposição (humans.overlap) e o contrato no_worse_than_human para verificar também as pessoas.

Um primeiro estudo

O Potato inclui três estudos de exemplo em examples/labeling-engine/, um para texto, um para imagens e um para traces de agentes. A tabela lista as fontes e os contratos que cada um usa:

O exemplo de texto roda com quatro comandos. O primeiro rotula todos os itens com a cascata e sorteia a primeira amostra cega, o segundo serve essa amostra às pessoas, e os dois últimos testam os contratos e imprimem o certificado depois que as pessoas rotularam a amostra:

potato label run examples/labeling-engine/text-certified-sentiment/config.yaml
potato start examples/labeling-engine/text-certified-sentiment/config.yaml -p 8000
potato label certify examples/labeling-engine/text-certified-sentiment/config.yaml
potato label certificate examples/labeling-engine/text-certified-sentiment/config.yaml --format md

Para adicionar o motor ao seu próprio estudo, acrescente estas chaves a uma configuração que já tenha data_files e um esquema de anotação chamado sentiment. O contrato exige que no máximo 10% dos rótulos de máquina aceitos estejam errados, com 90% de confiança, e budgets.human_labels limita quantas solicitações a pessoas o motor pode abrir:

assignment_strategy: engine
 
labeling_engine:
  enabled: true
  sources:
    - id: gemma
      kind: llm
      endpoint_type: vllm
      model: google/gemma-4-12B-it-qat-w4a16-ct
      base_url: http://localhost:8001/v1
      confidence: {method: logprob}
  contracts:
    - id: accuracy
      kind: selective_risk
      schema: sentiment
      error: 0.1
      confidence: 0.9
  budgets:
    human_labels: 400

A fonte informa sua confiança a partir das log-probabilidades dos tokens (method: logprob), o que custa uma chamada por item e costuma ser o mais bem calibrado dos métodos de confiança. Configuração lista todas as chaves, e Contratos explica o que cada contrato testa.

Solicitações na página de anotação

Com assignment_strategy: engine, os anotadores recebem as solicitações do motor, da prioridade mais alta para a mais baixa. A ordem é: arbitragem, certificação, calibração, avaliadores extras para contratos distribucionais, itens que nenhuma máquina conseguiu rotular, verificação e auditorias. As solicitações de calibração são servidas em uma ordem aleatória fixa, com solicitações dev e cert intercaladas. Uma pessoa recebe de uma vez todas as solicitações abertas de um item, uma por esquema, e nunca duas solicitações para o mesmo esquema no mesmo item.

Uma nota curta acima do item diz que tipo de solicitação é e, em uma página com várias perguntas, nomeia a pergunta:

• Cega. A nota diz "Label this one yourself. Suggestions are off for this item." O item continua cego para essa pessoa depois que ela salva, ao recarregar a página e ao voltar.
• Verificação. A resposta da máquina vem preenchida, e a nota diz para mantê-la se estiver certa e alterá-la se não estiver. A página registra a resposta pré-preenchida, então você pode medir com que frequência as pessoas a aceitam. Nada é salvo até a pessoa agir, então uma página deixada aberta não responde por ela. Esquemas cujas respostas a página não consegue pré-preencher (segmentos de tempo, objetos 3D, traces de agentes) são servidos às cegas.
• Resolução. Nenhum rótulo de máquina pôde ser aceito, então a resposta da pessoa é o rótulo.

Uma solicitação que alguém mantém sem responder por runtime.hold_minutes (60 por padrão) volta para o conjunto disponível e sai da página dessa pessoa. Um rótulo salvo em um item que o motor não serviu àquela pessoa nunca fecha a solicitação de outra pessoa, e o motor o guarda como rótulo orgânico. Quando uma nova certificação aceita rótulos de máquina, o motor cancela as solicitações abertas de verificação e de resolução nos itens que agora cobre. As solicitações que uma pessoa já tem em mãos continuam com ela, e a resposta dela substitui o rótulo de máquina.

O contador de progresso conta as solicitações que a pessoa ainda pode pegar, não o corpus. Quando ainda não há nada a fazer, o anotador vê uma página de espera curta e recebe novas solicitações conforme o planejador as abre. Quando nada mais vai chegar, porque todos os itens têm rótulo, o orçamento de rótulos humanos acabou ou a pessoa atingiu seu próprio limite, a participação dela termina como de costume, com as páginas pós-estudo e, em uma plataforma de crowdsourcing, o código de conclusão. Ninguém termina antes da primeira passagem do planejador.

O Modo bolso também serve solicitações do motor, um lote completo de cada vez, e pede mais antes de dizer "All caught up". O Modo bolso nunca mostra uma resposta de máquina, então uma solicitação de verificação servida ali é registrada como cega, a menos que a página de desktop já tenha mostrado a resposta àquela pessoa. Nos cartões de resolução e de arbitragem, ele mostra a mesma nota que a página de desktop.

A página de administração

Quando o motor está ligado, o painel de administração tem um link para Labeling engine em /admin/labeling-engine. Todos os gráficos da página também têm uma visualização em tabela. A página mostra:

• o status, a cobertura e o número da inspeção de cada contrato, e quantos rótulos ainda faltam, com a afirmação completa que ele faz (um contrato não cumprido declara sua meta, não uma garantia);
• os intervalos de cada contrato ppi, ao lado dos intervalos obtidos só com pessoas;
• um aviso para uma fonte cuja última execução falhou ou cujas respostas foram todas erros;
• a curva de erro contra cobertura do último nível da cascata, com o limite superior garantido e a meta;
• um diagrama de confiabilidade por nível, que plota a confiança declarada contra a fração de acertos nos rótulos humanos, com ECE e Brier score, e com as faixas de poucos rótulos desenhadas mais claras;
• as auditorias de rótulos aceitos, como erros em relação à meta, e se há auditorias de menos para concluir algo;
• as solicitações a pessoas por finalidade e status;
• o registro de chamadas a modelos, das mais recentes para as mais antigas, com tokens, latência e custo; e
• botões para executar uma passagem do planejador, certificar agora e abrir o certificado.

Aberta sem uma sessão de administrador, a página leva ao formulário de chave do painel. Com o motor desligado, ela informa isso e nomeia a chave que o liga.

Leitura adicional

• Contratos do motor de rotulagem: os seis tipos de contrato e o que cada um testa
• Configuração do motor de rotulagem: todas as chaves de labeling_engine
• Linha de comando, REST API, ferramentas MCP e SDK
• Migrar para o motor de rotulagem a partir de icl_labeling, judge_calibration e pre_annotation
• Modo Solo, para um especialista trabalhando com um LLM
• Pré-anotação com LLM e concordância de juízes LLM

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