API Python

Punti di ingresso

Le factory caricano modelli o configurano client API. Sono separate in base al contratto di chiamata, non all'architettura.

from libreyolo import LibreYOLO, LibreEnsemble # Factory che annusa i pesi, sulle famiglie senza prompt.detector = LibreYOLO("LibreYOLO9t.pt") # Due o più rilevatori dietro un'unica superficie di predizione.ens = LibreEnsemble(["LibreYOLO9t.pt", "LibreYOLO9s.pt"]) # Le altre tre factory richiedono un extra installato:#   pip install 'libreyolo[sam]'        -> from libreyolo import LibreSAM#   pip install 'libreyolo[vlm]'        -> from libreyolo import LibreVLM#   pip install 'libreyolo[openvocab]'  -> from libreyolo import LibreOpenVocabprint(type(detector).__name__, ens.fusion)

LibreYOLO accetta file di checkpoint e artefatti esportati. Le altre factory accettano alias di modelli; LibreVLM e LibreVLA ricaricano anche le proprie directory di checkpoint salvate, e LibreGen carica una directory di modello locale nel formato upstream di una famiglia supportata.

LibreYOLO(    model_path: str,    size: str | None = None,    reg_max: int = 16,    nb_classes: int | None = None,    device: str = "auto",    task: str | None = None,    compute_units: str = "all",)

model_path accetta un checkpoint .pt, un file ONNX .onnx, un ExecuTorch .pte, un MNN .mnn, un TensorRT .engine, una directory OpenVINO, Paddle o ncnn, oppure l'URL HTTP o HTTPS di un modello su Triton. size e nb_classes vengono letti dal checkpoint quando sono omessi. compute_units viene letto solo per i caricamenti di un CoreML .mlpackage ed è uno tra all, cpu_only, cpu_and_gpu, cpu_and_ne. task accetta qualsiasi nome canonico di task da libreyolo.tasks.TASKS.

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreYOLO9t.pt") # Una sorgente con una sola immagine restituisce un Results; una lista# o una directory ne restituiscono una lista.result = model(SAMPLE_IMAGE) print(result.boxes.xyxy)print(result.names)

from libreyolo import LibreYOLO9, SAMPLE_IMAGE model = LibreYOLO9("LibreYOLO9t.pt", size="t")result = model(SAMPLE_IMAGE) print(len(result))

LibreGround associa istruzioni a punti dell'immagine; LibreVLA predice blocchi di azioni robotiche; LibreLLM chiama un endpoint remoto compatibile di un modello linguistico. Vedi API di grounding, API delle policy e client per modelli linguistici.

LibreYOLO("hf://owner/repo@revision/filename") carica checkpoint dall'Hub. model.push_to_hub(repo_id, private=False) pubblica un checkpoint e una model card. Il riferimento Hub definisce risoluzione e autenticazione.

Classi di famiglia

Ogni famiglia che la factory può restituire è esportata anche per nome, così si può costruire una classe direttamente quando il checkpoint è noto in anticipo. I costruttori seguono BaseModel.__init__:

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

I valori predefiniti del costruttore variano per famiglia; controlla la firma prima di costruirlo direttamente. YOLO9 e le sue varianti inseriscono reg_max: int = 16 dopo size.

Famiglie di rilevamento e multi-task: LibreYOLO9, LibreYOLO9E2E, LibreYOLO9P2, LibreYOLONAS, LibreYOLOX, LibreYOLO7, LibreYOLO4, LibreYOLO3, LibreYOLO2, LibreYOLO1, LibreRTDETR, LibreRTDETRv2, LibreRTDETRv4, LibreRFDETR, LibreDFINE, LibreDOMEDETR, LibreDEIM, LibreDEIMv2, LibreDETR, LibreDeformableDETR, LibreDINODETR, LibreLWDETR, LibreMaskRCNN, LibreFCOS, LibreFasterRCNN, LibreRetinaNet, LibreSSD, LibreCenterNet, LibreEfficientDet, LibreEC, LibreGTR, LibreTinyFormer, LibrePICODET, LibrePPYOLOE, LibreRTMDet, LibreFOMO.

Famiglie di predizione densa: LibreMiDaS, LibreDepthAnythingV2, LibreDepthAnything3, LibreZipDepth, LibreMoGe2, LibreTEED, LibreDexiNed, LibreNAFNet, LibreRealESRGAN, LibreSwinIR, LibreBiRefNet, LibreFeyNobg, LibreFCN, LibreEoMT, LibreDeepLabv3, LibrePIDNet, LibrePPLiteSeg, LibreUNet, LibreSegformer, LibreLingBotVision, LibreMarigoldV2, LibreDDColor, LibreHVICIDNet, LibreLaMa, LibreQuickSRNet, LibreBEN2, LibreViTMatte.

Famiglie di classificazione ed embedding: LibreViT, LibreMobileNetV4, LibreConvNeXt, LibreDeiT, LibreSwin, LibreEfficientNetV2, LibreVGG, LibreResNet, LibreAlexNet, LibreCLIP, LibreSigLIP2, LibreDINOv2, LibreConvNeXtV2, LibrePE, LibreVJEPA2, LibreLeVJEPA.

Altri task: LibreHRNet e LibreDEKR (pose), LibreL2CS (gaze), LibrePPOCR (ocr), LibreFaceEmbedder (embed), e i detector 3D LibreFCOS3D, LibreDetAny3D, LibreWildDet3D e Libre3DMOOD (detect3d).

Anche i tier gemelli esportano le loro classi di famiglia: LibreSAM1, LibreSAM2, LibreSAM3, LibreEdgeTAM, LibreMobileSAM, LibrePicoSAM3; LibreGroundingDINO, LibreOWLv2, LibreOMDetTurbo; LibreLFM2VL, LibreQwen3VL, LibreSmolVLM2, LibreInternVL3, LibreFlorence2, LibreKosmos2, LibreLocateAnything, LibreGemma4, LibreMoondream, LibreMolmo2, LibreNorthMicroVision, LibreMODUS (scritto anche LibreModus), LibreWeVisOneVL; LibreShowUI, LibreGroundFlorence2 e LibreGroundQwen3VL dietro LibreGround; LibreSmolVLA, LibreACT e LibreDiffusionPolicy dietro LibreVLA; LibreFlux2Klein, LibreSanaSprint e LibreSperidlabsIdol dietro LibreGen.

Superficie di predizione

Chiamare un modello esegue l'inferenza. predict è un alias di __call__, quindi i due sono intercambiabili.

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. Gli altri metodi dell'oggetto modello sono documentati nella pagina dell'API del modello.

agnostic_nms=True esegue la NMS agnostica rispetto alla classe: tra i box che si sovrappongono oltre iou, viene mantenuto solo quello con il punteggio più alto, qualunque sia la classe. Agisce sui rilevamenti finiti della famiglia, dopo il filtro classes, e copre i task detect, segment, pose e OBB, con l'IoU ruotato per i box orientati. Su qualsiasi altro task solleva ValueError.

Payload di Results

Results e le sue classi di payload sono esportati a livello di pacchetto: Results, Boxes, Masks, Keypoints, Points, Probs, OBB, Gaze, SemanticMask, PanopticSegmentation, DepthMap, EdgeMap, NormalMap, RestoredImage, Matte, Meshes, OCRRegions, Embeddings, Identities. Ognuna è descritta nei tipi di Results.

Boxes3D, AlbedoMap e Actions aggiungono cuboidi 3D, albedo intrinseca e blocchi di azioni. Vedi tipi di risultato.

GeneratedImage e Gaussians portano l'output di LibreGen: un'immagine generata in Results.generated e un oggetto 3D generato in Results.gaussians.

Backend

Gli artefatti esportati si caricano attraverso LibreYOLO() in base al suffisso del file, quindi le classi di backend si costruiscono raramente a mano. Sono esportate per i casi in cui un backend va selezionato esplicitamente: OnnxBackend, OpenVINOBackend, PaddleBackend, TensorRTBackend, TritonBackend, NcnnBackend, CoreMLBackend, più create_triton_config. BaseExporter è il registro degli exporter dietro model.export().

Validatori

model.val() smista verso il validatore giusto in base al task, quindi questi sono esportati per l'uso diretto e per essere estesi tramite sottoclassi: DetectionValidator, SegmentationValidator, PoseValidator, SemanticValidator, PanopticValidator, DepthValidator, NormalValidator, EdgeValidator, e il ValidationConfig condiviso.

Tracking

model.track() seleziona un tracker per nome. Anche le classi dei tracker e le loro dataclass di configurazione sono esportate: ByteTracker con TrackConfig, BoTSortTracker con BoTSortConfig e OCSortTracker con OCSortConfig.

libreyolo.tracking.Tracker definisce reset() e update(results, image=None) per istanze di tracker personalizzate.

Utility per i dati

DATASETS_DIR è la radice risolta dei dataset, load_data_config legge un YAML di dataset e check_dataset ne convalida uno. I loader specifici per task elencati in Formati dei dataset stanno in libreyolo.data e non a livello di pacchetto.

Gallery e distillazione

Gallery e FaceGallery conservano i vettori di identità registrati per il task embed e producono il payload Identities. Distiller e get_distill_config guidano l'addestramento teacher-student.

libreyolo.training.TrainFitnessCallback definisce fitness(metrics) per la selezione personalizzata dei checkpoint. Vedi callback di fitness.

Asset

SAMPLE_IMAGE è un percorso assoluto a un'immagine inclusa nel pacchetto, così ogni snippet di questa documentazione gira senza dover prima scaricare una foto.

Import lazy e classi rinominate

La maggior parte dei nomi dei tier gemelli, i backend, i validatori e le utility per i dati si risolvono attraverso il __getattr__ a livello di modulo, quindi importare libreyolo non importa le loro dipendenze. L'import fallisce comunque con un messaggio chiaro quando manca l'extra richiesto.

Due nomi di classe sono stati rinominati e la vecchia grafia si risolve ancora, con un DeprecationWarning: LibreYOLORTDETR ora è LibreRTDETR, e LibreYOLORFDETR ora è LibreRFDETR.