API de vocabulário aberto

Instalação

Este tier precisa do extra openvocab.

pip install 'libreyolo[openvocab]'

A factory

LibreOpenVocab(model: str = "grounding-dino-tiny", **kwargs) -> LibreOpenVocabDetector

model é um alias, não um caminho. Underscores viram hífens antes da busca, então os nomes qualificados por família que o inventário da CLI imprime, como omdet_turbo-t e grounding_dino-t, carregam do jeito que estão. Um alias desconhecido levanta ValueError listando todos os aliases conhecidos.

O construtor aceita size, nb_classes=80, names=None, device="auto", task=None e text_threshold=None. Passar names é o mesmo que chamar set_classes logo depois de carregar. Passar text_threshold para uma família que não o suporta levanta TypeError.

from libreyolo import LibreOpenVocab, SAMPLE_IMAGE model = LibreOpenVocab("grounding-dino-tiny")model.set_classes(["person", "skateboard", "handrail"]) result = model.predict(SAMPLE_IMAGE)for box, cls in zip(result.boxes.xyxy, result.boxes.cls):    print(result.names[int(cls)], box.tolist())

Famílias e aliases

O alias padrão é grounding-dino-tiny.

LibreGroundingDINO, LibreOWLv2 e LibreOMDetTurbo são exportados no nível do pacote e podem ser construídos diretamente com size=. O OV-DEIM é acessível pelos aliases da factory acima.

set_classes

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

Define o vocabulário para toda chamada predict() posterior e retorna o modelo para que as chamadas possam ser encadeadas. A lista precisa ser não vazia, conter apenas strings e ter entradas únicas quando comparadas sem diferenciar maiúsculas de minúsculas; rótulos em branco são rejeitados. Passar uma string solta levanta TypeError, porque ela seria enumerada em classes de um caractere.

Depois da chamada, model.names mapeia 0..N-1 para os rótulos na ordem dada, e model.nb_classes é N.

Argumentos de chamada

Este tier reaproveita a superfície padrão de predict com três diferenças.

conf assume por padrão o valor da própria família, e não o 0.25 compartilhado:

iou= só significa alguma coisa para uma família que roda supressão. O OMDet-Turbo recebe o limiar como argumento e usa 0.5 por padrão quando iou= não é definido. As outras três não suprimem nada, então passar iou= nelas emite um aviso e é ignorado.

text_threshold= é exclusivo do Grounding DINO, onde o padrão é 0.25. Pode ser passado na construção para um valor persistente, ou por chamada. Um valor por chamada não pode ser combinado com stream=True, porque os resultados em stream são gerados de forma preguiçosa; nesse caso, defina o valor no construtor. Toda outra família levanta TypeError para ele.

imgsz= levanta ValueError: o pipeline de pré-processamento é o dono do redimensionamento neste tier. augment=True também levanta, já que o data augmentation em tempo de teste está fora de escopo aqui. Os tamanhos de entrada são registrados por família apenas para referência: Grounding DINO 800, OWLv2 960 e 1008, OMDet-Turbo 640, OV-DEIM 640.

Sem suporte

train(), val(), track() e export() levantam todos NotImplementedError. Faça fine-tuning upstream e carregue os pesos resultantes; rode predict() por quadro no lugar do tracking. A validação precisaria de um validador dedicado, porque o validador de detecção compartilhado chama o modelo com tensores de imagem, enquanto este tier exige entradas condicionadas por texto.