LibreVLM

LibreVLM tersedia melalui paket tambahan opsional vlm. Paket ini memasang versi terbaru transformers dan helper yang diperlukan beberapa processor. Tanpa paket tambahan tersebut, mengimpor family VLM memicu ImportError yang mengarahkan ke halaman ini.

1
pip install 'libreyolo[vlm]'

Bobot diunduh dari Hugging Face Hub saat pertama kali digunakan ke folder lokal weights/. Beberapa family menggunakan lisensi non-OSI dan mencatat pemberitahuan satu kali sebelum mengunduh. GPU disarankan untuk backend yang lebih besar, tetapi setiap model juga dapat dijalankan pada CPU dengan device="cpu".

Buat model, tentukan kata yang diperlukan, lalu jalankan prediksi. Backend default adalah Qwen3-VL-4B, detektor terkuat di tier ini yang berlisensi 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")

Itulah seluruh alurnya. Semua yang berjalan setelah predict() berperilaku seperti detektor biasa, sehingga kode visualisasi, pemotongan, dan pelacakan yang sudah ada tetap berfungsi.

Pilih backend melalui alias yang diberikan ke LibreVLM(...). Nama family tanpa ukuran akan menggunakan ukuran default. Backend default secara keseluruhan adalah qwen3-vl-4b. Dalam praktiknya, detektor terkuat adalah Qwen3-VL, LFM2-VL, dan Florence-2.

Memilih backend

• Kualitas terbaik: qwen3-vl-8b atau qwen3-vl-4b (default).
• Kotak rapat, footprint kecil: florence-2-large.
• Edge / CPU: lfm2-vl-450m atau smolvlm2-500m.
• Lisensi yang sepenuhnya permisif: semua ukuran Qwen3-VL, SmolVLM2, Florence-2, atau Kosmos-2.

Kosakata adalah inti deteksi open-vocabulary. Panggil set_classes() dengan daftar string label. Pengaturan ini melekat: nilainya bertahan pada setiap pemanggilan predict() dan track() berikutnya hingga diatur kembali. Metode ini mengembalikan self, sehingga pemanggilannya dapat dirangkai.

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

Label dapat berupa frasa apa pun. Setiap label harus unik tanpa membedakan huruf besar dan kecil, dan input harus berupa daftar, bukan satu string. Jika set_classes() tidak pernah dipanggil, model kembali ke kosakata COCO-80 sehingga pemanggilan predict() tanpa pengaturan tetap menghasilkan sesuatu yang masuk akal.

predict() (dan pemanggilan model(...) yang setara) menerima tipe sumber yang sama dengan semua detektor LibreYOLO: path, gambar PIL, array numpy, URL, folder, atau video. stream=True dan track() juga berfungsi.

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
)

Struktur hasil

Objek Results standar akan dikembalikan, sama seperti detektor closed-vocabulary:

Di balik layar, LibreVLM mengurai output model secara toleran (menangani pembatas markdown, prosa yang terselip, kotak duplikat, dan array yang terpotong), memetakan label teks bebas kembali ke ID kelas Anda, dan membuang label yang tidak ada dalam kosakata. Langkah terakhir itulah yang membuat generator berformat bebas berperilaku seperti detektor dengan himpunan tertutup.

Deteksi objek dengan warna tertentu

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

Kotak rapat dengan 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()

Filter ke satu kelas secara langsung

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

Jalankan pada CPU dengan gambar sampel bawaan

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, folder, dan 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)

Terkadang yang diperlukan adalah modelnya, bukan detektornya. Family dengan template chat menyediakan chat(), yang menerima gambar dan prompt berformat bebas lalu mengembalikan teks hasil dekode apa adanya. Gunakan untuk penghitungan, pembuatan caption, atau pertanyaan visual cepat.

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)

Setiap family mengembalikan Results yang sama, tetapi mencapainya dengan cara berbeda. Perbedaan ini jarang perlu diperhatikan, tetapi membantu menjelaskan perilaku beberapa backend. Family chat diminta menghasilkan array kotak dalam JSON, sedangkan model grounding menggunakan token task khusus.

Untuk family chat, prompt deteksi dapat ditimpa dengan argumen constructor prompt=, dan panjang generasi dapat dibatasi dengan max_new_tokens=. Perangkat dan dtype ditentukan secara otomatis: bf16 atau fp16 pada CUDA, fp32 pada CPU.

LibreVLM kuat, tetapi masih muda. Mengetahui batasannya sejak awal mencegah kejutan di kemudian hari.

• Skor keyakinan sintetis. Setiap kotak diberi skor 1.0. Karena itu, filter conf= bersifat semua-atau-tidak-sama-sekali, bukan sebagai ambang batas nyata.
• Tanpa mAP / validasi. val() memicu error karena skor sintetis akan membuat mAP COCO menyesatkan.
• Tanpa pelatihan atau ekspor. train() dan export() memicu error. Sebagai gantinya, lakukan fine-tuning pada VLM upstream lalu muat bobot yang dihasilkan.
• Kualitas pelacakan menurun. track() dapat dijalankan, tetapi skor yang seragam membuat tahap pemulihan dengan skor keyakinan rendah pada pelacak tidak berfungsi.
• Satu gambar setiap kali. Generasi berlangsung secara berurutan di v1, sehingga nilai batch= yang lebih besar tidak mempercepat proses.
• Hanya API Python. CLI libreyolo belum dapat mengenali alias VLM.