Addestrare modelli di detection e segmentazione sulle annotazioni di immagini

Novità nella v2.14.0

Questo tutorial addestra un detector di oggetti sui bounding box dello studio e mostra i box del detector ai prossimi annotatori come pre-etichette da correggere. Il tutorial è per i responsabili di studi con uno schema image_annotation che hanno letto Addestra il tuo primo modello o conoscono la pagina Training dell'amministratore. La prima metà percorre un ciclo completo con torchvision-detect (box sulle immagini, un'esecuzione di addestramento, write-back, correzioni e una seconda esecuzione), e ogni passo ha girato sulla CPU di un portatile. La seconda metà adatta il ciclo a YOLO, ai contorni, al raffinamento con SAM, alle classi per l'intera immagine, ai vetrini interi, alla microscopia, alle mappe, alle cellule, alle pagine di documenti e ai modelli visione-linguaggio, una sezione per ciascuno.

Installare i trainer per la visione

torchvision-detect esegue il fine-tuning di un detector Faster R-CNN di torchvision. Il trainer richiede torch e torchvision. Potato li esclude entrambi dall'installazione predefinita perché torch è un download di diversi gigabyte. Installa l'extra per la visione sulla macchina che addestra:

pip install "potato-annotation[train-vision]"

Lo stesso extra copre torchvision-segment, hf-image-classification, sam-finetune, layoutlmv3 e vlm-sft. Un trainer di cui mancano i pacchetti compare nella pagina Training come "not installed", con il comando che installa i pacchetti.

Una GPU è facoltativa per il piccolo progetto che segue. Su un Mac con Apple silicon, torchvision-detect e torchvision-segment si addestrano sulla CPU e non su Metal (mps), e il log dell'esecuzione registra il cambio con l'avviso "torchvision-detect does not run on Apple's Metal (mps) with this torch; using the CPU". Nelle misurazioni del gruppo di Potato, un passo di addestramento su Metal alla dimensione di immagine predefinita ha richiesto più tempo di un'epoca intera sulla CPU. Per immagini più grandi o uno studio più ampio, addestra su un server GPU come descrive Addestramento remoto.

Preparare un progetto di immagini

Il progetto richiede tre cose: le immagini, un file di dati che le elenca e una configurazione. Metti le immagini in una cartella chiamata media dentro la cartella del progetto, perché Potato serve <task_dir>/media/ al percorso URL /media/ per impostazione predefinita. Funziona anche una cartella diversa, se la configurazione la indica con media_directory.

shapes/
  config.yaml
  data/images.jsonl
  media/img_001.png
  media/img_002.png
  ...

Ogni riga di data/images.jsonl è un item con un id e il percorso URL dell'immagine:

{"id": "img_001", "image_url": "/media/img_001.png"}

La configurazione definisce uno schema image_annotation con lo strumento bbox e due etichette, e attiva l'addestramento di modelli con il write-back. La configurazione supera python -m potato.validate_cli --strict:

annotation_task_name: "Shape detection (model training)"
task_dir: "."
data_files:
  - "data/images.jsonl"
item_properties:
  id_key: "id"
  text_key: "image_url"
output_annotation_dir: "annotation_output"
 
require_password: false
admin_api_key: "demo-admin-key"
num_annotators_per_item: 1
 
annotation_schemes:
  - annotation_type: "image_annotation"
    name: "objects"
    description: "Draw a box around every circle and every square."
    source_field: "image_url"
    tools: ["bbox"]
    labels:
      - name: "circle"
        color: "#e6194b"
      - name: "square"
        color: "#4363d8"
 
model_training:
  enabled: true
  writeback:
    schemas: ["objects"]
    include_unlabeled: true
    min_confidence: 0.5

Quattro impostazioni danno forma al ciclo:

• source_field: "image_url" indica al widget dell'immagine e al trainer quale campo dell'item contiene l'immagine.
• num_annotators_per_item: 1 dà a ogni immagine un solo annotatore, così le etichette iniziali coprono più immagini diverse possibile.
• writeback.include_unlabeled: true fa predire a ogni esecuzione anche le immagini che nessuno ha ancora etichettato. Senza questa impostazione, un'esecuzione predice solo le immagini val e test escluse dall'addestramento, e quelle immagini hanno già box umani.
• writeback.min_confidence: 0.5 trattiene la predizione di un'immagine quando il punteggio medio dei suoi box è inferiore a 0.5. La soglia vale per l'intera immagine, quindi gli annotatori non vedono mai metà dei box di un'immagine.

Avvia il server dall'interno della cartella del progetto:

potato start config.yaml -p 8000

Etichettare un insieme iniziale

torchvision-detect rifiuta di eseguire l'addestramento con meno di 20 immagini annotate nella partizione train, e la suddivisione predefinita assegna a train il 70% delle immagini etichettate. Etichetta almeno 30 immagini, e di più se gli oggetti variano. Disegna i box a mano su http://localhost:8000. Un'immagine senza box è esclusa dall'addestramento, perché un detector non sa distinguere un'immagine senza oggetti da un'immagine che nessuno ha finito. Disegna ogni oggetto di un'immagine che invii.

Per provare il ciclo prima che qualcuno etichetti, il simulatore di utenti può disegnare box da un file gold. Ogni voce gold indica l'id dell'immagine e le forme dello schema in coordinate normalizzate:

[
  {"id": "img_001", "objects": [
    {"type": "bbox", "label": "circle",
     "coordinates": {"x": 0.158, "y": 0.849, "width": 0.106, "height": 0.146}}
  ]}
]

python -m potato.simulator --server http://localhost:8000 --users 3 \
  --strategy gold_standard --competence good=1.0 --max-annotations 20 \
  --gold-file data/gold.json --sequential --fast-mode --no-export

Il simulatore ridisegna ogni box gold con qualche pixel di jitter, e al livello good il simulatore tralascia o sbaglia anche qualche oggetto, come a volte fa un annotatore attento. Nel nostro test su 80 immagini sintetiche, tre annotatori simulati hanno etichettato 60 immagini in circa un secondo.

Addestrare torchvision-detect

Apri http://localhost:8000/admin, inserisci la chiave di amministratore demo-admin-key e apri http://localhost:8000/admin/training. Scegli objects come schema e torchvision-detect come trainer, lascia vuoto Parameters e fai clic su Train now. La stessa esecuzione parte da uno script con:

curl -X POST -H "X-API-Key: demo-admin-key" -H "Content-Type: application/json" \
  http://localhost:8000/admin/training/api/runs \
  -d '{"trainer": "torchvision-detect", "schemas": ["objects"]}'

L'esecuzione parte dai pesi COCO di torchvision e mette sul detector una nuova testa per i box con le due etichette dello schema. Torch scarica i pesi COCO nella propria cache alla prima esecuzione. I valori predefiniti sono l'architettura piccola fasterrcnn_mobilenet_v3_large_fpn, 15 epoche, 4 immagini per passo e arresto anticipato dopo 4 epoche senza un mAP val migliore. Ogni forma si addestra come bounding box della forma, quindi uno studio i cui annotatori hanno disegnato poligoni addestra comunque un detector di box. Con più annotatori per immagine, l'esecuzione si addestra sull'unica risposta intera scelta per l'immagine da model_training.aggregation, perché i box di due persone raramente coincidono esattamente.

Sulla CPU Apple M4 Pro che abbiamo usato, 37 immagini di addestramento di 320 per 240 pixel si sono addestrate in circa 106 secondi, e l'esecuzione si è fermata dopo 5 epoche. I file dell'esecuzione finiscono in annotation_output/training/runs/<run_id>/, con il detector addestrato in artifacts/model/detector.pt. Le impostazioni dell'esecuzione e il dispositivo usato sono in artifacts/model_card.json.

Leggere il punteggio held-out

Ogni esecuzione valuta il detector sulle immagini su cui non si è mai addestrato. La metrica principale per uno schema image_annotation è map_50, la precisione media COCO in cui un box predetto conta come corrispondenza quando si sovrappone al bounding box di un oggetto annotato con un IoU di almeno 0.5. La pagina dell'esecuzione registra anche map_50_95, la media sulle soglie IoU da 0.5 a 0.95. I box di due annotatori per lo stesso oggetto raramente si sovrappongono con un IoU di 0.9, quindi le soglie più severe misurano in parte quanto le persone disegnano in modo coerente. Per questo Potato mette in primo piano la soglia 0.5. Misurare l'accordo sui bounding box mostra come verificare direttamente questa coerenza.

Il detector conserva il checkpoint dell'epoca con il miglior punteggio val, quindi la metrica principale viene dalla partizione test quando test contiene immagini. La tabella Runs mostra la metrica principale nella colonna Held-out score. La pagina dell'esecuzione elenca n_train, n_boxes, dimensione e copertura di ogni partizione e il numero di oggetti annotati e predetti su val e test. Nella nostra esecuzione di prova sulle 80 immagini sintetiche di cerchi e quadrati colorati, il detector ha ottenuto 0.99 su map_50 di test. Le forme sintetiche sono molto più facili da trovare degli oggetti reali, quindi giudica il punteggio sulle tue immagini.

Controllare le pre-etichette

Dopo un'esecuzione riuscita, Potato scrive i box del detector nel campo predictions di ogni immagine idonea. GET /admin/training/api/status riporta l'esito nel campo writeback della risposta, con n_written per le immagini che hanno ricevuto pre-etichette e un conteggio per ogni motivo per cui un'immagine è stata trattenuta, ad esempio n_skipped_low_confidence sotto min_confidence e n_skipped_train_split per le immagini su cui l'esecuzione si è addestrata. Le immagini della partizione train non ricevono mai pre-etichette, perché la confidenza di un modello sui propri dati di addestramento non dice nulla sulle immagini nuove.

Accedi a http://localhost:8000 con un nuovo nome utente. Ogni immagine non etichettata che ha superato i controlli del write-back si apre con i box del detector già disegnati. Ogni box è archiviato con source: ai e il punteggio del detector come confidence. L'annotatore sposta o ridimensiona un box, cambia un'etichetta, elimina un falso rilevamento e disegna ogni oggetto che il detector ha mancato. I box diventano la risposta dell'annotatore quando li modifica o passa all'immagine successiva. Una pre-etichetta non viene mai salvata mentre l'annotatore si limita a guardare l'immagine. La coda di revisione del modello serve le immagini pre-etichettate partendo dalle meno sicure, e un verdetto correct di un revisore mette l'immagine nella partizione train di ogni esecuzione successiva.

Riaddestrare sui box corretti

Ogni immagine corretta diventa un'etichetta umana per l'esecuzione successiva. Avvia un'altra esecuzione di torchvision-detect dalla pagina Training dopo che gli annotatori hanno lavorato su un gruppo di immagini pre-etichettate. Una nuova esecuzione sostituisce la predizione della precedente su ogni immagine, e una pre-etichetta su un'immagine su cui la nuova esecuzione si addestra viene rimossa.

Per riaddestrare senza fare clic, aggiungi un blocco auto_retrain. Questo frammento estende il blocco model_training precedente e avvia un'esecuzione dopo ogni 25 nuove annotazioni, al massimo una volta ogni 10 minuti:

model_training:
  enabled: true
  auto_retrain:
    enabled: true
    trainer: torchvision-detect
    schemas: [objects]
    update_frequency: 25
    min_interval_s: 600
  writeback:
    schemas: [objects]
    include_unlabeled: true
    min_confidence: 0.5

Le pre-etichette ancorano gli annotatori ai box del modello. Attiva il write-back per gli annotatori solo quando il punteggio held-out giustifica le pre-etichette, e vedi Individuare le pre-etichette accettate senza controllo per un modo di verificare se gli annotatori accettano i box senza guardarli.

Detection più veloce con Ultralytics YOLO

ultralytics-detect addestra un detector Ultralytics YOLO a partire da un checkpoint preaddestrato su COCO (yolo11n.pt per impostazione predefinita) sugli stessi box. YOLO si addestra e predice più in fretta di torchvision-detect, e le pre-etichette sono gli stessi box modificabili. Ultralytics è distribuito con licenza AGPL-3.0, e un modello addestrato e distribuito con Ultralytics porta con sé i termini dell'AGPL. Ultralytics vende una licenza enterprise separata per l'uso chiuso. Gli extra di Potato escludono Ultralytics, quindi installa il pacchetto da solo:

pip install ultralytics

Potato chiede di confermare la licenza prima di ogni esecuzione. La pagina Training mostra una conferma, un'esecuzione via API richiede "accept_licence": true nel corpo della richiesta e un riaddestramento automatico richiede auto_retrain.accept_licence: true. Senza la conferma, l'API rifiuta l'esecuzione con HTTP 400, needs_licence_ack: true e il messaggio "ultralytics-detect is licensed AGPL-3.0". La richiesta seguente conferma la licenza e avvia l'esecuzione:

curl -X POST -H "X-API-Key: demo-admin-key" -H "Content-Type: application/json" \
  http://localhost:8000/admin/training/api/runs \
  -d '{"trainer": "ultralytics-detect", "schemas": ["objects"], "accept_licence": true}'

Durante un'esecuzione, il trainer disattiva le analisi d'uso di Ultralytics, Ultralytics HUB, le integrazioni con i tracker di esperimenti e le installazioni automatiche di pacchetti. Le modifiche valgono in memoria per il processo dell'esecuzione, e il file delle impostazioni di Ultralytics resta invariato. I checkpoint si scaricano in ~/.cache/potato/ultralytics. I valori predefiniti sono 50 epoche a 640 pixel con arresto anticipato dopo 10 epoche.

Contorni al posto dei box

torchvision-segment addestra un Mask R-CNN di torchvision su contorni a poligono, ellisse, mano libera e maschera a pennello. I box sono esclusi dall'addestramento per la segmentazione, perché un box non dice quali pixel appartengono all'oggetto. Dai agli annotatori uno strumento di contorno come polygon o brush. Come annotare le maschere di segmentazione delle immagini spiega quando ciascuno strumento è adatto.

Ogni maschera predetta viene tracciata come un poligono con al massimo 64 vertici, quindi l'annotatore corregge la pre-etichetta punto per punto. Quando una maschera risulta in più pezzi, si conserva il pezzo più grande. Il score_threshold predefinito è 0.5 invece del 0.25 del detector. Le seconde ipotesi di Mask R-CNN per uno stesso oggetto ottengono punteggi tra 0.25 e 0.6, e ogni ipotesi sarebbe una forma in più da eliminare per l'annotatore. I punteggi held-out confrontano i poligoni predetti con i contorni annotati. Su un Mac, torchvision-segment si addestra sulla CPU. Con torch 2.8, il gruppo di Potato ha misurato un passo di addestramento su un'immagine di 256 pixel a 57 secondi su Metal e a 2.3 secondi sulla CPU. Per studi reali usa un server GPU. ultralytics-segment è la controparte YOLO (yolo11n-seg.pt), con gli stessi poligoni da 64 vertici e la stessa conferma della licenza AGPL-3.0.

Trasformare i box in contorni con sam-finetune

I box si disegnano in fretta e i contorni lentamente. sam-finetune esegue il fine-tuning del decoder di maschere di Segment Anything (SAM) per trasformare un box nel contorno che i tuoi annotatori disegnerebbero. L'encoder di immagini resta congelato, e l'embedding di ogni immagine si calcola una sola volta, quindi un'epoca costa poco. L'addestramento usa come prompt di ogni contorno annotato il suo bounding box. L'esecuzione sposta e ridimensiona ogni box usato come prompt fino a box_jitter (5% per impostazione predefinita), così il decoder impara da box larghi quanto quelli di un detector.

sam-finetune raffina i box e richiede box da cui partire. La sequenza abituale su uno schema ha due esecuzioni:

1. Esegui torchvision-detect o ultralytics-detect con writeback.include_unlabeled: true, così le immagini non etichettate portano pre-etichette di box.
2. Esegui sam-finetune sullo stesso schema. Ogni pre-etichetta di box diventa una pre-etichetta di poligono, e i poligoni sostituiscono i box.

Lo schema richiede contorni da cui SAM impari, quindi dai agli annotatori uno strumento di contorno accanto a bbox. Sulle immagini escluse dall'addestramento i prompt sono i box degli annotatori stessi, quindi val_mask_iou riporta l'IoU medio del contorno quando il box è giusto. Queste predizioni sugli item esclusi dall'addestramento vengono valutate ma mai archiviate né pubblicate, perché sono fatte a partire dalla risposta di un altro annotatore. Il rapporto di write-back conta queste predizioni in n_skipped_heldout_only. Il checkpoint predefinito è facebook/sam-vit-base (Apache-2.0). Il decoder addestrato serve solo le pre-etichette. Il click-to-segment dello strumento per immagini esegue nel browser pesi ONNX distinti, e un'esecuzione di sam-finetune non sostituisce quei pesi.

Classificare immagini intere

Per una domanda sull'intera immagine, ad esempio uno schema radio che chiede quale animale mostra una foto, usa un classificatore e non un detector. hf-image-classification esegue il fine-tuning di qualsiasi modello che AutoModelForImageClassification di Hugging Face carica, come ViT, DeiT, BEiT, ConvNeXt, Swin o DINOv2. Il modello predefinito è google/vit-base-patch16-224-in21k. Il trainer capovolge a caso le immagini di addestramento per impostazione predefinita. Imposta flip su false in Parameters quando un capovolgimento cambia l'etichetta, come con il testo nell'immagine o con sinistra e destra. lora: true addestra un adattatore LoRA e la testa di classificazione invece di tutti i pesi.

Uno schema a scelta conta come corpus di immagini quando almeno l'80% dei suoi item etichettati porta un percorso di immagine che termina in .jpg, .jpeg, .png, .bmp, .webp, .tif, .tiff o .gif. Su un corpus di questo tipo, sklearn-text senza un vectorizer indicato addestra un classificatore lineare sugli embedding di immagini CLIP. La baseline CLIP non richiede GPU, solo pip install "potato-annotation[embeddings]" pillow.

Percorsi delle immagini e immagini remote

I trainer per immagini leggono il campo indicato da source_field dello schema. Senza source_field, un trainer prende il primo campo non vuoto dell'item tra image_url, image, image_path, file_name, url, path e gli equivalenti per audio e video. Le immagini devono essere file locali dentro il progetto:

• Un percorso relativo si risolve rispetto a task_dir, o rispetto a media_directory quando il file non si trova sotto task_dir.
• Un percorso URL come /media/img_001.jpg si risolve rispetto a media_directory. La pagina di annotazione carica l'immagine dallo stesso posto.
• Un file che un percorso assoluto, ../ o un collegamento simbolico colloca fuori dalla directory del compito e da media_directory viene escluso con un avviso.
• Le immagini http(s) remote non vengono mai scaricate. Un'esecuzione esclude ogni item la cui immagine è remota o mancante, il log dell'esecuzione dice quanti sono, e quegli item non ricevono predizione.

Scarica le immagini remote in media_directory per addestrarti su di esse. La pagina sui formati per la visione e potato import spiegano come portare in un progetto dataset di immagini esistenti.

Vetrini interi e altre immagini grandi

I trainer per detection e segmentazione ridimensionano ogni immagine a qualche centinaio di pixel, e gli oggetti di un vetrino di patologia di 100.000 pixel o di una scena satellitare scompaiono a quella dimensione. Per uno schema image_annotation, microscopy o geo_annotation, Potato taglia quindi le immagini grandi in tile quando si costruiscono i dati di addestramento dell'esecuzione. La suddivisione in tile è automatica per i formati di vetrino (.svs, .ndpi, .mrxs, .scn e altri) e per le immagini il cui lato più lungo è di almeno 4.096 pixel. I vetrini richiedono openslide:

pip install "potato-annotation[wsi]"

L'addestramento usa i tile che contengono un oggetto annotato più un campione di tile vuoti, e ogni oggetto viene ritagliato al proprio tile. La predizione copre ogni tile sul tessuto, fino a max_predict_tiles per immagine. La partizione di ogni immagine è decisa prima che l'immagine venga tagliata, quindi i tile di uno stesso vetrino non finiscono mai in due partizioni. Le predizioni dei tile vengono riunite sull'immagine intera, e un oggetto trovato da due tile sovrapposti viene conservato una sola volta. Le pre-etichette usano le coordinate dell'immagine intera, le stesse che archivia il visualizzatore deep-zoom. I punteggi held-out sono calcolati su immagini intere. Un backend remoto scarica i tile e non il vetrino.

Le impostazioni si trovano sotto model_training.tiling. Questo frammento addestra un vetrino a 40x a 20x su tile da 1.024 pixel:

model_training:
  enabled: true
  tiling:
    tile_size: 1024
    overlap: 128
    downsample: 2

Tieni overlap almeno grande quanto gli oggetti, perché un oggetto più grande viene trovato a pezzi, uno per tile. Per un vetrino che registra la propria risoluzione, mpp imposta i micron per pixel di tile e ha la precedenza su downsample. Due impostazioni richiedono attenzione su alcuni vetrini. I tile vuoti di addestramento presuppongono che ogni oggetto di un'immagine annotata sia stato disegnato, quindi imposta background: 0 quando gli annotatori hanno disegnato solo alcune regioni di un vetrino. Il tessuto viene rilevato con la soglia di Otsu sulla miniatura del vetrino, quindi un vetrino senza vetro scoperto perde la sua metà più chiara, e tissue_threshold: 0 predice su ogni tile. La tabella tiling elenca ogni chiave e il valore predefinito.

Microscopia e mappe

Le ROI di uno schema microscopy addestrano torchvision-detect, ultralytics-detect, torchvision-segment, ultralytics-segment e cellpose. Ogni z-slice e ogni istante con ROI viene reso con i canali e il contrasto predefiniti dello schema e diventa un'immagine di addestramento separata. Il renderer è il compositore che usa il visualizzatore. Un'immagine su cui non è ancora stato disegnato nulla viene predetta allo z-slice centrale e al primo istante, dove si apre il visualizzatore. Le predizioni tornano come ROI di microscopia con z e t di ciascuna ROI. Le classificazioni di cellule si riferiscono a un'immagine di etichette e non a una forma, e i trainer saltano le classificazioni di cellule.

Le feature di uno schema geo_annotation addestrano gli stessi trainer di detection e segmentazione sulla mappa di base raster dell'item. Un GeoTIFF viene posizionato dalla trasformazione e dal codice EPSG presenti nei tag del file stesso e riproiettato con pyproj quando è proiettato. Un'immagine semplice con un'estensione viene posizionata in longitudine e latitudine. Poligoni, rettangoli, linee e punti diventano forme sul raster, con i buchi dei poligoni riempiti. Le predizioni tornano come feature GeoJSON in EPSG:4326 con source: model. La mappa offre le feature come suggerimenti, e i suggerimenti contano come risposta solo quando l'annotatore ne modifica o ne accetta uno. Una mappa la cui mappa di base è un tile server o un contorno GeoJSON non ha un raster su cui addestrarsi, e l'esecuzione esclude quegli item con un avviso.

Cellule con cellpose

cellpose esegue il fine-tuning di Cellpose su contorni di cellule o nuclei in uno schema image_annotation o microscopy. Installa Cellpose 3 o 4 separatamente:

pip install cellpose

Il modello di base predefinito è cyto3. Con Cellpose 3 funzionano anche nuclei e cyto2, e con Cellpose 4 cpsam. Imposta diameter al diametro tipico della cellula in pixel quando la stima di Cellpose è sbagliata. Cellpose segmenta senza classi, quindi ogni cellula predetta riceve il parametro label, oppure l'etichetta più comune dello schema quando label non è impostato. Addestra un modello per etichetta quando le classi hanno aspetto diverso. Ogni maschera predetta torna come poligono con la probabilità media della cellula come confidenza della pre-etichetta. cellpose richiede solo 5 immagini annotate nella partizione train, contro le 20 dei detector. Il codice di Cellpose è BSD-3-Clause, e i pesi provengono dagli autori di Cellpose secondo i termini degli autori.

Spettrogrammi

I box di uno schema spectrogram_annotation addestrano torchvision-detect e ultralytics-detect su ogni registrazione resa come immagine di spettrogramma. Il tutorial sui modelli per l'audio tratta la detection su spettrogrammi dall'inizio alla fine, con le impostazioni di rendering e i formati di registrazione che i trainer leggono.

Layout dei documenti con layoutlmv3

layoutlmv3 esegue il fine-tuning di LayoutLMv3 per trovare le regioni che gli annotatori disegnano sulle immagini di pagina a partire dalle parole della pagina e dalle loro posizioni. Una regione è qualsiasi blocco etichettato, ad esempio un titolo, una tabella o un totale. Potato non esegue alcun OCR, quindi ogni item porta le parole della pagina con box in pixel dell'immagine di pagina o da 0 a 1:

{"id": "page_001", "image": "pages/page_001.png",
 "words": [{"text": "INVOICE", "bbox": [40, 52, 180, 82]},
           {"text": "Total", "bbox": [300, 700, 380, 730]}]}

Un'importazione PAGE XML in modalità regions riempie words dagli elementi Word del file. Le parole dal livello di testo di un PDF o da un altro strumento OCR funzionano allo stesso modo. Ogni parola è etichettata dalla regione in cui cade il suo centro, le parole predette vengono riunite in regioni e ogni regione diventa una pre-etichetta di box attorno alle parole della regione. I punteggi held-out sono la mAP dei box. Un box predetto termina alle parole della regione, quindi regioni disegnate molto più grandi delle parole ottengono un punteggio più basso di quello che i box meritano.

I pesi di LayoutLMv3 sono distribuiti con licenza CC BY-NC-SA 4.0 e non sono per uso commerciale. Come per i trainer YOLO, la pagina Training chiede conferma prima di un'esecuzione, un'esecuzione via API richiede accept_licence: true e un riaddestramento automatico richiede auto_retrain.accept_licence: true.

Modelli visione-linguaggio con vlm-sft

vlm-sft esegue il fine-tuning di un modello visione-linguaggio sulle risposte degli annotatori sulle immagini, con un adattatore LoRA per impostazione predefinita e Qwen/Qwen2.5-VL-3B-Instruct come modello predefinito. Il trainer impara da quattro schemi:

Le coordinate sono su una griglia da 0 a 1.000 dell'immagine, quindi qualsiasi checkpoint può imparare il formato dagli esempi. Un'esecuzione su testo pubblica la risposta generata come pre-etichetta di testo. Un'esecuzione di grounding pubblica una regione o un'assenza per ogni espressione, e Grounding con VLM tratta lo schema grounding_eval. Un'esecuzione su traiettorie GUI suggerisce un verdetto per ogni passo in base a dove il modello cliccherebbe, e Valutare gli agent che usano il computer tratta le tracce GUI. Un'esecuzione sulle didascalie è valutata con F1 sui token e BLEU-4 ma non viene mai pubblicata, perché le regioni con didascalia sono una risposta dell'annotatore.

I checkpoint reali richiedono una GPU. Il gruppo di Potato ha addestrato due epoche di Qwen/Qwen3-VL-2B-Instruct con LoRA su 26 immagini in 46 secondi sulla GPU Metal di un Mac. {"lora": {"quantize": "4bit"}} in Parameters addestra un adattatore QLoRA sopra pesi di base a 4 bit. Controlla la licenza del modello che scegli. Qwen2.5-VL-3B porta la licenza di ricerca Qwen, mentre il modello da 7B è Apache-2.0. Il tutorial sul fine-tuning di LLM tratta LoRA, QLoRA e la pubblicazione di un modello su Hugging Face Hub.

Ulteriori letture

• Panoramica sull'addestramento di modelli, per il ciclo e la pagina Training
• Trainer, per ogni trainer raggruppato per compito
• Configurazione, per ogni chiave, i punteggi held-out, il write-back e le route
• Etichettatura con il modello nel ciclo, per revisione, acquisizione e riaddestramento automatico
• Addestramento remoto, per server GPU via ssh, SLURM e l'agent che esegue il polling
• Annotazione di immagini, per gli strumenti e le opzioni dello schema
• Model zoo e licenze, per i modelli di visione che girano nel browser e sul server
• Riferimento upstream per gli item immagine, i vetrini interi, torchvision-detect, sam-finetune e vlm-sft, con ogni tabella dei parametri

Riferimenti

• Ren, S., He, K., Girshick, R., and Sun, J. (2017). Faster R-CNN: Towards Real-Time Object Detection with Region Proposal Networks. IEEE Transactions on Pattern Analysis and Machine Intelligence, 39, 1137–1149. doi:10.1109/TPAMI.2016.2577031
• He, K., Gkioxari, G., Dollár, P., and Girshick, R. (2017). Mask R-CNN. 2017 IEEE International Conference on Computer Vision (ICCV), 2980–2988. doi:10.1109/ICCV.2017.322
• Kirillov, A., Mintun, E., Ravi, N., Mao, H., Rolland, C., Gustafson, L., Xiao, T., Whitehead, S., Berg, A. C., Lo, W.-Y., Dollár, P., and Girshick, R. (2023). Segment Anything. 2023 IEEE/CVF International Conference on Computer Vision (ICCV), 3992–4003. doi:10.1109/ICCV51070.2023.00371
• Stringer, C., Wang, T., Michaelos, M., and Pachitariu, M. (2021). Cellpose: a generalist algorithm for cellular segmentation. Nature Methods, 18, 100–106. doi:10.1038/s41592-020-01018-x
• Huang, Y., Lv, T., Cui, L., Lu, Y., and Wei, F. (2022). LayoutLMv3: Pre-training for Document AI with Unified Text and Image Masking. Proceedings of the 30th ACM International Conference on Multimedia, 4083–4091. doi:10.1145/3503161.3548112