Skip to content
Annunci9 min di lettura

Potato 2.3: annotazione agentica, Solo Mode e Best-Worst Scaling

Potato 2.3.0 aggiunge Solo Mode per l'etichettatura congiunta tra umano e LLM, l'annotazione di tracce di agenti, Best-Worst Scaling, login SSO e OAuth, l'esportazione Parquet e 15 progetti demo.

Potato Team

Nota: questo post descrive Potato 2.3 com'era al rilascio, a marzo 2026. Diverse chiavi di configurazione che compaiono qui sotto sono state rinominate o sostituite nelle versioni successive, e la sintassi attuale è nella documentazione. Non copiare questi blocchi in un progetto che usa una versione attuale di Potato.

Potato 2.3.0 aggiunge Solo Mode, un flusso di etichettatura tra umano e LLM che attraversa dieci fasi documentate, oltre all'annotazione di tracce di agenti con undici convertitori di tracce registrati, Best-Worst Scaling con tre metodi di punteggio, login SSO e OAuth per Google, GitHub e provider OIDC generici, l'esportazione Parquet e 15 progetti demo. Le note di rilascio registrano 50 o più commit dalla 2.2.0 e correzioni per 12 vulnerabilità di sicurezza in 8 moduli.

Il rilascio segue un cambiamento in ciò che si annota. I ricercatori che due anni fa etichettavano sentiment ed entità nominate oggi smontano tracce di agenti in più passaggi, confrontano in blocco gli output dei modelli e costruiscono dataset per compiti che non esistevano quando è stato progettato l'insieme di schemi di Potato. Solo Mode e il lavoro sulle tracce di agenti puntano entrambi a questo cambiamento.

Aggiornamento

bash
pip install --upgrade potato-annotation==2.3.0

L'esportazione Parquet richiede PyArrow 12.0.0 o successivo, da installare a parte:

bash
pip install "pyarrow>=12.0.0"

Annotazione di tracce di agenti

L'esecuzione di un agente è una sequenza di chiamate a strumenti, passaggi di ragionamento e output intermedi, e appiattirla in testo semplice elimina la struttura che un valutatore ha bisogno di vedere. Potato 2.3 visualizza invece le tracce attraverso il sistema di display, così la traccia si presenta come una conversazione con valutazioni associate ai singoli turni.

Il display si dichiara in instance_display, con gli schemi di valutazione per turno annidati sotto il campo che contiene la conversazione:

yaml
instance_display:
  layout:
    direction: vertical
    gap: 16px
  fields:
    - key: task_description
      type: text
      label: "Task"
    - key: conversation
      type: dialogue
      label: "Agent Trace"
      span_target: true
      display_options:
        show_turn_numbers: true
        alternating_shading: true

Nella 2.3 sono due i tipi di display che gestiscono il lavoro sugli agenti. Il display dialogue mostra una traccia come turni e supporta l'annotazione di span su di essi, mentre interactive_chat copre le conversazioni a cui l'annotatore partecipa invece di rileggerle. È l'impostazione span_target: true a permettere agli annotatori di evidenziare un passaggio all'interno di un turno, ed è così che allucinazioni e affermazioni non supportate vengono segnate nel punto in cui compaiono.

Le tracce di altri framework entrano tramite il convertitore, che in questo rilascio registra undici formati: openai, anthropic, swebench, otel, mcp, multi_agent, langchain, langfuse, react, webarena e atif.

bash
python -m potato.trace_converter -i traces.json -f react -o data/traces.jsonl

Solo Mode

L'etichettatura con più annotatori richiede di assumere, formare e coordinare persone, e in molti progetti di ricerca il collo di bottiglia è questa logistica, più che l'interfaccia di annotazione. Solo Mode affianca invece a un esperto del dominio un LLM. L'umano etichetta, l'LLM propone, ogni correzione torna nel prompt, e l'umano cede una parte sempre maggiore della coda man mano che i due convergono.

Il flusso attraversa dieci fasi documentate: configurazione, revisione del prompt, sintesi dei casi limite, etichettatura dei casi limite, validazione del prompt, annotazione in parallelo, risoluzione dei disaccordi, revisione periodica, etichettatura autonoma e validazione finale. Non tutti i progetti passano per tutte le fasi.

yaml
solo_mode:
  enabled: true
 
  labeling_models:
    - endpoint_type: "ollama"
      model: "qwen3:4b"
      endpoint_url: "http://localhost:11434"
      max_tokens: 256
      temperature: 0.1
 
  revision_models:
    - endpoint_type: "ollama"
      model: "qwen3:4b"
      endpoint_url: "http://localhost:11434"
 
  uncertainty:
    strategy: "direct_confidence"
 
  thresholds:
    end_human_annotation_agreement: 0.90
    minimum_validation_sample: 20
    confidence_low: 0.5
    periodic_review_interval: 50
 
  instance_selection:
    low_confidence_weight: 0.4
    diversity_weight: 0.3
    random_weight: 0.2
    disagreement_weight: 0.1
 
  state_dir: "solo_state"

I quattro pesi di instance_selection decidono quali elementi meritano l'attenzione di una persona. Un peso di 0.4 sulla bassa confidenza e di 0.3 sulla diversità indirizza la maggior parte del tempo dell'umano verso le istanze su cui il modello è incerto, mantenendo una copertura del resto della distribuzione sufficiente a notare un errore sistematico. Lo 0.2 sul campionamento casuale è ciò che dà senso alla stima di accordo in end_human_annotation_agreement, perché un tasso di accordo calcolato solo sulle istanze difficili non è il tasso che si ottiene sul corpus.

Solo Mode include 85 test di integrazione ed end-to-end, una guida per sviluppatori e due progetti di esempio in examples/advanced/solo-mode/ e examples/advanced/simple-solo-mode/. Parti da quello semplice, che funziona con un modello Ollama locale e non richiede una chiave API, così la prima cosa che valuti è se il flusso si adatta al tuo compito, non se il modello vale quanto costa.

Best-Worst Scaling

Best-Worst Scaling mostra all'annotatore una tupla di elementi, di solito quattro, e chiede solo il migliore e il peggiore secondo un criterio. Queste due scelte implicano un insieme di confronti a coppie, e i punteggi su molte tuple sovrapposte si collocano su una scala reale, a partire da giudizi più rapidi da esprimere di una valutazione.

yaml
annotation_schemes:
  - annotation_type: bws
    name: sentiment_bws
    description: "Sentiment Intensity"
    best_description: "Which sentence expresses the MOST positive sentiment?"
    worst_description: "Which sentence expresses the LEAST positive sentiment?"
    tuple_size: 4
    sequential_key_binding: true

Sulle tuple raccolte si applicano tre metodi di punteggio. counting è la baseline trasparente, con (best_count - worst_count) / appearances, non richiede dipendenze aggiuntive ed è deterministico. bradley_terry stima un modello di confronto a coppie e produce parametri di forza in scala logaritmica. plackett_luce stima un modello di ranking completo. Entrambi i metodi basati su modelli richiedono pip install choix.

bash
python -m potato.bws_scoring --config config.yaml --method bradley_terry

I punteggi finiscono in bws_scores.tsv nella directory di output, con punteggio, posizione, conteggi di migliore e peggiore e apparizioni di ogni elemento. La dashboard di amministrazione ha una scheda BWS Scoring che esegue lo stesso calcolo con un pulsante e mostra i risultati in una tabella.

SSO e OAuth

Un deployment che gli annotatori raggiungono via internet ha bisogno di account veri, e la 2.3 aggiunge OAuth 2.0 e OpenID Connect perché possano usare l'identità che hanno già. Sono supportati Google, GitHub e qualsiasi provider OIDC generico, e l'accesso può essere limitato per dominio email o per organizzazione GitHub.

yaml
authentication:
  method: "oauth"
  providers:
    google:
      client_id: ${GOOGLE_CLIENT_ID}
      client_secret: ${GOOGLE_CLIENT_SECRET}
  user_identity_field: "email"
 
secret_key: ${POTATO_SECRET_KEY}

Aggiungi questo blocco alla tua configurazione. Porta con sé due requisiti. OAuth richiede un deployment in HTTPS, con localhost esente durante lo sviluppo, e richiede una secret_key stabile, perché una chiave di firma che cambia a ogni riavvio invalida le sessioni che il login ha già emesso. Registra l'URI di reindirizzamento presso il tuo provider come https://your-domain.com/auth/callback/google, sostituendo il nome del provider.

Esportazione Parquet

I dati di annotazione finiscono sempre più spesso in strumenti di analisi che si aspettano un formato colonnare, quindi la 2.3 aggiunge Parquet al registro delle esportazioni. Un'esportazione produce fino a tre tabelle: annotations.parquet con una riga per istanza e annotatore, spans.parquet con una riga per annotazione di span, e items.parquet con i dati di origine.

bash
python -m potato.export -c config.yaml -f parquet -o ./export/

Le opzioni si passano da riga di comando invece di essere configurate nel progetto, e il codec di compressione è uno tra snappy (il predefinito), gzip, zstd, lz4 o none:

bash
python -m potato.export -c config.yaml -f parquet -o ./export/ \
    --option compression=gzip --option include_items=false

Le tabelle si uniscono sulla chiave dell'istanza, anche se il nome della colonna cambia dall'una all'altra: annotations.parquet e spans.parquet hanno instance_id, mentre items.parquet ha item_id. È questo che rende l'esportazione utilizzabile da DuckDB senza caricare prima nulla in pandas:

python
import duckdb
duckdb.sql("""
  SELECT i.item_id, a.user_id, a.*
  FROM './export/annotations.parquet' a
  JOIN './export/items.parquet' i ON a.instance_id = i.item_id
""")

annotations.parquet ha una riga per istanza e annotatore, con ogni schema di annotazione appiattito in una propria colonna, quindi non esiste una colonna generica value da selezionare. Uno schema che memorizza più risposte insieme si espande in sottocolonne con il punto, chiamate <scheme>.<part>.

Correzioni di sicurezza

Il rilascio corregge 12 vulnerabilità di sicurezza in 8 moduli, insieme a problemi di XSS, robustezza e integrità dei dati in 25 file, e a una cancellazione a cascata degli span che iterava sulle chiavi del dizionario invece che sui valori e lasciava indietro record di collegamento. Un audit delle dipendenze ha portato le dipendenze Python e JavaScript alle versioni attuali.

Due delle altre correzioni potrebbero aver modificato dati che hai già raccolto. Un crash sul booleano has_free_response (issue #111) e un loop di navigazione su tutte le fasi incidevano sul fatto che le annotazioni venissero registrate come previsto, e la gestione delle virgolette nel multirate dinamico incideva su come quei valori venivano scritti. Se hai condotto uno studio sulla 2.2 con opzioni a risposta libera o schemi multirate, controlla l'output prima di considerarlo definitivo.

Progetti demo

Il rilascio include 15 progetti demo in demo/, numerati nell'ordine in cui si basano l'uno sull'altro, da 01-sentiment-admin a 15-agentic-chat. Coprono span, layout di moderazione personalizzati, classificazione di immagini, emozioni nell'audio, video, elementi multimodali, adjudication, slider, bounding box, alberi delle dipendenze, annotazione ELAN a livelli e chat agentica. Ogni directory demo contiene un config.yaml e la sua data/, e l'insieme condivide uno script che genera i contenuti multimediali necessari alle demo basate su media.

bash
# From the repository root: generates the demo data, then starts all 15 servers
bash demo/launch.sh

Per il changelog completo, con ogni correzione citata sopra, consulta le note di rilascio della v2.3.0 nel repository. Segnala i problemi su GitHub o apri una discussione in GitHub Discussions.