Python API

Точки входа

Фабрики загружают модели или настраивают API-клиенты. Они разделены по контракту вызова, а не по архитектуре.

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

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, а также HTTP- или HTTPS-URL модели в Triton. Если 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 привязки к изображению, API политик и клиент языковой модели.

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

Классы семейств

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

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 (pose), LibreL2CS (gaze), 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__, так что они взаимозаменяемы.

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, и охватывает задачи детекции, сегментации, позы и 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) для собственного выбора чекпойнтов. См. колбэки fitness.

Ресурсы

SAMPLE_IMAGE — абсолютный путь к изображению, которое поставляется вместе с пакетом, поэтому любой пример кода в этой документации запускается без предварительного скачивания картинки.

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

Большинство имён родственных уровней, бэкенды, валидаторы и вспомогательные функции для данных разрешаются через __getattr__ на уровне модуля, поэтому импорт libreyolo не тянет за собой их зависимости. Если нужный extra не установлен, импорт всё равно падает с понятным сообщением.

Два класса переименовали, и старое написание всё ещё разрешается — с DeprecationWarning: LibreYOLORTDETR теперь LibreRTDETR, а LibreYOLORFDETR теперь LibreRFDETR.