API di visione e linguaggio

Installazione

Il tier richiede l'extra vlm.

pip install 'libreyolo[vlm]'

La factory

LibreVLM(model: str = "qwen3-vl-4b", **kwargs) -> LibreVLMModel

model è un alias, non un percorso. **kwargs arriva al costruttore della famiglia, che accetta device, names (il vocabolario iniziale, equivalente a chiamare set_classes dopo il caricamento), prompt (per sovrascrivere il prompt di rilevamento) e max_new_tokens. Un alias sconosciuto solleva ValueError elencando tutti gli alias.

from libreyolo import LibreVLM, SAMPLE_IMAGE model = LibreVLM("lfm2-vl-450m")model.set_classes(["person", "skateboard"]) result = model.predict(SAMPLE_IMAGE)for box, cls in zip(result.boxes.xyxy, result.boxes.cls):    print(result.names[int(cls)], box.tolist())

from libreyolo import LibreVLM, SAMPLE_IMAGE model = LibreVLM("lfm2-vl-450m")print(model.chat(SAMPLE_IMAGE, "How many people are in this image?"))

Alias

L'alias predefinito è qwen3-vl-4b. Le dimensioni per l'alias predefinito di ogni famiglia sono quelle elencate per prime: qwen3-vl risolve a 4b, lfm2-vl a 450m, internvl3 a 2b, smolvlm2 a 2.2b, florence-2 a base, wevisone-vl a 2b.

LibreVLM, LibreLFM2VL, LibreQwen3VL, LibreSmolVLM2, LibreInternVL3, LibreFlorence2, LibreKosmos2, LibreLocateAnything, LibreWeVisOneVL e LibreMODUS (scritto anche LibreModus) sono esportati a livello di pacchetto.

Il rilevamento include anche north-micro-vision, gemma-4-e2b, gemma-4-e4b, moondream-2, moondream-3 e lfm2-vl-3b. L'alias semplice gemma-4 seleziona E4B. Gli alias Molmo2 sono molmo2-4b, molmo2-8b e molmo2-o-7b; il default è 4B. Gli alias definiscono l'instradamento, ma non attestano che ogni snapshot remoto sia stato scaricato e testato. moondream-3 non si carica in 1.6.0: al suo mirror mancano alcuni shard dei pesi.

Task

Il supporto dei task è specifico per famiglia. Questi adattatori supportano più task:

Poiché il task è guidato dal prompt invece di essere incorporato in un checkpoint, si può cambiare su un modello già caricato:

model.set_task(task: str) -> LibreVLMModel

Il task viene validato rispetto all'elenco supportato dalla famiglia, resta valido nelle chiamate successive a predict() e track(), e il modello viene restituito così che le chiamate si possano concatenare.

Molmo2 restituisce punti e richiede {label} nei template di puntamento personalizzati. Con referring=True di WeVisOne-VL, detect invia una generazione per ogni frase, e i suoi segment, matte e il rilevamento referenziale sollevano ValueError senza un vocabolario. Moondream supporta rilevamento, punti e chat nativa. Usa LibreGround per query che trasformano istruzioni in clic.

set_classes

model.set_classes(classes: list[str]) -> LibreVLMModel

Imposta il vocabolario aperto. Funziona qualsiasi parola, perché il modello la riceve nel prompt invece di essere vincolato a una testa fissa. L'elenco non deve essere vuoto e le sue voci devono essere uniche confrontandole senza distinzione tra maiuscole e minuscole. Passare una semplice stringa solleva TypeError, perché verrebbe enumerata in classi di un carattere. Il vocabolario è persistente: impostalo una volta dopo il caricamento e rimane finché non lo imposti di nuovo.

chat

model.chat(image, prompt, max_new_tokens=None, color_format="auto") -> str

Generazione multimodale grezza: immagine e prompt in ingresso, testo decodificato in uscita, alla lettera. È la via di fuga sotto la comodità del rilevamento, per domande libere, per contare, o per un formato di output che il wrapper di rilevamento non copre. max_new_tokens ricade sul MAX_NEW_TOKENS della famiglia, che è 1024 nella classe base. La decodifica è greedy con una lieve penalità di ripetizione.

Confidenza

L'output generato non ha una confidenza calibrata per box. Questa versione assegna un segnaposto costante perché predict, il disegno e track funzionino, il che rende il filtraggio con conf= e la mAP approssimativi anziché significativi. È anche il motivo per cui val() solleva un'eccezione: la mAP COCO su punteggi segnaposto sarebbe fuorviante.

Predict e track

Vale la superficie standard di predict, e track() funziona, quindi un rilevatore VLM si inserisce nella stessa pipeline di qualsiasi altra famiglia. Due politiche a livello di classe differiscono da un rilevatore convoluzionale: la test-time augmentation è disabilitata, perché l'augmentation multi-scala non ha senso per un generatore a risoluzione fissa, e il predict in batch è disattivato, perché la generazione è autoregressiva e il preprocessing restituisce una codifica di testo e immagine invece di un tensore immagine impilabile.

Non supportato

L'esportazione e la validazione della mAP di rilevamento non sono supportate. Il supporto all'addestramento è limitato al flusso Qwen3-VL descritto sotto.

Codice remoto

Ogni famiglia inclusa viene caricata tramite una classe di modello nativa, quindi LibreYOLO non esegue codice di repository di terze parti per impostazione predefinita. Una famiglia che ne ha davvero bisogno deve fare opt-in esplicito e fissare una revisione snapshot; LocateAnything è quella che lo fa, fissata al commit c32291ca5e996f5a7a485845b4f57a233936bba0.

LibreMODUS è un'eccezione esplicita allo schema dei checkpoint: il suo alias risolve a una directory di file upstream fissati invece che a un .pt di LibreYOLO, e LibreYOLO non gli aggiunge metadati v1.0 né lo ripubblica.

Addestramento

Qwen3-VL supporta LoRA di rilevamento tramite train(data=...) dopo l'installazione di libreyolo[vlm-train]. Congela l'encoder visivo, sceglie i checkpoint migliori in base alla loss di validazione e salva directory di checkpoint. Vedi fine-tuning dei VLM.