LibreVLM

O LibreVLM fica disponível por meio do extra opcional vlm. Ele instala uma versão recente de transformers e os auxiliares exigidos por alguns processadores. Sem o extra, importar uma família VLM gera um ImportError que aponta para esta página.

1
pip install 'libreyolo[vlm]'

Os pesos são baixados do Hugging Face Hub no primeiro uso para uma pasta local weights/. Algumas famílias são distribuídas sob licenças que não são da OSI e registram um aviso único antes do download. Recomenda-se uma GPU para os backends maiores, mas todos os modelos também rodam em CPU com device="cpu".

Crie um modelo, declare as palavras que interessam e faça a predição. O backend padrão é Qwen3-VL-4B, o detector mais forte do nível, com licença 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")

Esse é o ciclo completo. Tudo depois de predict() se comporta como um detector normal, então o código existente de visualização, recorte e rastreamento continua funcionando.

Escolha um backend pelo alias passado a LibreVLM(...). O nome da família sem tamanho usa o tamanho padrão. O backend padrão geral é qwen3-vl-4b. Na prática, os detectores mais fortes são Qwen3-VL, LFM2-VL e Florence-2.

Escolha de um backend

• Melhor qualidade: qwen3-vl-8b ou qwen3-vl-4b (o padrão).
• Bounding boxes precisos e tamanho reduzido: florence-2-large.
• Edge / CPU: lfm2-vl-450m ou smolvlm2-500m.
• Licença totalmente permissiva: qualquer tamanho de Qwen3-VL, SmolVLM2, Florence-2 ou Kosmos-2.

O vocabulário é o centro da detecção de vocabulário aberto. Chame set_classes() com uma lista de strings de labels. A configuração é persistente: ela permanece em todas as chamadas posteriores de predict() e track() até você defini-la novamente. O método retorna self, portanto pode ser encadeado.

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

As labels podem ser qualquer frase. Elas precisam ser únicas sem diferenciar maiúsculas de minúsculas, e você deve passar uma lista, não uma string isolada. Se você nunca chamar set_classes(), o modelo usará o vocabulário COCO-80, para que um predict() isolado ainda produza um resultado razoável.

predict() (e a chamada equivalente model(...)) aceita os mesmos tipos de fonte que qualquer detector do LibreYOLO: um caminho, uma imagem PIL, um array numpy, uma URL, uma pasta ou um vídeo. stream=True e track() também funcionam.

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
)

Formato do retorno

Você recebe o objeto Results padrão, idêntico ao de um detector de vocabulário fechado:

Nos bastidores, o LibreVLM analisa a saída do modelo de forma tolerante (lidando com blocos de markdown, texto solto, bounding boxes duplicados e arrays truncados), mapeia labels de texto livre de volta aos IDs das suas classes e descarta qualquer label que não esteja no seu vocabulário. Essa última etapa faz um gerador de formato livre se comportar como um detector de conjunto fechado.

Detectar um objeto de uma cor específica

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

Bounding boxes precisos com 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 para uma única classe durante a execução

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

Executar na CPU com uma imagem de amostra 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, pastas e 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)

Às vezes, você quer o modelo, não o detector. As famílias com template de chat expõem chat(), que recebe uma imagem e um prompt de formato livre e retorna o texto decodificado sem alterações. Use-o para contagem, criação de legendas ou perguntas visuais 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 as famílias retornam o mesmo Results, mas chegam a ele de maneiras diferentes. Você raramente precisa se preocupar com isso, porém conhecer essas diferenças ajuda a entender por que alguns backends se comportam como se comportam. As famílias de chat recebem a instrução de gerar um array JSON de bounding boxes. Os modelos de grounding usam tokens de tarefa dedicados.

Nas famílias de chat, você pode substituir o prompt de detecção com o argumento prompt= do construtor e limitar o comprimento da geração com max_new_tokens=. O dispositivo e o dtype são definidos automaticamente: bf16 ou fp16 no CUDA, fp32 na CPU.

O LibreVLM é poderoso, mas ainda é recente. Conhecer os limites de antemão evita surpresas depois.

• Confiança sintética. Todo bounding box recebe pontuação 1.0. Portanto, o filtro conf= se comporta como tudo ou nada, em vez de usar um limiar real.
• Sem mAP / validação. val() gera um erro porque as pontuações sintéticas tornariam o mAP do COCO enganoso.
• Sem treinamento nem exportação. train() e export() geram erros. Faça fine-tuning do VLM na origem e carregue os pesos resultantes.
• Rastreamento degradado. track() funciona, mas as pontuações uniformes tornam inativa a etapa de recuperação de baixa confiança do rastreador.
• Uma imagem por vez. A geração é sequencial na v1, então valores maiores de batch= não aceleram o processamento.
• Somente API Python. A CLI libreyolo ainda não reconhece aliases de VLM.