API del modello

Costruzione

La factory restituisce un'istanza della classe di famiglia. Costruire quella classe direttamente accetta gli stessi argomenti, salvo che size è obbligatorio:

Family(model_path, size, nb_classes=80, device="auto", task=None, **kwargs)

device="auto" seleziona CUDA quando è disponibile, poi MPS, poi la CPU. Un intero o una stringa di cifre viene letto come ordinale CUDA, quindi device=0 e device="0" significano entrambi cuda:0. task viene validato rispetto ai SUPPORTED_TASKS della famiglia. Passare model_path=None costruisce l'architettura e la lascia in modalità di addestramento; passare un dict carica direttamente quello state dict.

predict e __call__

predict è un alias di __call__.

model(    source=None,    *,    conf=0.25,    iou=0.45,    imgsz=None,    device=None,    classes=None,    max_det=300,    agnostic_nms=False,    augment=False,    save=False,    batch=1,    stream=False,    stream_buffer=False,    vid_stride=1,    show=False,    output_path=None,    color_format="auto",    tiling=False,    overlap_ratio=0.2,    output_file_format=None,    cuda_graph=False,    **kwargs,)

Una sorgente con una sola immagine restituisce un Results. Una lista, una tupla o una directory ne restituiscono una lista, e stream=True restituisce un generatore in ogni caso.

Le sorgenti di stream dal vivo sono illimitate e richiedono stream=True. tiling e augment non possono essere combinati. La data augmentation al momento del test solleva un errore per i task embed, point ed edge.

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreYOLO9t.pt") model.info()result = model(SAMPLE_IMAGE, conf=0.25, iou=0.45) print(result.boxes.xyxy)print(result.speed)

Con batch > 1, le famiglie il cui SUPPORTS_BATCHED_PREDICT è true eseguono un forward impilato per ogni chunk; batch=1 mantiene un forward per immagine.

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreYOLO9t.pt") # stream=True restituisce un generatore, un Results per frame o immagine.for result in model([SAMPLE_IMAGE, SAMPLE_IMAGE], stream=True):    print(len(result))

embed

model.embed(source=None, **kwargs) -> torch.Tensor

Un wrapper di comodo su predict che impila ogni riga di embedding in un unico tensore (N_total, D). Il modello deve essere stato costruito con task="embed", altrimenti solleva NotImplementedError.

track

model.track(    source,    *,    track_conf=0.25,    conf=None,    iou=0.45,    imgsz=None,    classes=None,    max_det=300,    save=False,    show=False,    vid_stride=1,    fps=30.0,    color_format="auto",    output_path=None,    tracker="bytetrack",    tracker_config=None,    augment=False,    persist=False,    **tracker_kwargs,) -> Generator[Results, None, None]

Produce un Results per frame con track_id impostato. tracker è "bytetrack", "botsort", "ocsort" o "deepocsort", eventualmente con un suffisso .yaml, oppure un'istanza di tracker personalizzato, e viene ignorato quando si passa tracker_config, perché è il tipo di config a selezionare il tracker. track_conf corrisponde a track_high_thresh per ByteTrack e BoT-SORT e a det_thresh per OC-SORT e Deep OC-SORT. conf, quando è indicato, è la soglia di rilevamento, come in predict(). persist=True mantiene il tracker della chiamata precedente per i cicli frame per frame. Il valore predefinito di output_path è runs/track/<video_stem>.mp4.

val

model.val(    data=None,    batch=16,    imgsz=None,    conf=0.001,    iou=0.6,    workers=4,    allow_download_scripts=False,    device=None,    split="val",    augment=False,    save_json=False,    verbose=True,    *,    plots=None,    project=None,    name=None,    exist_ok=False,    **kwargs,) -> Dict

Restituisce un dizionario di metriche le cui chiavi dipendono dal task; il rilevamento restituisce metrics/precision, metrics/recall, metrics/mAP50 e metrics/mAP50-95. imgsz accetta un int quadrato o una tupla (height, width) e per impostazione predefinita usa la dimensione di input nativa del modello. data=None valida sul dataset salvato nella configurazione di addestramento del checkpoint e solleva un errore quando non ce n'è uno, come nei pesi pubblicati. project, name e exist_ok impostano la directory di output come project/name, incrementata a meno che exist_ok=True. plots è un alias di save_plots. allow_download_scripts regola l'esecuzione del Python incorporato che un YAML di dataset può portare nel suo campo download.

Per detect e segment il dizionario è una sottoclasse di dict che porta anche box (metriche per immagine e curve di precisione, recall e F1 per classe) e confusion_matrix; per classify porta top1, top5 e confusion_matrix. Vedi Validazione e metriche.

faster_coco_eval è accettato tramite **kwargs e vale True per impostazione predefinita, con ripiego su pycocotools quando il pacchetto non è installato. Il backend che è stato usato viene riportato in model.last_eval_backend.

agnostic_nms=True, anche tramite **kwargs, applica la NMS agnostica rispetto alla classe a iou prima del calcolo del punteggio. Copre detect e segment e solleva ValueError su qualsiasi altro task.

La validazione con augmentation solleva un errore per i task obb e pose.

train

train è definito per famiglia, quindi i suoi argomenti cambiano. Due comportamenti sono comuni, perché la classe base fa da wrapper al train di ogni famiglia:

• cfg= accetta un percorso YAML le cui chiavi vengono unite alla chiamata. Gli argomenti keyword espliciti vincono sul file.
• pretrained=False su una famiglia del gruppo di copertura g0 o g1 reinizializza il modello da zero prima dell'addestramento, e non può essere combinato con resume=True.

Quali parametri di augmentation una famiglia rispetti davvero è una questione che varia da famiglia a famiglia; vedi la matrice della data augmentation.

export

model.export(format="onnx", **kwargs) -> str

Restituisce il percorso dell'artefatto scritto. format viene risolto tramite il registro degli exporter, dove engine è un alias di tensorrt e litert è un alias di tflite. Argomenti condivisi da tutti gli exporter:

Le combinazioni bloccate sollevano NotImplementedError nel preflight, prima del tracing. Un'opzione che il formato non usa emette l'avviso Unknown <format> export arguments (ignored) e l'esportazione prosegue. La copertura e le sue regole sono nella pagina matrice di esportazione. Quando sono presenti adattatori LoRA attivi, vengono ripiegati nei pesi densi, e quella fusione avviene solo dopo ogni rifiuto della richiesta.

save

model.save(path) -> str

Scrive un checkpoint LibreYOLO con schema v1.0: lo state dict più i metadati descritti nello schema dei checkpoint. Un modello quantizzato porta con sé anche il suo manifest quant, così LibreYOLO(path) ripristina la struttura quantizzata e le scale.

quantize, quant_info e dequantize

model.quantize(    recipe,    calib="coco128.yaml",    samples=128,    batch=8,    algorithm="auto",    keep_high_precision=None,    allow_download_scripts=False,    verbose=True,)

Quantizza in place e restituisce il modello. recipe è uno dei cast fp16 e bf16, le ricette per Conv e Linear int8 e fp8, oppure le ricette solo per Linear w4a16, w4a8, nvfp4, mxfp4 e int2, che le famiglie transformer come RF-DETR supportano. int2 richiede il QAT. calib accetta un percorso data.yaml o il nome di un dataset integrato e legge le immagini solo in avanti; le etichette non vengono mai lette. Passa calib=None per saltare la calibrazione. algorithm è "minmax", "percentile" o "auto".

model.quant_info() restituisce il riepilogo dello stato di quantizzazione, o None per un modello float. model.dequantize() ripristina in place i moduli float mantenendo i pesi master addestrati con la quantizzazione, che è il ponte dal QAT a export(format="onnx", int8=True, data=...).

info e layer

model.info(detailed=False, verbose=True) -> Dict[str, Any]model.get_available_layer_names() -> List[str]model.get_distill_config() -> Dict

info restituisce un dizionario compatibile con JSON e scrive nel log un riepilogo leggibile quando verbose è true. get_available_layer_names elenca i layer che una config di distillazione o di estrazione di feature può nominare.

Grafi CUDA

Disponibili sulle famiglie il cui attributo di classe SUPPORTS_CUDA_GRAPH è true. Il replay è identico bit a bit all'esecuzione eager.

model.capture_graph(imgsz=None, batch=1, dtype=None) -> Nonemodel.cuda_graph_scope(mode=True)          # gestore di contestomodel.graph_info() -> Dict[str, Any]model.release_graphs() -> None

Un grafo catturato è valido solo per la forma esatta con cui è stato catturato, quindi batch e imgsz devono coincidere con la successiva chiamata a predict. capture_graph toglie il costo della cattura dalla prima richiesta. mode accetta True o "on" per catturare al primo utilizzo, "auto" per aspettare che una forma si ripeta, e False per non fare nulla. capture_graph solleva NotImplementedError quando la famiglia non ha aderito e CudaGraphUnavailable quando la cattura fallisce.

Dispositivo e dtype

Gli oggetti Results portano .to(), .cpu(), .cuda() e .numpy(); vedi Tipi di Results. Il modello stesso si sposta passando device= a predict, oppure al momento della costruzione.