LibreVLM

LibreVLM ist über das optionale Extra vlm verfügbar. Es installiert eine aktuelle Version von transformers und die Hilfsbibliotheken, die einige Prozessoren benötigen. Ohne das Extra löst der Import einer VLM-Familie einen ImportError aus, der auf diese Stelle verweist.

1
pip install 'libreyolo[vlm]'

Die Gewichte werden bei der ersten Verwendung vom Hugging Face Hub in einen lokalen Ordner weights/ heruntergeladen. Einige Familien werden unter Nicht-OSI-Lizenzen ausgeliefert und protokollieren vor dem Download einmalig einen Hinweis. Für die größeren Backends wird eine GPU empfohlen, aber mit device="cpu" läuft jedes Modell auch auf der CPU.

Erstelle ein Modell, gib die relevanten Wörter an und führe die Vorhersage aus. Das Standard-Backend ist Qwen3-VL-4B, der stärkste Detektor dieser Stufe unter Apache-2.0-Lizenz.

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")

Das ist der gesamte Ablauf. Alles nach predict() verhält sich wie bei einem normalen Detektor, deshalb funktionieren vorhandener Visualisierungs-, Zuschneide- und Tracking-Code weiterhin.

Wähle ein Backend über den Alias, den du an LibreVLM(...) übergibst. Ein allein stehender Familienname wird auf seine Standardgröße aufgelöst. Das allgemeine Standard-Backend ist qwen3-vl-4b. In der Praxis sind Qwen3-VL, LFM2-VL und Florence-2 die stärksten Detektoren.

Auswahl eines Backends

• Beste Qualität: qwen3-vl-8b oder qwen3-vl-4b (Standard).
• Enge Boxen, kleiner Ressourcenbedarf: florence-2-large.
• Edge / CPU: lfm2-vl-450m oder smolvlm2-500m.
• Vollständig permissive Lizenz: jede Größe von Qwen3-VL, SmolVLM2, Florence-2 oder Kosmos-2.

Das Vokabular ist das Herzstück der Open-Vocabulary-Erkennung. Rufe set_classes() mit einer Liste von Label-Strings auf. Die Einstellung bleibt bestehen: Sie gilt für jeden späteren Aufruf von predict() und track(), bis du sie erneut setzt. Die Methode gibt self zurück und lässt sich daher verketten.

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"])

Labels können beliebige Wortgruppen sein. Sie müssen unabhängig von Groß- und Kleinschreibung eindeutig sein, und du musst eine Liste statt eines einzelnen Strings übergeben. Wenn du set_classes() nie aufrufst, greift das Modell auf das COCO-80-Vokabular zurück. So liefert auch ein allein stehendes predict() ein sinnvolles Ergebnis.

predict() und der gleichwertige Aufruf model(...) akzeptieren dieselben Quelltypen wie jeder LibreYOLO-Detektor: einen Pfad, ein PIL-Bild, ein NumPy-Array, eine URL, einen Ordner oder ein Video. stream=True und track() funktionieren ebenfalls.

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
)

Rückgabeform

Du erhältst das standardmäßige Results-Objekt zurück, genau wie bei einem Closed-Vocabulary-Detektor:

Intern parst LibreVLM die Modellausgabe tolerant, einschließlich Markdown-Blöcken, verstreuter Prosa, doppelter Boxen und abgeschnittener Arrays. Es ordnet Freitext-Labels wieder deinen Klassen-IDs zu und verwirft jedes Label, das nicht in deinem Vokabular enthalten ist. Dieser letzte Schritt lässt einen freien Generator wie einen Closed-Set-Detektor arbeiten.

Ein Objekt mit einer bestimmten Farbe erkennen

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")

Enge Boxen mit 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()

Dynamisch nach einer einzelnen Klasse filtern

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])

Mit einem integrierten Beispielbild auf der CPU ausführen

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"

Batches, Ordner und Videos

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)

Manchmal brauchst du das Modell statt des Detektors. Die Chat-Template-Familien stellen chat() bereit. Die Methode nimmt ein Bild und einen freien Prompt entgegen und gibt den dekodierten Text unverändert zurück. Nutze sie zum Zählen, für Bildbeschreibungen oder für schnelle visuelle Fragen.

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)

Jede Familie gibt dieselben Results zurück, erreicht sie aber auf einem anderen Weg. Das ist selten wichtig, erklärt jedoch das Verhalten einiger Backends. Die Chat-Familien werden zur Ausgabe eines JSON-Arrays von Boxen aufgefordert, während die Grounder spezielle Task-Tokens verwenden.

Bei den Chat-Familien kannst du den Erkennungs-Prompt mit dem Konstruktorargument prompt= überschreiben und die Generierungslänge mit max_new_tokens= begrenzen. Gerät und Datentyp werden automatisch bestimmt: bf16 oder fp16 unter CUDA, fp32 auf der CPU.

LibreVLM ist leistungsfähig, aber noch jung. Wenn du die Grenzen vorab kennst, vermeidest du spätere Überraschungen.

• Synthetische Confidence. Jede Box erhält den Wert 1.0. Der Filter conf= verhält sich daher nach dem Alles-oder-nichts-Prinzip statt wie ein echter Schwellenwert.
• Keine mAP / Validierung. val() löst einen Fehler aus, weil synthetische Werte die COCO-mAP irreführend machen würden.
• Kein Training oder Export. train() und export() lösen Fehler aus. Führe stattdessen Upstream ein Fine-Tuning des VLM durch und lade die daraus entstandenen Gewichte.
• Eingeschränktes Tracking. track() läuft, aber einheitliche Werte setzen die Wiederherstellungsstufe des Trackers für niedrige Confidence außer Kraft.
• Jeweils ein Bild. In v1 läuft die Generierung sequenziell, deshalb bringen größere Werte für batch= keinen Geschwindigkeitsvorteil.
• Nur Python-API. Die CLI libreyolo löst VLM-Aliasse noch nicht auf.