API open-vocabulary

Instalasi

Tier ini memerlukan ekstra openvocab.

pip install 'libreyolo[openvocab]'

Factory

LibreOpenVocab(model: str = "grounding-dino-tiny", **kwargs) -> LibreOpenVocabDetector

model adalah alias, bukan path. Underscore diubah menjadi tanda hubung sebelum lookup, sehingga nama dengan kualifikasi family yang dicetak oleh inventaris CLI, seperti omdet_turbo-t dan grounding_dino-t, dimuat sebagaimana diberikan. Alias yang tidak dikenal memunculkan ValueError yang mencantumkan semua alias yang diketahui.

Constructor menerima size, nb_classes=80, names=None, device="auto", task=None, dan text_threshold=None. Memberikan names sama dengan memanggil set_classes segera setelah pemuatan. Memberikan text_threshold kepada family yang tidak mendukungnya memunculkan TypeError.

from libreyolo import LibreOpenVocab, SAMPLE_IMAGE model = LibreOpenVocab("grounding-dino-tiny")model.set_classes(["person", "skateboard", "handrail"]) result = model.predict(SAMPLE_IMAGE)for box, cls in zip(result.boxes.xyxy, result.boxes.cls):    print(result.names[int(cls)], box.tolist())

Family dan alias

Alias default adalah grounding-dino-tiny.

LibreGroundingDINO, LibreOWLv2, dan LibreOMDetTurbo diekspor pada level package dan dapat dibuat secara langsung dengan size=. OV-DEIM dapat diakses melalui alias factory di atas.

set_classes

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

Menetapkan vocabulary untuk setiap pemanggilan predict() berikutnya, serta mengembalikan model agar pemanggilan dapat dirangkai. List tidak boleh kosong, hanya boleh memuat string, dan elemennya harus unik saat dibandingkan tanpa memedulikan kapitalisasi; label kosong ditolak. Memberikan string langsung memunculkan TypeError karena string tersebut akan diuraikan menjadi kelas satu karakter.

Setelah pemanggilan, model.names memetakan 0..N-1 ke label dalam urutan yang diberikan, dan model.nb_classes bernilai N.

Argumen pemanggilan

Tier ini menggunakan kembali antarmuka predict standar dengan tiga perbedaan.

Default conf menggunakan nilai milik family, bukan nilai bersama 0.25:

iou= hanya bermakna untuk family yang menjalankan suppression. OMDet-Turbo menerima ambang batas sebagai argumen dan memiliki default 0.5 ketika iou= tidak ditetapkan. Tiga family lainnya tidak melakukan suppression, sehingga memberikan iou= akan memunculkan peringatan dan diabaikan.

text_threshold= hanya untuk Grounding DINO, dengan default 0.25. Nilai ini dapat diberikan saat konstruksi sebagai nilai persisten atau per pemanggilan. Nilai per pemanggilan tidak dapat digabungkan dengan stream=True karena hasil stream dibuat secara lazy; tetapkan pada constructor sebagai gantinya. Semua family lain memunculkan TypeError jika menerimanya.

imgsz= memunculkan ValueError: pipeline preprocessing mengendalikan pengubahan ukuran untuk tier ini. augment=True juga memunculkan error karena augmentasi saat pengujian berada di luar cakupan. Ukuran input dicatat per family hanya sebagai referensi: Grounding DINO 800, OWLv2 960 dan 1008, OMDet-Turbo 640, OV-DEIM 640.

Tidak didukung

train(), val(), track(), dan export() semuanya memunculkan NotImplementedError. Lakukan fine-tuning di upstream dan muat bobot yang dihasilkan; jalankan predict() per frame sebagai pengganti tracking. Validasi akan memerlukan validator khusus karena validator deteksi bersama memanggil model dengan tensor gambar, sedangkan tier ini memerlukan input yang dikondisikan oleh teks.