Python API

Публічний Python API LibreYOLO визначає список __all__ у libreyolo/__init__.py. Експорт на рівні пакета використовує from libreyolo import <name>; протоколи відстеження й навчання нижче використовують свої іменовані підмодулі.

Точки входу

Фабрики завантажують моделі або налаштовують клієнти API. Вони розділені за контрактом виклику, а не за архітектурою.

Фабрика	Завантажує	Підказка під час виклику	Потрібний додатковий пакет
`LibreYOLO`	Сімейства без підказок через аналіз контрольної точки або суфікса файла
`LibreSAM`	Сегментатори з підказками за псевдонімом розміру	Точки, рамки або текст концепції	`sam`
`LibreVLM`	Генеративні візуально-мовні детектори за псевдонімом	Словник класів або довільна підказка	`vlm`
`LibreOpenVocab`	Текстово-керовані детектори за псевдонімом	Словник класів	`openvocab`
`LibreGen`	Генеративні моделі за псевдонімом або локальним каталогом моделі	Текстовий запит (текст у зображення) або зображення (зображення в 3D)	`gen`
`LibreEnsemble`	Два або більше детекторів, злитих в одну поверхню

П'ять точок входу

from libreyolo import LibreYOLO, LibreEnsemble # Фабрика визначає сімейство без підказок за вагами.detector = LibreYOLO("LibreYOLO9t.pt") # Два або більше детекторів за однією поверхнею передбачення.ens = LibreEnsemble(["LibreYOLO9t.pt", "LibreYOLO9s.pt"]) # Для інших трьох фабрик потрібно встановити додатковий пакет:#   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 приймає файли контрольних точок і експортовані артефакти. Споріднені фабрики приймають псевдоніми моделей; LibreVLM і LibreVLA також повторно завантажують власні збережені каталоги контрольних точок, а LibreGen завантажує локальний каталог моделі у форматі першоджерела підтримуваного сімейства.

python

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 приймає контрольну точку .pt, файл ONNX .onnx, ExecuTorch .pte, MNN .mnn, TensorRT .engine, каталог OpenVINO, Paddle чи ncnn або URL моделі Triton HTTP чи HTTPS. Якщо size і nb_classes не задано, вони зчитуються з контрольної точки. compute_units зчитується лише для завантаження CoreML .mlpackage і має одне зі значень all, cpu_only, cpu_and_gpu, cpu_and_ne. task приймає будь-яку канонічну назву завдання з libreyolo.tasks.TASKS.

Завантаження будь-чого через одну фабрику

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreYOLO9t.pt") # Джерело з одним зображенням повертає один Results; список або каталог# повертає список таких об'єктів.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 відображає інструкції на точки зображення; LibreVLA передбачає фрагменти дій робота; LibreLLM викликає сумісну віддалену кінцеву точку мовної моделі. Див. API прив'язки, API політик і клієнт мовної моделі.

LibreYOLO("hf://owner/repo@revision/filename") завантажує контрольні точки Hub. model.push_to_hub(repo_id, private=False) публікує контрольну точку й картку. Довідка Hub визначає пошук і автентифікацію.

Класи сімейств

Кожне сімейство, яке може повернути фабрика, також експортується за назвою, тому клас можна створити безпосередньо, якщо контрольна точка відома заздалегідь. Конструктори відповідають BaseModel.__init__:

python

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

Типові значення конструктора залежать від сімейства; перевірте його сигнатуру перед безпосереднім створенням. YOLO9 та її варіанти вставляють reg_max: int = 16 після size.

Сімейства виявлення та багатозадачні сімейства: 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.

Сімейства щільного передбачення: 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.

Сімейства класифікації та ембедінгів: LibreViT, LibreMobileNetV4, LibreConvNeXt, LibreDeiT, LibreSwin, LibreEfficientNetV2, LibreVGG, LibreResNet, LibreAlexNet, LibreCLIP, LibreSigLIP2, LibreDINOv2, LibreConvNeXtV2, LibrePE, LibreVJEPA2, LibreLeVJEPA.

Інші завдання: LibreHRNet і LibreDEKR (поза), LibreL2CS (погляд), LibrePPOCR (ocr), LibreFaceEmbedder (embed), а також 3D-детектори LibreFCOS3D, LibreDetAny3D, LibreWildDet3D і Libre3DMOOD (detect3d).

Суміжні рівні також експортують свої класи сімейств: LibreSAM1, LibreSAM2, LibreSAM3, LibreEdgeTAM, LibreMobileSAM, LibrePicoSAM3; LibreGroundingDINO, LibreOWLv2, LibreOMDetTurbo; LibreLFM2VL, LibreQwen3VL, LibreSmolVLM2, LibreInternVL3, LibreFlorence2, LibreKosmos2, LibreLocateAnything, LibreGemma4, LibreMoondream, LibreMolmo2, LibreNorthMicroVision, LibreMODUS (також пишеться LibreModus), LibreWeVisOneVL; LibreShowUI, LibreGroundFlorence2 і LibreGroundQwen3VL через LibreGround; LibreSmolVLA, LibreACT і LibreDiffusionPolicy через LibreVLA; LibreFlux2Klein, LibreSanaSprint і LibreSperidlabsIdol через LibreGen.

Поверхня передбачення

Виклик моделі запускає інференс. predict є псевдонімом __call__, тому вони взаємозамінні.

python

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

Джерело з одним зображенням повертає один Results. Список, кортеж або каталог повертає список таких об'єктів, а stream=True повертає генератор. Інші методи об'єкта моделі документовано на сторінці API моделі.

agnostic_nms=True запускає NMS без урахування класів: з рамок, що перекриваються понад iou, лишається тільки та, що має найвищу оцінку, незалежно від їхніх класів. Він працює на готових виявленнях сімейства, після фільтра classes, і охоплює завдання detect, segment, pose та OBB, з повернутим IoU для орієнтованих рамок. На будь-якому іншому завданні він спричиняє ValueError.

Корисні дані Results

Results та його класи корисних даних експортуються на рівні пакета: Results, Boxes, Masks, Keypoints, Points, Probs, OBB, Gaze, SemanticMask, PanopticSegmentation, DepthMap, EdgeMap, NormalMap, RestoredImage, Matte, Meshes, OCRRegions, Embeddings, Identities. Кожен описано в розділі Типи Results.

Boxes3D, AlbedoMap і Actions додають кубоїди 3D, власне альбедо й фрагменти дій. Див. типи результатів.

GeneratedImage і Gaussians несуть вихід LibreGen: згенероване зображення в Results.generated і згенерований 3D-об'єкт у Results.gaussians.

Бекенди

Експортовані артефакти завантажуються через LibreYOLO() за суфіксом файла, тому класи бекендів рідко створюються вручну. Їх експортовано для випадків, коли бекенд потрібно вибрати явно: OnnxBackend, OpenVINOBackend, PaddleBackend, TensorRTBackend, TritonBackend, NcnnBackend, CoreMLBackend, а також create_triton_config. BaseExporter є реєстром експортерів, що стоїть за model.export().

Валідатори

model.val() спрямовує виклик до правильного валідатора за завданням, тому наведені класи експортуються для безпосереднього використання й створення підкласів: DetectionValidator, SegmentationValidator, PoseValidator, SemanticValidator, PanopticValidator, DepthValidator, NormalValidator, EdgeValidator і спільний ValidationConfig.

Відстеження

model.track() вибирає трекер за назвою. Класи трекерів і їхні dataclass конфігурації також експортуються: ByteTracker із TrackConfig, BoTSortTracker із BoTSortConfig та OCSortTracker із OCSortConfig.

libreyolo.tracking.Tracker визначає reset() і update(results, image=None) для власних екземплярів трекерів.

Допоміжні засоби для даних

DATASETS_DIR є визначеним коренем датасетів, load_data_config зчитує YAML датасету, а check_dataset перевіряє його. Завантажувачі окремих завдань, названі в Форматах датасетів, розташовані в libreyolo.data, а не на рівні пакета.

Галереї та дистиляція

Gallery і FaceGallery зберігають зареєстровані вектори ідентичностей для завдання embed і створюють корисні дані Identities. Distiller і get_distill_config керують навчанням учитель-учень.

libreyolo.training.TrainFitnessCallback визначає fitness(metrics) для власного вибору контрольних точок. Див. колбеки оцінки якості.

Ресурси

SAMPLE_IMAGE є абсолютним шляхом до зображення, включеного до пакета, тому кожен фрагмент цієї документації запускається без попереднього завантаження зображення.

Ліниві імпорти та перейменовані класи

Більшість назв суміжних рівнів, бекенди, валідатори та допоміжні засоби для даних визначаються через __getattr__ на рівні модуля, тому імпорт libreyolo не імпортує їхні залежності. Якщо потрібного додаткового пакета немає, імпорт усе одно завершується зрозумілим повідомленням.

Два класи перейменовано, а старий варіант написання досі визначається з DeprecationWarning: LibreYOLORTDETR тепер має назву LibreRTDETR, а LibreYOLORFDETR тепер має назву LibreRFDETR.