API a vocabolario aperto

Installazione

Il tier richiede l'extra openvocab.

pip install 'libreyolo[openvocab]'

La factory

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

model è un alias, non un percorso. Gli underscore diventano trattini prima della ricerca, quindi i nomi qualificati per famiglia che stampa l'inventario della CLI, come omdet_turbo-t e grounding_dino-t, si caricano così come sono. Un alias sconosciuto solleva ValueError elencando tutti gli alias noti.

Il costruttore accetta size, nb_classes=80, names=None, device="auto", task=None e text_threshold=None. Passare names equivale a chiamare set_classes subito dopo il caricamento. Passare text_threshold a una famiglia che non lo supporta solleva 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())

Famiglie e alias

L'alias predefinito è grounding-dino-tiny.

LibreGroundingDINO, LibreOWLv2 e LibreOMDetTurbo sono esportati a livello di pacchetto e si possono costruire direttamente con size=. A OV-DEIM si arriva tramite gli alias della factory qui sopra.

set_classes

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

Imposta il vocabolario per ogni chiamata successiva a predict() e restituisce il modello, così le chiamate si possono concatenare. L'elenco non può essere vuoto, deve contenere solo stringhe e le sue voci devono essere uniche quando le confronti senza distinguere maiuscole e minuscole; le etichette vuote vengono rifiutate. Passare una stringa da sola solleva TypeError, perché verrebbe enumerata in classi di un solo carattere.

Dopo la chiamata, model.names mappa 0..N-1 sulle etichette nell'ordine dato, e model.nb_classes vale N.

Argomenti di chiamata

Il tier riusa la superficie standard di predict con tre differenze.

conf usa come valore predefinito quello della singola famiglia invece dello 0.25 condiviso:

iou= significa qualcosa solo per una famiglia che esegue la soppressione. OMDet-Turbo prende la soglia come argomento e la imposta a 0.5 quando iou= non è indicato. Le altre tre non sopprimono nulla, quindi passare iou= lì emette un avviso e viene ignorato.

text_threshold= riguarda solo Grounding DINO, dove vale 0.25 di default. Si può passare alla costruzione per avere un valore persistente, oppure a ogni chiamata. Un valore per chiamata non si può combinare con stream=True, perché i risultati in streaming sono generati in modo pigro; in quel caso impostalo sul costruttore. Ogni altra famiglia solleva TypeError.

imgsz= solleva ValueError: in questo tier è la pipeline di preprocessing a occuparsi del ridimensionamento. Anche augment=True solleva un errore, dato che la data augmentation in fase di test è fuori dallo scopo qui. Le dimensioni di input sono registrate per famiglia solo a titolo di riferimento: Grounding DINO 800, OWLv2 960 e 1008, OMDet-Turbo 640, OV-DEIM 640.

Non supportato

train(), val(), track() e export() sollevano tutti NotImplementedError. Fai il fine-tuning upstream e carica i pesi risultanti; esegui predict() per ogni frame al posto del tracking. La validazione richiederebbe un validatore dedicato, perché il validatore di rilevamento condiviso chiama il modello con tensori immagine mentre questo tier richiede input condizionati dal testo.