LibreVLM

LibreVLM est disponible via l'extra facultatif vlm. Celui-ci installe une version récente de transformers et les utilitaires requis par certains processeurs. Sans cet extra, l'import d'une famille VLM déclenche une ImportError qui vous renvoie ici.

1
pip install 'libreyolo[vlm]'

Les poids sont téléchargés depuis le Hub Hugging Face lors de la première utilisation, dans un dossier local weights/. Quelques familles sont fournies sous des licences non OSI et affichent un avertissement unique avant le téléchargement. Un GPU est recommandé pour les backends les plus volumineux, mais chaque modèle fonctionne aussi sur CPU avec device="cpu".

Construisez un modèle, définissez les mots qui vous intéressent et lancez une prédiction. Le backend par défaut est Qwen3-VL-4B, le détecteur le plus performant du niveau, sous licence 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")

La boucle complète se résume à cela. Tout ce qui suit predict() se comporte comme avec un détecteur normal : le code existant de visualisation, de recadrage et de suivi continue donc de fonctionner.

Choisissez un backend avec l'alias que vous transmettez à LibreVLM(...). Un nom de famille seul correspond à sa taille par défaut. Le backend global par défaut est qwen3-vl-4b. En pratique, les détecteurs les plus performants sont Qwen3-VL, LFM2-VL et Florence-2.

Choisir un backend

• Meilleure qualité : qwen3-vl-8b ou qwen3-vl-4b (modèle par défaut).
• Boîtes ajustées, faible encombrement : florence-2-large.
• Edge / CPU : lfm2-vl-450m ou smolvlm2-500m.
• Licence entièrement permissive : toutes les tailles de Qwen3-VL, SmolVLM2, Florence-2 ou Kosmos-2.

Le vocabulaire est au cœur de la détection à vocabulaire ouvert. Appelez set_classes() avec une liste de chaînes d'étiquettes. Ce réglage est persistant : il s'applique à tous les appels ultérieurs à predict() et track() jusqu'à ce que vous le redéfinissiez. La méthode renvoie self, ce qui permet de chaîner les appels.

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

Les étiquettes peuvent être n'importe quelle expression. Elles doivent être uniques sans tenir compte de la casse, et vous devez transmettre une liste, pas une simple chaîne. Si vous n'appelez jamais set_classes(), le modèle utilise le vocabulaire COCO-80 par défaut afin qu'un simple predict() produise tout de même un résultat pertinent.

predict() (et l'appel équivalent à model(...)) accepte les mêmes types de sources que tous les détecteurs LibreYOLO : un chemin, une image PIL, un tableau numpy, une URL, un dossier ou une vidéo. stream=True et track() fonctionnent aussi.

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
)

Structure du retour

Vous récupérez l'objet Results standard, identique à celui d'un détecteur à vocabulaire fermé :

En interne, LibreVLM analyse avec tolérance la sortie du modèle (blocs délimités en Markdown, texte parasite, boîtes dupliquées et tableaux tronqués), remappe les étiquettes de texte libre vers vos identifiants de classe et ignore toute étiquette absente de votre vocabulaire. Cette dernière étape permet à un générateur libre de se comporter comme un détecteur à ensemble fermé.

Détecter un objet d'une couleur précise

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

Boîtes ajustées avec 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()

Filtrer à la volée sur une seule classe

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

Exécuter sur CPU avec une image d'exemple intégrée

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"

Batchs, dossiers et vidéo

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)

Vous avez parfois besoin du modèle, pas du détecteur. Les familles à template de chat exposent chat(), qui reçoit une image et un prompt libre, puis renvoie le texte décodé tel quel. Utilisez-la pour compter, générer des légendes ou répondre à des questions visuelles rapides.

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)

Chaque famille renvoie le même Results, mais y parvient différemment. Vous avez rarement besoin de vous en préoccuper, mais ces détails expliquent le comportement de certains backends. Les familles de chat reçoivent un prompt demandant un tableau JSON de boîtes ; les modèles de grounding utilisent des tokens de tâche dédiés.

Pour les familles de chat, vous pouvez remplacer le prompt de détection avec l'argument de constructeur prompt= et limiter la longueur de génération avec max_new_tokens=. Le device et le dtype sont déterminés automatiquement : bf16 ou fp16 sur CUDA, fp32 sur CPU.

LibreVLM est puissant mais encore jeune. Connaître ses limites dès le départ évite les surprises.

• Confiance synthétique. Chaque boîte reçoit un score de 1.0. Le filtre conf= fonctionne donc en tout ou rien, plutôt que comme un véritable seuil.
• Pas de mAP ni de validation. val() déclenche une erreur, car des scores synthétiques rendraient la mAP COCO trompeuse.
• Pas d'entraînement ni d'export. train() et export() déclenchent une erreur. Faites le fine-tuning du VLM en amont et chargez plutôt les poids obtenus.
• Suivi dégradé. track() s'exécute, mais les scores uniformes rendent inopérante l'étape de récupération à faible confiance du tracker.
• Une seule image à la fois. La génération est séquentielle dans la v1, donc augmenter la valeur de batch= n'accélère pas le traitement.
• API Python uniquement. La CLI libreyolo ne résout pas encore les alias VLM.