I trainer di Potato, raggruppati per compito

Novità nella v2.14.0

L'addestramento di modelli di Potato ha 38 trainer, e ciascun trainer adatta un tipo di modello alle risposte di un tipo di schema di annotazione. Le tabelle di questa pagina elencano ogni trainer per compito, con gli schemi da cui il trainer impara, gli item che il trainer legge, l'installazione che richiede, la pre-etichetta che riscrive e il punteggio held-out che ogni esecuzione riporta. La pagina è per chi gestisce uno studio e deve scegliere un trainer prima di una prima esecuzione, o verificare se uno schema può essere addestrato. Chiavi di configurazione, backend e regole del write-back si trovano nella pagina di configurazione. La tabella completa dei parametri di ciascun trainer è nella sezione del trainer nel riferimento upstream, e ogni nome di trainer qui sotto rimanda a quella sezione.

Trainer offerti per ogni schema

La pagina Training in /admin/training offre a ogni schema solo i trainer adatti al tipo dello schema e alla modalità dei suoi item, per esempio testo, immagini o audio. Un trainer che il progetto non può eseguire resta nell'elenco con il motivo, come decision-calibrate, che mostra "no decision model is configured" finché il progetto non ha un modello decisionale. Un trainer a cui mancano i pacchetti è elencato come "not installed", con il comando che installa i pacchetti. Finché non scegli un trainer, sklearn-text è selezionato ovunque sklearn-text sia adatto. Un'esecuzione avviata per uno schema che non esiste, o per uno schema che il trainer non può imparare, viene rifiutata con HTTP 400 prima che venga costruito qualsiasi cosa.

Ogni esecuzione si addestra su uno schema. La pagina Training ne invia uno, e l'API di addestramento accetta un elenco di schemi ma ogni trainer adatta solo il primo dell'elenco. Per addestrare due schemi, avvia due esecuzioni.

Nelle tabelle seguenti, la colonna Pre-etichetta indica che cosa un'esecuzione scrive su un item una volta che lo schema è elencato sotto writeback.schemas. Gli item della partizione train di un'esecuzione non ricevono mai una pre-etichetta, e una pre-etichetta diventa la risposta di un annotatore solo quando l'annotatore la modifica o passa oltre. La colonna Punteggio held-out indica la metrica principale dell'esecuzione, calcolata sugli item val e test rispetto alle etichette risolte degli annotatori. Un item con un'etichetta e senza predizione conta come sbagliato. Un trainer non può quindi alzare il punteggio saltando gli item difficili. Punteggi held-out nel riferimento upstream definisce ogni metrica.

Installare i trainer

sklearn-text non richiede nulla oltre a una normale installazione di Potato, perché scikit-learn è una dipendenza di base. I trainer per testo, immagini, audio e LLM richiedono PyTorch e transformers. Un solo extra installa i pacchetti di tutti e quattro i gruppi:

pip install "potato-annotation[train]"

Gli extra più ristretti [train-text], [train-vision], [train-audio] e [train-llm] installano ciascuno un gruppo, e la colonna Installazione qui sotto indica l'extra più ristretto che copre ogni trainer, come in pip install "potato-annotation[train-vision]". Nessuno degli extra di addestramento fa parte di potato-annotation[all], perché PyTorch è un'installazione di vari gigabyte. Alcuni trainer richiedono pacchetti esterni a [train]:

• ultralytics-detect e ultralytics-segment richiedono pip install ultralytics.
• cellpose richiede pip install cellpose e funziona con Cellpose 3 o Cellpose 4.
• laya-finetune richiede [decision], e openjev-finetune richiede pip install wev-ai.
• rdkit-property richiede [chemistry], volume-unet richiede [volumes], video-track richiede opencv-python, e i segnali WFDB o Parquet richiedono [signals]. Le immagini di vetrini interi richiedono [wsi] per openslide.
• L'opzione dp di hf-text-classification e hf-image-classification richiede pip install opacus.

ultralytics-detect, ultralytics-segment e layoutlmv3 ti chiedono di confermare una licenza prima della prima esecuzione. Ultralytics è AGPL-3.0, quindi un modello addestrato e distribuito con uno dei due trainer YOLO ricade nei termini dell'AGPL, e Ultralytics vende una licenza separata per l'uso chiuso. I pesi di LayoutLMv3 sono CC BY-NC-SA 4.0 e non sono per uso commerciale. Per tutti e tre i trainer, la pagina Training chiede conferma, un'esecuzione via API richiede accept_licence: true e un riaddestramento automatico richiede auto_retrain.accept_licence: true. Il codice di Cellpose è BSD-3-Clause, e gli autori di Cellpose pubblicano i pesi preaddestrati di Cellpose con termini propri. Anche le licenze dei checkpoint che indichi in model_name variano. Qwen2.5-VL-3B, per esempio, è sotto la licenza di ricerca Qwen, mentre Qwen2.5-VL-7B è Apache-2.0.

Parametri

I parametri di un'esecuzione provengono da tre luoghi, e ciascuno prevale sul precedente:

1. i valori predefiniti del trainer, elencati nella sezione upstream del trainer;
2. model_training.trainer_params.<trainer> nella configurazione;
3. i params propri dell'esecuzione, cioè il campo Parameters della pagina Training, i params di un'esecuzione via API oppure auto_retrain.params.

Aggiungi trainer_params al blocco model_training per impostare un valore predefinito per ogni trainer che usi:

model_training:
  enabled: true
  trainer_params:
    hf-text-classification:
      model_name: answerdotai/ModernBERT-base
      epochs: 4
    torchvision-detect:
      model_name: fasterrcnn_resnet50_fpn_v2
      score_threshold: 0.4

Il campo Parameters della pagina Training è JSON, compilato da trainer_params per il trainer scelto. Un nome di parametro che il trainer non accetta è un errore. Un nome sotto trainer_params ferma il server all'avvio, e un nome nei params di un'esecuzione ferma l'esecuzione prima che parta. Entrambi gli errori elencano i nomi che il trainer accetta. Per esempio, un score_thresh scritto male sotto torchvision-detect viene segnalato con score_threshold nell'elenco. Potato controlla anche ogni valore rispetto al tipo e all'intervallo del parametro.

Classificatori per testo e immagini

I classificatori imparano dagli schemi a scelta radio, select, likert e multiselect. Una pre-etichetta radio, select o likert seleziona una risposta, e una pre-etichetta multiselect spunta un insieme di etichette. sklearn-text gira su una CPU senza installazioni aggiuntive, e il tutorial sul primo modello percorre un'esecuzione con sklearn-text. Su un corpus di immagini, sklearn-text adatta il classificatore agli embedding di immagini CLIP. setfit è pensato per i primi giorni di un progetto e funziona con circa otto item etichettati per etichetta. Le pagine degli schemi per radio e multiselect, select e scale Likert trattano il lato dell'annotazione.

hf-text-classification esegue il fine-tuning di un transformer e, con lora: true, anche di un LLM decoder come Qwen o Llama. Con soft_targets: true, hf-text-classification si addestra sulla distribuzione dei voti degli annotatori invece che su una sola etichetta risolta. hf-text-classification e hf-image-classification accettano un parametro acquisition che ordina i prossimi item da etichettare di uno schema a etichetta singola per margine, entropia, BALD o distanza coreset, come mostra il tutorial sul modello nel ciclo. Entrambi i trainer accettano anche dp per l'addestramento con DP-SGD tramite Opacus, e il tutorial sulla privacy differenziale percorre un'esecuzione con dp.

Span, relazioni e struttura

I trainer di questo gruppo imparano span con offset di carattere, collegamenti tra span, risposte sui nodi di un albero di conversazione e glosse interlineari. hf-relation addestra un solo encoder a etichettare gli span e a classificare le coppie di span. Un collegamento predetto conta come trovato solo quando il tagger ha trovato anche entrambi gli span del collegamento con i confini giusti. Quando ogni risposta di addestramento di uno schema span_link è un albero di dipendenze, hf-relation decodifica alberi e aggiunge UAS e LAS al punteggio. Un'esecuzione segue gli stessi passi del tutorial sul primo modello, con un trainer e uno schema diversi.

LLM e modelli di ricompensa

I trainer per LLM imparano da risposte a testo libero, preferenze, classifiche e tracce di agenti corrette. llm-sft e llm-dpo addestrano per impostazione predefinita un adattatore LoRA, e lora: {quantize: 4bit} carica il modello di base a 4 bit come QLoRA. reward-model addestra un modello di ricompensa scalare da risposte a confronto, classifiche e best-worst, e ogni predizione tiene le ricompense per opzione accanto alla risposta dello schema. prm-reward valuta ogni passo di una traccia di agente come corretto, neutro o sbagliato. I passi oltre max_length (1.024 token per impostazione predefinita) non vengono né usati per l'addestramento né valutati. Una predizione trajectory_edit viene valutata e salvata ma non viene mai mostrata come pre-etichetta, e il server rifiuta di avviarsi con uno schema trajectory_edit sotto writeback.schemas. Il tutorial sul fine-tuning di LLM tratta SFT, DPO, modelli di ricompensa, modelli di ricompensa di processo e QLoRA.

Rilevamento e segmentazione di immagini

I detector e i segmentatori imparano le forme che gli annotatori disegnano in uno schema image_annotation, e la maggior parte di essi legge anche schemi di microscopia, di mappe e di spettrogrammi. Un detector si addestra sul riquadro di delimitazione di ogni forma, quindi anche uno studio con poligoni o maschere addestra un detector di box. Un segmentatore si addestra sui contorni e lascia fuori i box, e predice poligoni di al più 64 vertici che l'annotatore può modificare punto per punto. cellpose segmenta senza classi, quindi ogni cellula predetta riceve il parametro label, oppure l'etichetta più comune dello schema quando label non è impostato.

sam-finetune esegue il fine-tuning del decoder di maschere di Segment Anything per trasformare un box in un contorno mentre l'encoder di immagini resta congelato. Un'esecuzione sam-finetune traccia i contorni delle pre-etichette a box che un'esecuzione di rilevamento precedente ha riscritto, quindi l'ordine consueto è un'esecuzione di rilevamento con writeback.include_unlabeled: true, poi un'esecuzione sam-finetune sullo stesso schema. Su un Mac, torchvision-detect e torchvision-segment si addestrano sulla CPU e non su Metal. Il tutorial sui modelli per la visione percorre rilevamento, segmentazione, vetrini, microscopia, mappe, Cellpose e SAM.

I trainer per immagini leggono file locali dentro la directory del task o media_directory. Un'immagine http(s) remota non viene scaricata, e una riga la cui immagine è remota o mancante viene esclusa dall'esecuzione e non riceve alcuna predizione. Image items nel riferimento upstream indica i campi da cui Potato legge il percorso di un'immagine.

Vetrini, microscopia, mappe e spettrogrammi

I trainer di rilevamento e segmentazione ridimensionano ogni immagine a poche centinaia di pixel. Per uno schema image_annotation, microscopy o geo_annotation, Potato taglia quindi un'immagine grande in tile quando costruisce il bundle dell'esecuzione. La suddivisione in tile è attiva per impostazione predefinita per i formati di vetrino come .svs e .ndpi e per le immagini il cui lato più lungo è di almeno 4.096 pixel. I tile di uno stesso vetrino finiscono sempre in un'unica partizione, e le forme predette vengono rimappate sull'immagine intera nelle coordinate che il visualizzatore deep-zoom memorizza. La tabella tiling elenca ogni chiave, e il tutorial sui modelli per la visione imposta dimensione dei tile, sovrapposizione e risoluzione per un vetrino.

Le ROI di uno schema microscopy addestrano i trainer di rilevamento e segmentazione e cellpose. Ogni z-slice e ogni istante con ROI viene reso con i canali e il contrasto predefiniti dello schema, e le predizioni tornano come ROI con z e t di ciascuna ROI. Uno schema geo_annotation si addestra sulla mappa di base raster dell'item, cioè un GeoTIFF o un'immagine con un'estensione, e le predizioni tornano come GeoJSON in EPSG:4326 che la mappa mostra come suggerimenti. Una mappa la cui base proviene da un tile server non ha un raster su cui addestrare, e l'esecuzione esclude quegli item con un avviso. Uno schema spectrogram_annotation addestra torchvision-detect e ultralytics-detect su ogni registrazione resa come spettrogramma, e i box tornano in secondi e hertz. Microscopy and maps e Spectrograms nel riferimento upstream danno i dettagli del rendering.

Documenti e modelli visione-linguaggio

layoutlmv3 impara il layout di un documento dalle parole di una pagina e dalle loro posizioni, e vlm-sft esegue il fine-tuning di un modello visione-linguaggio su risposte relative a immagini. Potato non esegue alcun OCR, quindi ogni item di layoutlmv3 richiede un campo words con testo e box di ogni parola. Un import di PAGE XML in modalità regions compila words, e le parole dallo strato di testo di un PDF o da un altro strumento OCR funzionano allo stesso modo. vlm-sft addestra per impostazione predefinita un adattatore LoRA, e i checkpoint reali richiedono una GPU. Un'esecuzione region_caption viene valutata ma non pubblicata, perché le regioni descritte da una didascalia sono una risposta dell'annotatore. Il tutorial sui modelli per la visione tratta entrambi i trainer, e VLM grounding tratta lo schema grounding_eval.

Audio e parlato

I trainer per l'audio leggono registrazioni da file locali che soundfile apre, per esempio WAV o FLAC, e un item il cui audio è un URL viene escluso. hf-audio-tagger etichetta segmenti temporali in uno schema audio_annotation. whisper-asr esegue il fine-tuning di Whisper sui turni di trascrizione corretti dagli annotatori e, per impostazione predefinita, scrive anche una copia CTranslate2 del modello per potato transcripts --transcribe e faster-whisper. diarization esegue il fine-tuning di un encoder del parlato (WavLM per impostazione predefinita) per trovare chi parla e quando. I nomi dei parlanti sono locali a ciascuna registrazione. I box sugli spettrogrammi addestrano i detector descritti in Rilevamento e segmentazione di immagini. Il tutorial sui modelli per l'audio percorre Whisper, diarizzazione, rilevamento su spettrogrammi e tagging audio.

Volumi, nuvole di punti e video

I trainer per 3D e video imparano da volumi dipinti, cuboidi di nuvole di punti e tracce video. volume-unet addestra una U-Net 3D in PyTorch puro sulle maschere che gli annotatori hanno dipinto in volumi CT e MR, e una CT a dimensione piena richiede in pratica una GPU. external-3d esegue un tuo detector 3D tramite i parametri train_command e predict_command e rilegge i cuboidi. Sia OpenPCDet sia MMDetection3D sono adatti, ed entrambi richiedono operatori CUDA compilati sull'host GPU. video-track esegue il fine-tuning di un Faster R-CNN su frame campionati dalle tracce annotate e collega le rilevazioni tra i frame in tracce. Il tutorial su volumi, nuvole di punti e video percorre tutti e tre i trainer.

Scienza

I trainer per la scienza imparano da chimica, spettroscopia, segnali fisiologici ed episodi robotici. rdkit-property risponde a una domanda su una molecola a partire dal fingerprint di Morgan e dai descrittori RDKit della molecola, con un classificatore scikit-learn per le scelte o un regressore per uno slider. peak-cnn predice le posizioni dei picchi su uno spettro e non predice etichette né assegnazioni dei picchi. signal-cnn assegna fasi a epoche fisse o trova intervalli etichettati in EEG, ECG e altri segnali. episode-model predice fasi, un esito e una curva di ricompensa dalle serie di giunti e sensori di un episodio robotico. Il video dell'episodio non viene letto. Picchi, intervalli e risposte sugli episodi compaiono come suggerimenti che l'annotatore rivede, e non come la risposta stessa. Il tutorial sui modelli per la scienza percorre tutti e quattro i trainer, e le pagine degli schemi per strutture chimiche, spettri, serie temporali ed episodi robotici trattano il lato dell'annotazione.

Modelli decisionali

Un modello decisionale restituisce una probabilità per ogni opzione di una domanda, e Potato usa un modello decisionale come fonte del motore di etichettatura o come modello di etichettatura in Solo Mode. I trainer di modelli decisionali adattano un modello decisionale alle etichette dello studio su schemi radio, select, likert e slider, e pongono ogni domanda come la pone il motore di etichettatura. Uno slider viene posto come una valutazione con un'opzione per posizione, fino a 21 posizioni. decision-calibrate non addestra nulla. Il trainer adatta una calibrazione alle probabilità di Jev, OpenJev, laya-serve o Laya e scrive la calibrazione in calibration.json perché la fonte del motore la applichi. decision-calibrate gira solo sul backend local. laya-finetune esegue il fine-tuning di Laya, e openjev-finetune esegue il fine-tuning del modello OpenJev da 8B con l'addestramento LoRA di wev. La model card di OpenJev segnala che parte dei dati di addestramento di OpenJev è solo per ricerca. Verifica quei termini prima dell'uso commerciale.

Bridge di inferenza

I bridge di inferenza usano un modello che gira già altrove e non addestrano nulla. Un'esecuzione con un bridge invia gli item esclusi dall'addestramento al servizio e rilegge le risposte. Con writeback.include_unlabeled: true, l'esecuzione invia anche gli item non etichettati. Le risposte ottengono allora un punteggio held-out rispetto ai tuoi annotatori, il write-back e la revisione, come le risposte di un modello addestrato. Un bridge non prende mai una chiave API nella configurazione. Un parametro indica invece la variabile d'ambiente sul server che contiene la chiave. label-studio-ml chiama /predict di un backend ML di Label Studio e non invia al /webhook del backend gli eventi di annotazione. hf-inference e roboflow girano solo sul backend local. I box di openai-vlm-boxes non hanno confidenza, perché il modello visione-linguaggio non restituisce alcun punteggio. Il tutorial Porta il tuo modello imposta ogni bridge.

Ulteriori letture

• La panoramica dell'addestramento di modelli spiega il ciclo dalle annotazioni alle pre-etichette e la pagina Training.
• La pagina di configurazione documenta ogni chiave model_training, i backend, il write-back e le route.
• Il tutorial sul primo modello esegue sklearn-text dall'inizio alla fine senza GPU.
• Il tutorial sull'addestramento remoto invia le esecuzioni a un server GPU via ssh, a un cluster SLURM o a un agent che interroga il server.
• La guida all'etichettatura assistita da modelli discute quando le pre-etichette del tuo modello aiutano gli annotatori e quando invece li ancorano.
• Il riferimento upstream sull'addestramento di modelli contiene la tabella dei parametri di ogni trainer.