Python-API

Einstiegspunkte

Factories laden Modelle oder konfigurieren API-Clients. Sie sind nach Aufrufvertrag und nicht nach Architektur getrennt.

from libreyolo import LibreYOLO, LibreEnsemble # Factory mit Gewichtserkennung für promptlose Familien.detector = LibreYOLO("LibreYOLO9t.pt") # Zwei oder mehr Detektoren hinter einer Vorhersageschnittstelle.ens = LibreEnsemble(["LibreYOLO9t.pt", "LibreYOLO9s.pt"]) # Die drei anderen Factories benötigen ein installiertes Extra:#   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 akzeptiert Checkpoint-Dateien und exportierte Artefakte. Die verwandten Factories akzeptieren Modell-Aliasse; LibreVLM und LibreVLA laden außerdem ihre eigenen gespeicherten Checkpoint-Verzeichnisse, und LibreGen lädt ein lokales Modellverzeichnis im Upstream-Format einer unterstützten Familie.

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 akzeptiert einen .pt-Checkpoint, eine ONNX-Datei .onnx, eine ExecuTorch-Datei .pte, eine MNN-Datei .mnn, eine TensorRT-Datei .engine, ein OpenVINO-, Paddle- oder ncnn-Verzeichnis oder eine Triton-HTTP- oder HTTPS-Modell-URL. Wenn size und nb_classes fehlen, werden sie aus dem Checkpoint gelesen. compute_units wird nur beim Laden eines CoreML- .mlpackage gelesen und akzeptiert all, cpu_only, cpu_and_gpu sowie cpu_and_ne. task nimmt jeden kanonischen Aufgabennamen aus libreyolo.tasks.TASKS entgegen.

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreYOLO9t.pt") # Eine einzelne Bildquelle gibt ein Results zurück, eine Liste oder ein# Verzeichnis dagegen eine Liste solcher Objekte.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 bildet Anweisungen auf Bildpunkte ab; LibreVLA sagt Roboteraktionsblöcke vorher; LibreLLM ruft einen kompatiblen entfernten Sprachmodell-Endpunkt auf. Siehe die Grounding-API, Policy-API und den Sprachmodell-Client.

LibreYOLO("hf://owner/repo@revision/filename") lädt Hub-Checkpoints. model.push_to_hub(repo_id, private=False) veröffentlicht einen Checkpoint und eine Modellkarte. Die Hub-Referenz beschreibt Auflösung und Authentifizierung.

Familienklassen

Jede von der Factory zurückgebbare Familie wird auch unter ihrem Namen exportiert. Wenn der Checkpoint im Voraus bekannt ist, kann die Klasse daher direkt erstellt werden. Die Konstruktoren folgen BaseModel.__init__:

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

Die Standardwerte des Konstruktors hängen von der Modellfamilie ab. Vor einem direkten Aufruf sollte seine Signatur geprüft werden. YOLO9 und seine Varianten fügen reg_max: int = 16 nach size ein.

Erkennungs- und Multi-Task-Familien: 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.

Familien für dichte Vorhersagen: 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.

Klassifikations- und Embedding-Familien: LibreViT, LibreMobileNetV4, LibreConvNeXt, LibreDeiT, LibreSwin, LibreEfficientNetV2, LibreVGG, LibreResNet, LibreAlexNet, LibreCLIP, LibreSigLIP2, LibreDINOv2, LibreConvNeXtV2, LibrePE, LibreVJEPA2, LibreLeVJEPA.

Andere Aufgaben: LibreHRNet und LibreDEKR (Pose), LibreL2CS (Blick), LibrePPOCR (OCR), LibreFaceEmbedder (Embedding) sowie die 3D-Detektoren LibreFCOS3D, LibreDetAny3D, LibreWildDet3D und Libre3DMOOD (3D-Erkennung).

Auch die benachbarten Stufen exportieren ihre Familienklassen: LibreSAM1, LibreSAM2, LibreSAM3, LibreEdgeTAM, LibreMobileSAM, LibrePicoSAM3; LibreGroundingDINO, LibreOWLv2, LibreOMDetTurbo; LibreLFM2VL, LibreQwen3VL, LibreSmolVLM2, LibreInternVL3, LibreFlorence2, LibreKosmos2, LibreLocateAnything, LibreGemma4, LibreMoondream, LibreMolmo2, LibreNorthMicroVision, LibreMODUS (auch LibreModus), LibreWeVisOneVL; LibreShowUI, LibreGroundFlorence2 und LibreGroundQwen3VL hinter LibreGround; LibreSmolVLA, LibreACT und LibreDiffusionPolicy hinter LibreVLA; LibreFlux2Klein, LibreSanaSprint und LibreSperidlabsIdol hinter LibreGen.

Vorhersageschnittstelle

Das Aufrufen eines Modells führt die Inferenz aus. predict ist ein Alias für __call__. Beide sind daher austauschbar.

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,)

Eine einzelne Bildquelle gibt ein Results zurück. Eine Liste, ein Tupel oder ein Verzeichnis gibt eine Liste zurück, und stream=True einen Generator. Die anderen Methoden des Modellobjekts werden auf der Modell-API-Seite beschrieben.

agnostic_nms=True führt klassenunabhängiges NMS aus: Von Boxen, die sich über iou hinaus überlappen, bleibt nur die am höchsten bewertete erhalten, gleich welcher Klasse. Es läuft auf den fertigen Erkennungen der Familie, nach dem classes-Filter, und deckt die Aufgaben detect, segment, pose und OBB ab, mit gedrehter IoU für orientierte Boxen. Bei jeder anderen Aufgabe löst es ValueError aus.

Results-Payloads

Results und seine Payload-Klassen werden auf Paketebene exportiert: Results, Boxes, Masks, Keypoints, Points, Probs, OBB, Gaze, SemanticMask, PanopticSegmentation, DepthMap, EdgeMap, NormalMap, RestoredImage, Matte, Meshes, OCRRegions, Embeddings, Identities. Alle werden unter Results-Typen beschrieben.

Boxes3D, AlbedoMap und Actions ergänzen 3D-Quader, intrinsische Albedo und Aktionsblöcke. Siehe Ergebnistypen.

GeneratedImage und Gaussians tragen die Ausgabe von LibreGen: ein generiertes Bild in Results.generated und ein generiertes 3D-Objekt in Results.gaussians.

Backends

Exportierte Artefakte werden anhand ihres Dateisuffixes über LibreYOLO() geladen. Backend-Klassen müssen daher selten von Hand erstellt werden. Sie werden für Fälle exportiert, in denen ein Backend explizit gewählt werden muss: OnnxBackend, OpenVINOBackend, PaddleBackend, TensorRTBackend, TritonBackend, NcnnBackend, CoreMLBackend sowie create_triton_config. BaseExporter ist das Exporter-Register hinter model.export().

Validatoren

model.val() leitet nach Aufgabe an den passenden Validator weiter. Die folgenden Klassen werden für die direkte Verwendung und Unterklassenbildung exportiert: DetectionValidator, SegmentationValidator, PoseValidator, SemanticValidator, PanopticValidator, DepthValidator, NormalValidator, EdgeValidator und die gemeinsame ValidationConfig.

Tracking

model.track() wählt einen Tracker anhand seines Namens. Trackerklassen und ihre Konfigurations-Dataclasses werden ebenfalls exportiert: ByteTracker mit TrackConfig, BoTSortTracker mit BoTSortConfig und OCSortTracker mit OCSortConfig.

libreyolo.tracking.Tracker definiert reset() und update(results, image=None) für eigene Tracker-Instanzen.

Datenhilfsfunktionen

DATASETS_DIR ist der aufgelöste Datensatzstamm. load_data_config liest eine Datensatz-YAML, und check_dataset validiert sie. Die unter Datensatzformate benannten aufgabenspezifischen Loader liegen in libreyolo.data und nicht auf Paketebene.

Galerien und Distillation

Gallery und FaceGallery halten registrierte Identitätsvektoren für die Aufgabe embed und erzeugen die Payload Identities. Distiller und get_distill_config steuern das Teacher-Student-Training.

libreyolo.training.TrainFitnessCallback definiert fitness(metrics) für die eigene Checkpoint-Auswahl. Siehe Fitness-Callbacks.

Assets

SAMPLE_IMAGE ist ein absoluter Pfad zu einem mit dem Paket ausgelieferten Bild. Jedes Snippet dieser Dokumentation funktioniert daher, ohne zuerst ein Bild herunterzuladen.

Verzögerte Importe und umbenannte Klassen

Die meisten Namen benachbarter Stufen, Backends, Validatoren und Datenhilfsfunktionen werden über __getattr__ auf Modulebene aufgelöst. Beim Import von libreyolo werden ihre Abhängigkeiten daher nicht importiert. Wenn das erforderliche Extra fehlt, scheitert der spätere Import weiterhin mit einer verständlichen Meldung.

Zwei Klassennamen wurden umbenannt. Die alte Schreibweise wird weiterhin mit einem DeprecationWarning aufgelöst: LibreYOLORTDETR heißt jetzt LibreRTDETR, und LibreYOLORFDETR heißt jetzt LibreRFDETR.