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= не ускоряет работу.
• Только Python API. CLI libreyolo пока не разрешает псевдонимы VLM.