API vision-language моделей

Установка

Этому уровню нужен extra vlm.

pip install 'libreyolo[vlm]'

Фабрика

LibreVLM(model: str = "qwen3-vl-4b", **kwargs) -> LibreVLMModel

model — это алиас, а не путь. **kwargs передаётся в конструктор семейства, который принимает device, names (начальный словарь, то же самое, что вызвать set_classes после загрузки), prompt (переопределяет промпт детекции) и max_new_tokens. Неизвестный алиас вызывает ValueError со списком всех алиасов.

from libreyolo import LibreVLM, SAMPLE_IMAGE model = LibreVLM("lfm2-vl-450m")model.set_classes(["person", "skateboard"]) result = model.predict(SAMPLE_IMAGE)for box, cls in zip(result.boxes.xyxy, result.boxes.cls):    print(result.names[int(cls)], box.tolist())

from libreyolo import LibreVLM, SAMPLE_IMAGE model = LibreVLM("lfm2-vl-450m")print(model.chat(SAMPLE_IMAGE, "How many people are in this image?"))

Алиасы

Алиас по умолчанию — qwen3-vl-4b. Для алиаса по умолчанию каждого семейства берётся размер, указанный первым: qwen3-vl разрешается в 4b, lfm2-vl — в 450m, internvl3 — в 2b, smolvlm2 — в 2.2b, florence-2 — в base, wevisone-vl — в 2b.

LibreVLM, LibreLFM2VL, LibreQwen3VL, LibreSmolVLM2, LibreInternVL3, LibreFlorence2, LibreKosmos2, LibreLocateAnything, LibreWeVisOneVL и LibreMODUS (также пишется LibreModus) экспортируются на уровне пакета.

Детекция также включает north-micro-vision, gemma-4-e2b, gemma-4-e4b, moondream-2, moondream-3 и lfm2-vl-3b. Псевдоним gemma-4 без суффикса выбирает E4B. Псевдонимы Molmo2: molmo2-4b, molmo2-8b и molmo2-o-7b; по умолчанию выбран 4B. Псевдонимы задают маршрутизацию, но не означают, что каждый удалённый снимок был скачан и проверен. moondream-3 в 1.6.0 не загружается: в его зеркале не хватает шардов весов.

Задачи

Поддержка задач зависит от семейства. Эти адаптеры поддерживают несколько задач:

Задача задаётся промптом, а не запечена в чекпойнт, поэтому её можно переключить на уже загруженной модели:

model.set_task(task: str) -> LibreVLMModel

Задача проверяется по списку поддерживаемых семейством задач, запоминается для последующих вызовов predict() и track(), а модель возвращается, чтобы вызовы можно было соединять в цепочку.

Molmo2 возвращает точки и требует {label} в собственных шаблонах указания точек. referring=True в WeVisOne-VL заставляет detect отправлять по одной генерации на фразу, а его segment, matte и референтная детекция вызывают ValueError без словаря. Moondream поддерживает детекцию, точки и нативный чат. Для запросов клика по инструкции используйте LibreGround.

set_classes

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

Задаёт открытый словарь. Подойдут любые слова, потому что модель получает их в промпте, а не ограничена фиксированной головой. Список должен быть непустым, а его элементы — уникальными при сравнении без учёта регистра. Передача голой строки вызывает TypeError, потому что она развернулась бы в набор односимвольных классов. Словарь запоминается: задайте его один раз после загрузки, и он действует, пока вы не зададите его снова.

chat

model.chat(image, prompt, max_new_tokens=None, color_format="auto") -> str

Сырая мультимодальная генерация: на входе изображение и промпт, на выходе — декодированный текст, дословно. Это запасной выход под удобной обёрткой детекции — для произвольных вопросов, подсчёта объектов или формата вывода, который обёртка детекции не покрывает. max_new_tokens по умолчанию берёт значение MAX_NEW_TOKENS семейства, а в базовом классе оно равно 1024. Декодирование жадное, с мягким штрафом за повторы.

Уверенность

У сгенерированного вывода нет калиброванной уверенности для каждой рамки. В этой версии проставляется постоянная заглушка, чтобы работали predict, отрисовка и track, из-за чего фильтрация по conf= и mAP получаются условными, а не осмысленными. По этой же причине val() выбрасывает исключение: COCO mAP по оценкам-заглушкам вводил бы в заблуждение.

Предсказание и трекинг

Стандартный набор аргументов predict работает как обычно, track() тоже работает, поэтому VLM-детектор встраивается в тот же пайплайн, что и любое другое семейство. Две политики на уровне класса отличаются от свёрточного детектора: аугментация на этапе инференса отключена, потому что многомасштабная аугментация бессмысленна для генератора с фиксированным разрешением, а батчевый predict выключен, потому что генерация авторегрессионная, а препроцессинг возвращает кодировку из текста и изображения, а не тензор изображения, который можно сложить в батч.

Что не поддерживается

Экспорт и валидация mAP детекции не поддерживаются. Обучение ограничено описанным ниже процессом Qwen3-VL.

Удалённый код

Каждое поставляемое семейство загружается через нативный класс модели, поэтому LibreYOLO по умолчанию не выполняет код из сторонних репозиториев. Семейство, которому это действительно нужно, должно явно это включить и зафиксировать ревизию снапшота; LocateAnything — единственное такое семейство, зафиксировано на коммите c32291ca5e996f5a7a485845b4f57a233936bba0.

LibreMODUS — явное исключение из схемы чекпойнтов: его алиас разрешается в каталог зафиксированных файлов апстрима, а не в .pt от LibreYOLO, и LibreYOLO не добавляет к нему метаданные v1.0 и не публикует его заново.

Обучение

Qwen3-VL поддерживает LoRA для детекции через train(data=...) после установки libreyolo[vlm-train]. Визуальный энкодер замораживается, лучшие чекпойнты выбираются по функции потерь на валидации и сохраняются в каталогах. См. дообучение VLM.