API de vocabulario abierto

Instalación

El tier necesita el extra openvocab.

pip install 'libreyolo[openvocab]'

La factoría

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

model es un alias, no una ruta. Los guiones bajos se convierten en guiones antes de la búsqueda, así que los nombres cualificados por familia que imprime el inventario de la CLI, como omdet_turbo-t y grounding_dino-t, se cargan tal cual. Un alias desconocido lanza ValueError con la lista de todos los alias conocidos.

El constructor acepta size, nb_classes=80, names=None, device="auto", task=None y text_threshold=None. Pasar names equivale a llamar a set_classes justo después de cargar. Pasar text_threshold a una familia que no lo admite lanza 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())

Familias y alias

El alias por defecto es grounding-dino-tiny.

LibreGroundingDINO, LibreOWLv2 y LibreOMDetTurbo se exportan a nivel de paquete y se pueden construir directamente con size=. A OV-DEIM se llega a través de los alias de la factoría de arriba.

set_classes

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

Fija el vocabulario para todas las llamadas posteriores a predict() y devuelve el modelo, de modo que las llamadas se pueden encadenar. La lista no puede estar vacía, solo puede contener strings y sus entradas deben ser únicas al compararlas sin distinguir mayúsculas y minúsculas; las etiquetas en blanco se rechazan. Pasar una string suelta lanza TypeError, porque se enumeraría en clases de un solo carácter.

Tras la llamada, model.names asigna 0..N-1 a las etiquetas en el orden dado, y model.nb_classes es N.

Argumentos de llamada

El tier reutiliza la superficie estándar de predict con tres diferencias.

conf toma por defecto el valor propio de cada familia en lugar del 0.25 compartido:

iou= solo significa algo en una familia que ejecuta supresión. OMDet-Turbo toma el umbral como argumento y usa 0.5 por defecto cuando iou= no se indica. Las otras tres no suprimen nada, así que pasar iou= ahí emite un aviso y se ignora.

text_threshold= es exclusivo de Grounding DINO, donde vale 0.25 por defecto. Se puede pasar en la construcción para tener un valor persistente, o llamada a llamada. Un valor por llamada no se puede combinar con stream=True, porque los resultados en streaming se generan de forma perezosa; en ese caso, fíjalo en el constructor. Cualquier otra familia lanza TypeError con él.

imgsz= lanza ValueError: en este tier, el pipeline de preprocesado es el dueño del redimensionado. augment=True también lanza, porque el aumento en tiempo de test queda fuera de alcance aquí. Los tamaños de entrada se registran por familia solo como referencia: Grounding DINO 800, OWLv2 960 y 1008, OMDet-Turbo 640, OV-DEIM 640.

No soportado

train(), val(), track() y export() lanzan todos NotImplementedError. Haz el fine-tuning upstream y carga los pesos resultantes; ejecuta predict() por frame en lugar de hacer tracking. La validación necesitaría un validador dedicado, porque el validador de detección compartido llama al modelo con tensores de imagen mientras que este tier requiere entradas condicionadas por texto.