LibreVLM

LibreVLM jest dostępny przez opcjonalny dodatek vlm. Instaluje on aktualną wersję transformers oraz narzędzia pomocnicze wymagane przez niektóre procesory. Bez tego dodatku importowanie rodziny VLM zgłasza ImportError ze wskazaniem tej strony.

1
pip install 'libreyolo[vlm]'

Przy pierwszym użyciu wagi są pobierane z Hugging Face Hub do lokalnego folderu weights/. Niektóre rodziny są objęte licencjami spoza OSI i przed pobraniem jednorazowo wyświetlają powiadomienie. W przypadku większych backendów zalecane jest GPU, ale każdy model działa także na CPU z ustawieniem device="cpu".

Utwórz model, podaj interesujące słowa i uruchom predykcję. Domyślnym backendem jest Qwen3-VL-4B, najsilniejszy detektor na tym poziomie, objęty licencją 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")

To cały przebieg. Wszystko za predict() zachowuje się jak zwykły detektor, więc istniejący kod wizualizacji, wycinania i śledzenia nadal działa.

Wybierz backend za pomocą aliasu przekazywanego do LibreVLM(...). Sama nazwa rodziny wskazuje jej domyślny rozmiar. Ogólnym domyślnym backendem jest qwen3-vl-4b. W praktyce najsilniejszymi detektorami są Qwen3-VL, LFM2-VL i Florence-2.

Wybór backendu

• Najlepsza jakość: qwen3-vl-8b lub qwen3-vl-4b (domyślny).
• Precyzyjne ramki, mały rozmiar: florence-2-large.
• Urządzenia brzegowe / CPU: lfm2-vl-450m lub smolvlm2-500m.
• W pełni permisywna licencja: dowolny rozmiar Qwen3-VL, SmolVLM2, Florence-2 lub Kosmos-2.

Słownik stanowi podstawę detekcji z otwartym słownikiem. Wywołaj set_classes() z listą ciągów etykiet. Ustawienie jest trwałe: obowiązuje przy każdym późniejszym wywołaniu predict() i track(), dopóki nie zostanie zmienione. Metoda zwraca self, więc można łączyć wywołania.

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

Etykietą może być dowolna fraza. Etykiety muszą być unikatowe bez względu na wielkość liter i należy przekazać listę, a nie pojedynczy ciąg. Jeśli set_classes() nie zostanie wywołane, model użyje słownika COCO-80, dzięki czemu samo predict() nadal zwróci sensowny wynik.

predict() (or równoważne wywołanie model(...)) przyjmuje te same typy źródeł co każdy detektor LibreYOLO: ścieżkę, obraz PIL, tablicę numpy, adres URL, folder lub wideo. Działają także stream=True i 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
)

Struktura wyniku

Zwracany jest standardowy obiekt Results, identyczny jak w detektorze z zamkniętym słownikiem:

Wewnętrznie LibreVLM elastycznie analizuje wynik modelu (obsługuje bloki Markdown, zbędną prozę, zduplikowane ramki i ucięte tablice), mapuje etykiety w swobodnym tekście z powrotem na identyfikatory klas i odrzuca każdą etykietę spoza słownika. Ten ostatni krok sprawia, że generator swobodnego tekstu zachowuje się jak detektor z zamkniętym zbiorem klas.

Detekcja obiektu o określonym kolorze

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

Precyzyjne ramki z 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()

Filtrowanie do jednej klasy w locie

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

Uruchamianie na CPU z wbudowanym obrazem przykładowym

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"

Batche, foldery i wideo

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)

Czasami potrzebny jest model, a nie detektor. Rodziny korzystające z szablonu czatu udostępniają chat(), które przyjmuje obraz i swobodny prompt, a następnie zwraca zdekodowany tekst bez zmian. Można użyć tej metody do liczenia, tworzenia podpisów lub zadawania szybkich pytań wizualnych.

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)

Każda rodzina zwraca ten sam obiekt Results, ale dochodzi do niego w inny sposób. Rzadko ma to znaczenie, jednak warto wiedzieć, dlaczego niektóre backendy zachowują się w określony sposób. Rodziny czatowe otrzymują prompt z żądaniem tablicy ramek JSON, a modele ugruntowujące używają dedykowanych tokenów zadań.

W rodzinach czatowych można zastąpić prompt detekcji argumentem konstruktora prompt= i ograniczyć długość generowania za pomocą max_new_tokens=. Urządzenie i dtype są dobierane automatycznie: bf16 lub fp16 na CUDA, fp32 na CPU.

LibreVLM ma duże możliwości, ale jest młodym projektem. Znajomość ograniczeń od początku pozwala uniknąć późniejszych niespodzianek.

• Syntetyczny wskaźnik pewności. Każda ramka otrzymuje wynik 1.0. Filtr conf= działa więc na zasadzie wszystko albo nic, a nie jak rzeczywisty próg.
• Brak mAP i walidacji. val() zgłasza wyjątek, ponieważ syntetyczne wyniki sprawiłyby, że mAP na COCO byłoby mylące.
• Brak trenowania i eksportu. train() i export() zgłaszają wyjątek. Zamiast tego dostrój VLM w projekcie źródłowym i wczytaj uzyskane wagi.
• Ograniczone śledzenie. track() działa, ale jednakowe wyniki powodują, że etap odzyskiwania detekcji o niskiej pewności w trackerze jest nieaktywny.
• Jeden obraz naraz. W wersji v1 generowanie jest sekwencyjne, więc większe wartości batch= nie przyspieszają działania.
• Tylko API Pythona. CLI libreyolo nie rozpoznaje jeszcze aliasów VLM.