LibreVLM

LibreVLM доступний через необов'язковий додатковий пакет vlm. Він встановлює нову версію transformers і допоміжні засоби, потрібні кільком процесорам. Без цього пакета імпорт сімейства VLM спричиняє ImportError із посиланням на цей розділ.

1
pip install 'libreyolo[vlm]'

Ваги завантажуються з Hugging Face Hub під час першого використання до локальної папки weights/. Кілька сімейств постачаються за ліцензіями, не схваленими OSI, і перед завантаженням одноразово показують повідомлення. Для більших бекендів рекомендовано GPU, але кожна модель також працює на CPU з device="cpu".

Створіть модель, укажіть потрібні слова та запустіть передбачення. Типовим бекендом є Qwen3-VL-4B, найсильніший детектор цього рівня з ліцензією 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")

Це весь цикл. Усе після predict() поводиться як звичайний детектор, тому наявний код візуалізації, обрізання й відстеження продовжує працювати.

Виберіть бекенд за псевдонімом, який передаєте до LibreVLM(...). Назва сімейства без розміру відповідає типовому розміру. Загальним типовим бекендом є qwen3-vl-4b. На практиці найсильнішими детекторами є Qwen3-VL, LFM2-VL і Florence-2.

Вибір бекенда

• Найкраща якість: qwen3-vl-8b або qwen3-vl-4b (типовий).
• Щільні рамки й малий обсяг: florence-2-large.
• Edge-пристрої / CPU: lfm2-vl-450m або smolvlm2-500m.
• Повністю дозвільна ліцензія: будь-який розмір Qwen3-VL, SmolVLM2, Florence-2 або Kosmos-2.

Словник є основою виявлення з відкритим словником. Викличте set_classes() зі списком рядків міток. Він зберігається для всіх наступних викликів predict() і track(), доки ви не задасте його знову. Метод повертає self, тому виклики можна з'єднувати в ланцюжок.

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

Міткою може бути будь-яка фраза. Мітки мають бути унікальними без урахування регістру, і потрібно передати список, а не окремий рядок. Якщо жодного разу не викликати set_classes(), модель використовує словник COCO-80, тому звичайний виклик predict() усе одно дає осмислений результат.

predict() (і еквівалентний виклик model(...)) приймає ті самі типи джерел, що й будь-який детектор LibreYOLO: шлях, зображення PIL, масив NumPy, URL, папку або відео. stream=True і 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
)

Структура результату

Ви отримуєте стандартний об'єкт Results, ідентичний результату детектора із закритим словником:

Усередині LibreVLM стійко аналізує вихід моделі (обробляє огорожі Markdown, сторонній текст, дубльовані рамки й обрізані масиви), зіставляє довільні текстові мітки з ідентифікаторами ваших класів і відкидає всі мітки поза вашим словником. Саме останній крок змушує генератор довільного тексту поводитися як детектор із закритим набором класів.

Виявити об'єкт певного кольору

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

Щільні рамки з 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()

Фільтрувати до одного класу під час виконання

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

Запустити на CPU із вбудованим зразком зображення

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"

Батчі, папки та відео

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)

Іноді потрібна модель, а не детектор. Сімейства із шаблонами чату надають chat(), який приймає зображення та довільний промпт і дослівно повертає декодований текст. Використовуйте його для підрахунку, створення підписів або швидких запитань про зображення.

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)

Кожне сімейство повертає той самий Results, але отримує його по-різному. Це рідко має значення, проте пояснює поведінку деяких бекендів. Сімейства чату отримують промпт із запитом на масив рамок JSON, а моделі прив'язування використовують спеціальні токени задач.

Для сімейств чату промпт виявлення можна перевизначити аргументом конструктора prompt=, а довжину генерації обмежити за допомогою max_new_tokens=. Пристрій і dtype визначаються автоматично: bf16 або fp16 у CUDA, fp32 на CPU.

LibreVLM має широкі можливості, але ще молодий. Знання обмежень заздалегідь допоможе уникнути несподіванок.

• Синтетична впевненість. Кожна рамка отримує оцінку 1.0. Тому фільтр conf= пропускає або відкидає все, а не працює як справжній поріг.
• Без mAP і валідації. val() спричиняє помилку, оскільки синтетичні оцінки зробили б COCO mAP оманливим.
• Без навчання та експорту. train() і export() спричиняють помилку. Натомість донавчіть VLM у першоджерелі й завантажте отримані ваги.
• Погіршене відстеження. track() працює, але однакові оцінки роблять етап відновлення з низькою впевненістю у трекері неактивним.
• По одному зображенню. У v1 генерація послідовна, тому більші значення batch= не дають прискорення.
• Лише API Python. CLI libreyolo поки не розпізнає псевдоніми VLM.