API Pythona

Punkty wejścia

Fabryki wczytują modele lub konfigurują klientów API. Rozdziela je kontrakt wywołania, nie architektura.

from libreyolo import LibreYOLO, LibreEnsemble # Fabryka rodzin bez podpowiedzi, rozpoznająca typ po wagach.detector = LibreYOLO("LibreYOLO9t.pt") # Co najmniej dwa detektory za jednym interfejsem predykcji.ens = LibreEnsemble(["LibreYOLO9t.pt", "LibreYOLO9s.pt"]) # Pozostałe trzy fabryki wymagają zainstalowania dodatku:#   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 przyjmuje pliki checkpointów i wyeksportowane artefakty. Pozostałe fabryki przyjmują aliasy modeli; LibreVLM i LibreVLA wczytują też własne zapisane katalogi checkpointów, a LibreGen wczytuje lokalny katalog modelu w formacie nadrzędnym obsługiwanej rodziny.

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 przyjmuje checkpoint .pt, plik ONNX .onnx, ExecuTorch .pte, MNN .mnn, TensorRT .engine, katalog OpenVINO, Paddle lub ncnn albo adres URL modelu Triton przez HTTP lub HTTPS. W razie pominięcia size i nb_classes są odczytywane z checkpointu. compute_units jest odczytywane tylko przy wczytywaniu .mlpackage CoreML i przyjmuje all, cpu_only, cpu_and_gpu lub cpu_and_ne. task przyjmuje dowolną kanoniczną nazwę zadania z libreyolo.tasks.TASKS.

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreYOLO9t.pt") # Pojedyncze źródło obrazu zwraca jeden obiekt Results, a lista lub katalog# zwraca ich listę.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 mapuje instrukcje na punkty obrazu; LibreVLA przewiduje fragmenty akcji robota; LibreLLM wywołuje zgodny zdalny punkt końcowy modelu językowego. Zobacz API wskazywania, API polityk i klienta modelu językowego.

LibreYOLO("hf://owner/repo@revision/filename") wczytuje checkpointy z Hub. model.push_to_hub(repo_id, private=False) publikuje checkpoint i kartę modelu. Dokumentacja Hub definiuje rozwiązywanie odwołań i uwierzytelnianie.

Klasy rodzin

Każda rodzina, którą może zwrócić fabryka, jest również eksportowana według nazwy. Klasę można więc utworzyć bezpośrednio, gdy checkpoint jest znany z wyprzedzeniem. Konstruktory są zgodne z BaseModel.__init__:

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

Wartości domyślne konstruktorów zależą od rodziny; przed bezpośrednim utworzeniem należy sprawdzić sygnaturę. YOLO9 i jego warianty wstawiają reg_max: int = 16 po size.

Rodziny detekcyjne i wielozadaniowe: 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.

Rodziny gęstej predykcji: 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.

Rodziny klasyfikacji i embeddingów: LibreViT, LibreMobileNetV4, LibreConvNeXt, LibreDeiT, LibreSwin, LibreEfficientNetV2, LibreVGG, LibreResNet, LibreAlexNet, LibreCLIP, LibreSigLIP2, LibreDINOv2, LibreConvNeXtV2, LibrePE, LibreVJEPA2, LibreLeVJEPA.

Inne zadania: LibreHRNet i LibreDEKR (pose), LibreL2CS (gaze), LibrePPOCR (ocr), LibreFaceEmbedder (embed) oraz detektory 3D LibreFCOS3D, LibreDetAny3D, LibreWildDet3D i Libre3DMOOD (detect3d).

Sąsiednie poziomy również eksportują klasy rodzin: LibreSAM1, LibreSAM2, LibreSAM3, LibreEdgeTAM, LibreMobileSAM, LibrePicoSAM3; LibreGroundingDINO, LibreOWLv2, LibreOMDetTurbo; LibreLFM2VL, LibreQwen3VL, LibreSmolVLM2, LibreInternVL3, LibreFlorence2, LibreKosmos2, LibreLocateAnything, LibreGemma4, LibreMoondream, LibreMolmo2, LibreNorthMicroVision, LibreMODUS (również zapisywane jako LibreModus), LibreWeVisOneVL; LibreShowUI, LibreGroundFlorence2 i LibreGroundQwen3VL za fabryką LibreGround; LibreSmolVLA, LibreACT i LibreDiffusionPolicy za fabryką LibreVLA; LibreFlux2Klein, LibreSanaSprint i LibreSperidlabsIdol za fabryką LibreGen.

Interfejs predykcji

Wywołanie modelu uruchamia inferencję. predict jest aliasem __call__, więc można używać ich zamiennie.

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

Pojedyncze źródło obrazu zwraca jeden Results. Lista, krotka lub katalog zwraca ich listę, a stream=True zwraca generator. Pozostałe metody obiektu modelu opisano na stronie API modelu.

agnostic_nms=True uruchamia NMS niezależne od klas: spośród ramek nakładających się powyżej iou zostaje tylko ta z najwyższym wynikiem, bez względu na ich klasy. Działa na gotowych detekcjach rodziny, po filtrze classes, i obejmuje zadania detekcji, segmentacji, pozy i OBB, z obróconym IoU dla obróconych ramek. Dla każdego innego zadania zgłasza ValueError.

Dane wyników

Results i jego klasy danych są eksportowane na poziomie pakietu: Results, Boxes, Masks, Keypoints, Points, Probs, OBB, Gaze, SemanticMask, PanopticSegmentation, DepthMap, EdgeMap, NormalMap, RestoredImage, Matte, Meshes, OCRRegions, Embeddings, Identities. Każdą opisano w sekcji typów Results.

Boxes3D, AlbedoMap i Actions dodają prostopadłościany 3D, wewnętrzne albedo i fragmenty akcji. Zobacz typy wyników.

GeneratedImage i Gaussians niosą wynik LibreGen: wygenerowany obraz w Results.generated i wygenerowany obiekt 3D w Results.gaussians.

Backendy

Wyeksportowane artefakty są wczytywane przez LibreYOLO() według sufiksu pliku, dlatego klasy backendów rzadko tworzy się ręcznie. Są eksportowane na potrzeby sytuacji, w których backend trzeba wybrać jawnie: OnnxBackend, OpenVINOBackend, PaddleBackend, TensorRTBackend, TritonBackend, NcnnBackend, CoreMLBackend oraz create_triton_config. BaseExporter jest rejestrem eksporterów stojącym za model.export().

Walidatory

model.val() kieruje wywołanie do odpowiedniego walidatora według zadania, dlatego poniższe klasy są eksportowane do bezpośredniego użycia i tworzenia podklas: DetectionValidator, SegmentationValidator, PoseValidator, SemanticValidator, PanopticValidator, DepthValidator, NormalValidator, EdgeValidator oraz wspólna ValidationConfig.

Śledzenie

model.track() wybiera tracker według nazwy. Eksportowane są również klasy trackerów i dataclasses ich konfiguracji: ByteTracker z TrackConfig, BoTSortTracker z BoTSortConfig oraz OCSortTracker z OCSortConfig.

libreyolo.tracking.Tracker definiuje reset() i update(results, image=None) dla własnych instancji trackera.

Funkcje pomocnicze danych

DATASETS_DIR jest rozwiązaną ścieżką główną zbiorów danych, load_data_config odczytuje plik YAML zbioru danych, a check_dataset go waliduje. Loadery właściwe dla zadań, wymienione na stronie formatów zbiorów danych, znajdują się w libreyolo.data, a nie na poziomie pakietu.

Galerie i destylacja

Gallery i FaceGallery przechowują zarejestrowane wektory tożsamości dla zadania embed i tworzą dane Identities. Distiller i get_distill_config sterują trenowaniem nauczyciel-uczeń.

libreyolo.training.TrainFitnessCallback definiuje fitness(metrics) do własnego wyboru checkpointów. Zobacz callbacki fitness.

Zasoby

SAMPLE_IMAGE jest bezwzględną ścieżką obrazu dołączonego do pakietu, dzięki czemu każdy fragment kodu w tej dokumentacji działa bez wcześniejszego pobierania obrazu.

Leniwe importy i klasy o zmienionych nazwach

Większość nazw sąsiednich poziomów, backendy, walidatory i funkcje pomocnicze danych są rozwiązywane przez __getattr__ na poziomie modułu, dzięki czemu import libreyolo nie importuje ich zależności. Import nadal kończy się czytelnym komunikatem, gdy brakuje wymaganego dodatku.

Nazwy dwóch klas zmieniono, a stara pisownia nadal jest rozwiązywana z DeprecationWarning: LibreYOLORTDETR to obecnie LibreRTDETR, a LibreYOLORFDETR to obecnie LibreRFDETR.