LibreVLM

LibreVLM se encuentra tras el extra opcional vlm. Este instala una versión reciente de transformers y las utilidades que necesitan algunos procesadores. Sin el extra, importar una familia VLM genera un ImportError que remite a esta página.

1
pip install 'libreyolo[vlm]'

Los pesos se descargan desde Hugging Face Hub la primera vez que se usan y se guardan en una carpeta local weights/. Algunas familias se distribuyen con licencias que no son OSI y muestran un aviso una sola vez antes de la descarga. Se recomienda una GPU para los backends más grandes, pero todos los modelos también se ejecutan en CPU con device="cpu".

Construye un modelo, declara las palabras que te interesan y realiza una predicción. El backend predeterminado es Qwen3-VL-4B, el detector más potente del nivel, con licencia 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")

Ese es todo el ciclo. Todo lo que viene después de predict() se comporta como un detector normal, por lo que el código existente de visualización, recorte y seguimiento sigue funcionando.

Elige un backend mediante el alias que pasas a LibreVLM(...). Un nombre de familia sin más se resuelve al tamaño predeterminado. El backend predeterminado general es qwen3-vl-4b. En la práctica, los detectores más potentes son Qwen3-VL, LFM2-VL y Florence-2.

Elegir un backend

• Mejor calidad: qwen3-vl-8b o qwen3-vl-4b (el predeterminado).
• Cajas ajustadas, poco espacio: florence-2-large.
• Edge / CPU: lfm2-vl-450m o smolvlm2-500m.
• Licencia totalmente permisiva: cualquier tamaño de Qwen3-VL, SmolVLM2, Florence-2 o Kosmos-2.

El vocabulario es el núcleo de la detección de vocabulario abierto. Llama a set_classes() con una lista de cadenas de etiquetas. Es persistente: se conserva en todas las llamadas posteriores a predict() y track() hasta que vuelvas a configurarlo. Devuelve self, por lo que permite encadenar llamadas.

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

Las etiquetas pueden ser cualquier frase. Deben ser únicas sin distinguir entre mayúsculas y minúsculas, y debes pasar una lista, no una cadena sola. Si nunca llamas a set_classes(), el modelo utiliza el vocabulario COCO-80 como alternativa para que un simple predict() siga haciendo algo razonable.

predict() (y la llamada equivalente model(...)) acepta los mismos tipos de fuente que cualquier detector de LibreYOLO: una ruta, una imagen PIL, un array de numpy, una URL, una carpeta o un vídeo. stream=True y track() también funcionan.

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
)

Forma de la salida

Recibes el objeto Results estándar, idéntico al de un detector de vocabulario cerrado:

Internamente, LibreVLM analiza de forma tolerante la salida del modelo (gestiona bloques de Markdown, texto suelto, cajas duplicadas y arrays truncados), vuelve a asignar las etiquetas de texto libre a tus identificadores de clase y descarta cualquier etiqueta que no esté en tu vocabulario. Este último paso hace que un generador de formato libre se comporte como un detector de conjunto cerrado.

Detectar un objeto de un color específico

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

Cajas ajustadas con 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()

Filtrar a una sola clase sobre la marcha

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

Ejecutar en CPU con una imagen de muestra integrada

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"

Batches, carpetas y vídeo

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)

A veces quieres el modelo, no el detector. Las familias con plantilla de chat exponen chat(), que recibe una imagen y un prompt de formato libre y devuelve literalmente el texto decodificado. Úsalo para contar, generar descripciones o responder preguntas visuales rápidas.

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)

Todas las familias devuelven el mismo objeto Results, pero llegan a él de formas distintas. Rara vez necesitas preocuparte por ello, aunque ayuda a entender por qué algunos backends se comportan como lo hacen. A las familias de chat se les solicita un array JSON de cajas; los modelos de localización usan tokens de tarea específicos.

En las familias de chat puedes sustituir el prompt de detección mediante el argumento prompt= del constructor y limitar la longitud de generación con max_new_tokens=. El dispositivo y el dtype se resuelven automáticamente: bf16 o fp16 en CUDA, fp32 en CPU.

LibreVLM es potente, pero joven. Conocer sus límites desde el principio evita sorpresas más adelante.

• Confianza sintética. Cada caja recibe una puntuación de 1.0. Por tanto, el filtro conf= se comporta como un todo o nada en lugar de como un umbral real.
• Sin mAP ni validación. val() genera un error, porque las puntuaciones sintéticas harían engañoso el mAP de COCO.
• Sin entrenamiento ni exportación. train() y export() generan un error. Haz fine-tuning del VLM en el proyecto original y carga los pesos resultantes.
• Seguimiento degradado. track() se ejecuta, pero las puntuaciones uniformes dejan inactiva la fase de recuperación de baja confianza del tracker.
• Una imagen cada vez. La generación es secuencial en v1, por lo que los valores mayores de batch= no aceleran el proceso.
• Solo API de Python. La CLI de libreyolo todavía no resuelve los alias de VLM.