LibreVLM

LibreVLM è disponibile tramite il pacchetto extra opzionale vlm. Installa una versione recente di transformers e gli strumenti ausiliari richiesti da alcuni processori. Senza il pacchetto extra, l'importazione di una famiglia VLM genera un ImportError che rimanda a questa pagina.

1
pip install 'libreyolo[vlm]'

I pesi vengono scaricati da Hugging Face Hub al primo utilizzo in una cartella locale weights/. Alcune famiglie vengono distribuite con licenze non OSI e mostrano un avviso una sola volta prima del download. Per i backend più grandi è consigliata una GPU, ma ogni modello funziona anche su CPU con device="cpu".

Crea un modello, dichiara le parole che ti interessano ed esegui la predizione. Il backend predefinito è Qwen3-VL-4B, il rilevatore più potente del livello, con licenza Apache-2.0.

1
from libreyolo import LibreVLM
2
3
# Qwen3-VL-4B by default; weights autodownload on first use
4
model = LibreVLM()
5
6
# The vocabulary is just words. Any words.
7
model.set_classes(["pink car", "wheel"])
8
9
result = model.predict("street.jpg")
10
11
print(result.boxes.xyxy)   # pixel [x1, y1, x2, y2]
12
print(result.boxes.cls)    # ids into ["pink car", "wheel"]
13
result.plot()              # same drawing helpers as any LibreYOLO model
14
result.save("out.jpg")

Questo è l'intero ciclo. Tutto ciò che segue predict() si comporta come un normale rilevatore, quindi il codice esistente per visualizzazione, ritaglio e tracking continua a funzionare.

Scegli un backend tramite l'alias che passi a LibreVLM(...). Il solo nome della famiglia seleziona la dimensione predefinita. Il backend predefinito complessivo è qwen3-vl-4b. In pratica, i rilevatori più potenti sono Qwen3-VL, LFM2-VL e Florence-2.

Scegliere un backend

• Qualità migliore: qwen3-vl-8b o qwen3-vl-4b (il predefinito).
• Box precisi e ingombro ridotto: florence-2-large.
• Edge / CPU: lfm2-vl-450m o smolvlm2-500m.
• Licenza completamente permissiva: qualsiasi dimensione di Qwen3-VL, SmolVLM2, Florence-2 o Kosmos-2.

Il vocabolario è il cuore del rilevamento a vocabolario aperto. Chiama set_classes() con un elenco di stringhe di etichette. L'impostazione è persistente: rimane valida per ogni successiva chiamata a predict() e track() finché non la modifichi. Il metodo restituisce self, quindi può essere concatenato.

1
# Sticky and chainable
2
model = LibreVLM("qwen3-vl-2b").set_classes(["person", "dog", "cat"])
3
4
# Set it once at construction instead
5
model = LibreVLM("lfm2-vl-450m", names=["boat"], device="cpu")
6
7
# Re-set any time to change what you are looking for
8
model.set_classes(["a red car", "a blue truck"])

Le etichette possono essere qualsiasi frase. Devono essere univoche senza distinzione tra maiuscole e minuscole e devi passare un elenco, non una singola stringa. Se non chiami mai set_classes(), il modello usa come fallback il vocabolario COCO-80, così anche un semplice predict() produce un risultato sensato.

predict() e la chiamata equivalente model(...) accettano gli stessi tipi di sorgente di qualsiasi rilevatore LibreYOLO: un percorso, un'immagine PIL, un array numpy, un URL, una cartella o un video. Funzionano anche stream=True e track().

1
result = model.predict(
2
    source="image.jpg",  # path | PIL | ndarray | URL | folder | video
3
    conf=0.25,           # see note below: scoring is synthetic
4
    classes=[0],         # optional: keep only these vocabulary ids
5
    max_det=300,
6
)

Struttura restituita

Ottieni l'oggetto Results standard, identico a quello di un rilevatore a vocabolario chiuso:

Dietro le quinte, LibreVLM analizza in modo tollerante l'output del modello, gestendo delimitatori markdown, testo estraneo, box duplicati e array troncati; associa le etichette in testo libero agli ID delle classi e scarta ogni etichetta che non appartiene al vocabolario. Quest'ultimo passaggio fa sì che un generatore a forma libera si comporti come un rilevatore a insieme chiuso.

Rileva un oggetto di un colore specifico

1
from libreyolo import LibreVLM
2
3
model = LibreVLM("qwen3-vl-4b")
4
model.set_classes(["red car"])
5
6
result = model.predict("parking_lot.jpg")
7
print(f"Found {len(result.boxes.cls)} red car(s)")
8
result.save("red_cars.jpg")

Box precisi con Florence-2

1
# Florence-2 is a purpose-built grounder: very tight pixel boxes.
2
model = LibreVLM("florence-2-large")
3
model.set_classes(["a red car", "license plate"])
4
5
result = model.predict("car.jpg")
6
result.plot()

Filtra al volo una singola classe

1
model = LibreVLM("qwen3-vl-2b").set_classes(["person", "dog", "cat"])
2
3
# classes= filters the configured vocabulary by id
4
people_only = model.predict("street.jpg", classes=[0])

Esegui su CPU con un'immagine di esempio integrata

1
from libreyolo import LibreVLM, SAMPLE_IMAGE
2
3
model = LibreVLM("lfm2-vl-450m", device="cpu")
4
# No set_classes() -> falls back to the COCO-80 vocabulary
5
result = model.predict(SAMPLE_IMAGE)
6
print(model.names[result.boxes.cls[0]])  # e.g. "person"

Batch, cartelle e video

1
model = LibreVLM().set_classes(["forklift", "pallet"])
2
3
# A whole folder
4
for result in model.predict("warehouse_frames/", stream=True):
5
    result.save()
6
7
# A video file (frames are processed one at a time)
8
model.predict("warehouse.mp4", save=True)

A volte ti serve il modello, non il rilevatore. Le famiglie con template di chat espongono chat(), che riceve un'immagine e un prompt a forma libera e restituisce il testo decodificato senza modifiche. Usalo per il conteggio, la generazione di didascalie o domande visive rapide.

1
model = LibreVLM("qwen3-vl-4b")
2
3
answer = model.chat("harbor.jpg", "How many boats are docked? Answer with a number.")
4
print(answer)

Ogni famiglia restituisce lo stesso oggetto Results, ma lo ottiene in modo diverso. Raramente è necessario occuparsene, ma aiuta a capire perché alcuni backend si comportano in un determinato modo. Alle famiglie di chat viene richiesto un array JSON di box; i modelli di grounding usano token di task dedicati.

Per le famiglie di chat puoi sostituire il prompt di rilevamento con l'argomento prompt= del costruttore e limitare la lunghezza della generazione con max_new_tokens=. Il dispositivo e il dtype vengono determinati automaticamente: bf16 o fp16 su CUDA, fp32 su CPU.

LibreVLM è potente ma ancora giovane. Conoscerne subito i limiti evita sorprese in seguito.

• Confidenza sintetica. Ogni box riceve un punteggio di 1.0. Il filtro conf= si comporta quindi in modo tutto o niente, anziché come una vera soglia.
• Niente mAP o validazione. val() genera un errore perché i punteggi sintetici renderebbero fuorviante la mAP COCO.
• Niente addestramento o esportazione. train() ed export() generano un errore. Esegui invece il fine-tuning del VLM upstream e carica i pesi risultanti.
• Tracking limitato. track() funziona, ma i punteggi uniformi rendono inattiva la fase di recupero a bassa confidenza del tracker.
• Un'immagine alla volta. Nella v1 la generazione è sequenziale, quindi valori maggiori di batch= non aumentano la velocità.
• Solo API Python. La CLI libreyolo non riconosce ancora gli alias VLM.