Il motore di etichettatura

Il motore di etichettatura etichetta un dataset con dei modelli e usa le persone per misurare quanto spesso i modelli sbagliano. In un contratto dichiari che cosa devono soddisfare le etichette finali, per esempio "al massimo il 5% delle etichette automatiche accettate è sbagliato, con una confidenza del 90%". Il motore chiede alle persone le etichette che gli servono per testare questa affermazione, accetta le etichette automatiche supportate dal test e manda gli item rimanenti alle persone. Il risultato è il dataset più un certificato che registra che cosa è stato testato e su quante etichette umane.

Il motore è disponibile da Potato 2.11. Il server di annotazione, la riga di comando potato label, la REST API, il server MCP e un Python SDK lo pilotano tutti sullo stesso file engine.sqlite nella directory del task.

Quando il motore è adatto a uno studio

Il motore conviene quando le persone non possono etichettare tutto e un modello può etichettarne la maggior parte. Se le persone etichetteranno comunque ogni item, il motore non aggiunge nulla, ed è meglio una normale strategia di assegnazione. Si adatta a tre situazioni:

• Hai più item di quanti le persone possano etichettare e un modello che ha ragione nella maggior parte dei casi.
• Devi riportare quanto sono buone le etichette, non solo che le ha prodotte un modello, per un articolo, il rilascio di un dataset o un training set che userà qualcun altro.
• Stai valutando un modello o un agente con un giudice LLM e devi sapere se il giudice può sostituire le persone.

Dalla predizione del modello all'etichetta finale

Il motore conserva in un unico archivio le predizioni dei modelli, le richieste alle persone e i risultati dei contratti, e ogni item attraversa gli stessi sei passi:

1. Le fonti sono i modelli. Una fonte può essere un LLM, un modello visione-linguaggio, un modello decisionale (Laya, Jev o OpenJev), un object detector, un giudice LLM, un modello addestrato sulle etichette dello studio stesso, una giuria di altre fonti o etichette che hai già. Ogni fonte registra una confidenza con ogni predizione.
2. La cascata ordina le fonti. Un item va alla prima fonte e, se il contratto non accetta quella risposta, ci prova la fonte successiva. Dopo l'ultima fonte l'item va a una persona.
3. Le richieste sono ciò che il motore chiede di fare alle persone. Ogni richiesta registra perché è stata creata (ad esempio calibrazione, certificazione, verifica, audit), la probabilità che il suo item fosse campionato e se la persona poteva vedere una risposta della macchina. Le richieste di calibrazione vengono estratte a caso e sono sempre in cieco.
4. I contratti testano le etichette automatiche rispetto alle etichette umane sul campione casuale. Metà di quel campione (la partizione dev) sceglie la regola di accettazione, e l'altra metà (la partizione cert) la testa. Lo stato di un contratto è met, insufficient (servono altre etichette, con una stima di quante), infeasible, violated o stale.
5. La risoluzione assegna a ogni item la sua etichetta finale. L'etichetta è un'etichetta automatica accettata sotto un contratto soddisfatto, l'etichetta di una persona, oppure è in sospeso.
6. Il certificato registra il risultato di ogni contratto, la cascata con le versioni di modelli e prompt, quante etichette umane sono andate a ciascuno scopo, la spesa per i modelli e un digest del log delle chiamate.

Le regole dietro le garanzie

Un contratto soddisfatto è un'affermazione statistica sul campione casuale che le persone hanno etichettato, e vale per il modo in cui quel campione viene estratto e usato. Il motore applica cinque regole:

• Le richieste in cieco non mostrano risposte della macchina. Finché una persona ha in carico una richiesta di calibrazione, certificazione o audit, il server nasconde ogni risposta della macchina per quell'item. La pre-annotazione, il giudice inline, l'assistente IA (che risponde 403) e i pulsanti di aiuto IA sono tutti disattivati. Un'etichetta data dopo aver visto la risposta della macchina non è un controllo indipendente di quella risposta.
• Selezione e test usano etichette diverse. Le soglie vengono scelte sulle etichette dev e testate sulle etichette cert. Ogni nuovo test sulle etichette cert viene eseguito a un livello più severo, quindi ricertificare finché un test non passa non gonfia la confidenza.
• Solo le persone certificano. Gli annotatori automatici possono partecipare all'inferenza dell'etichetta finale, mai alle etichette su cui un contratto viene testato.
• Una modifica rende il certificato obsoleto. Cambiare una fonte, un prompt, una soglia o lo schema segna come stale ogni contratto interessato e sposta le sue etichette accettate in pending_recert finché il contratto non viene testato di nuovo. Le etichette umane vengono conservate.
• Le predizioni dei modelli non occupano posti da annotatore. Le predizioni del motore non contano nei limiti di annotatori per item.

Il motore non verifica che le etichette umane siano corrette. Ogni contratto misura le macchine rispetto alle persone che hanno etichettato il campione, quindi un contratto testato su persone inaffidabili certifica l'accordo con persone inaffidabili. Usa il controllo di qualità, la sovrapposizione (humans.overlap) e il contratto no_worse_than_human per verificare anche le persone.

Un primo studio

Potato include tre studi di esempio in examples/labeling-engine/, uno per il testo, uno per le immagini e uno per le tracce degli agenti. La tabella elenca le fonti e i contratti usati da ciascuno:

L'esempio di testo si esegue con quattro comandi. Il primo etichetta ogni item con la cascata ed estrae il primo campione in cieco, il secondo serve quel campione alle persone, e gli ultimi due testano i contratti e stampano il certificato una volta che le persone hanno etichettato il campione:

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

Per aggiungere il motore al tuo studio, aggiungi queste chiavi a una configurazione che ha già data_files e uno schema di annotazione chiamato sentiment. Il contratto chiede che al massimo il 10% delle etichette automatiche accettate sia sbagliato, con una confidenza del 90%, e budgets.human_labels limita quante richieste umane il motore può aprire:

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

La fonte ricava la sua confidenza dalle log-probabilità dei token (method: logprob), che richiede una chiamata per item ed è di solito il meglio calibrato tra i metodi di confidenza. Configurazione elenca ogni chiave, e Contratti spiega che cosa testa ogni contratto.

Le richieste nella pagina di annotazione

Con assignment_strategy: engine, agli annotatori vengono servite le richieste del motore, a partire da quelle con priorità più alta. L'ordine è: aggiudicazione, certificazione, calibrazione, annotatori aggiuntivi per i contratti distributivi, item che nessuna macchina ha potuto etichettare, verifica e audit. Le richieste di calibrazione vengono servite in un ordine casuale fisso, alternando richieste dev e cert. A una persona vengono date insieme tutte le richieste aperte su un item, una per schema, e mai due richieste per lo stesso schema sullo stesso item.

Una breve nota sopra l'item indica di che tipo di richiesta si tratta e, in una pagina con più domande, nomina la domanda:

• In cieco. La nota dice "Label this one yourself. Suggestions are off for this item." L'item resta in cieco per quella persona anche dopo che l'ha salvato, al ricaricamento e tornando indietro.
• Verifica. La risposta della macchina è precompilata, e la nota dice di tenerla se è giusta e di cambiarla se non lo è. La pagina registra la risposta precompilata, così puoi misurare quanto spesso le persone la accettano. Non viene salvato nulla finché la persona non agisce, quindi una pagina lasciata aperta non risponde al suo posto. Gli schemi le cui risposte la pagina non può precompilare (segmenti temporali, oggetti 3D, tracce degli agenti) vengono invece serviti in cieco.
• Risoluzione. Non è stato possibile accettare alcuna etichetta automatica, quindi la risposta della persona è l'etichetta.

Una richiesta che qualcuno tiene in carico senza rispondere per runtime.hold_minutes (60 per default) torna nel pool e sparisce dalla sua pagina. Un'etichetta salvata su un item che il motore non ha servito a quella persona non chiude mai la richiesta di qualcun altro, e il motore la conserva come etichetta organica. Quando una nuova certificazione accetta etichette automatiche, il motore annulla le richieste di verifica e di risoluzione aperte sugli item che ora copre. Le richieste che una persona ha già in carico restano a lei, e la sua risposta sostituisce l'etichetta automatica.

Il contatore di avanzamento conta le richieste che una persona può ancora prendere, non il corpus. Quando non c'è ancora nulla da fare, l'annotatore vede una breve pagina di attesa e riceve nuove richieste man mano che il planner le apre. Quando non arriverà altro, perché ogni item ha un'etichetta, il budget di etichette umane è esaurito o la persona ha raggiunto il proprio limite, la sua parte termina come al solito con le pagine post-studio e, su una piattaforma di crowdsourcing, il codice di completamento. Nessuno ha finito prima del primo passaggio del planner.

Anche Pocket Mode serve le richieste del motore, un batch completo alla volta, e ne chiede altre prima di dire "All caught up". Pocket Mode non mostra mai una risposta della macchina, quindi una richiesta di verifica servita lì viene registrata come in cieco, a meno che la pagina desktop non avesse già mostrato la risposta a quella persona. Sulle schede di risoluzione e di aggiudicazione mostra la stessa nota della pagina desktop.

La pagina di amministrazione

Quando il motore è attivo, la dashboard di amministrazione ha un link a Labeling engine in /admin/labeling-engine. Ogni grafico della pagina ha anche una vista a tabella. La pagina mostra:

• lo stato, la copertura, il numero di analisi di ogni contratto e quante altre etichette gli servono, con l'affermazione completa che fa (un contratto non soddisfatto indica il suo obiettivo, non una garanzia);
• gli intervalli di ogni contratto ppi, accanto agli intervalli ottenuti dalle sole persone;
• un avviso per una fonte la cui ultima esecuzione è fallita o le cui risposte sono state tutte errori;
• la curva errore-copertura dell'ultimo livello della cascata, con il limite superiore garantito e l'obiettivo;
• un diagramma di affidabilità per livello, che mette a confronto la confidenza dichiarata con la quota di risposte corrette sulle etichette umane, con ECE e Brier score, e con i bin che hanno poche etichette disegnati più chiari;
• gli audit delle etichette accettate, come errori rispetto all'obiettivo, e se gli audit sono troppo pochi per dirlo;
• le richieste umane per scopo e stato;
• il log delle chiamate ai modelli, dalle più recenti, con token, latenza e costo; e
• i pulsanti per eseguire un passaggio del planner, certificare subito e aprire il certificato.

Aperta senza una sessione di amministrazione, la pagina rimanda al modulo della chiave della dashboard. Con il motore disattivato, lo dice e nomina la chiave che lo attiva.

Approfondimenti

• Contratti del motore di etichettatura: i sei tipi di contratto e che cosa testa ciascuno
• Configurazione del motore di etichettatura: ogni chiave di labeling_engine
• Riga di comando, REST API, strumenti MCP e SDK
• Migrare al motore di etichettatura da icl_labeling, judge_calibration e pre_annotation
• Modalità Solo, per un singolo esperto che lavora con un LLM
• Pre-annotazione con LLM e accordo dei giudici LLM

Per i dettagli di implementazione, consulta la documentazione sorgente.