API моделі

Створення

Фабрика повертає екземпляр класу сімейства. Безпосереднє створення цього класу приймає ті самі аргументи, крім обов'язкового size:

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

device="auto" вибирає доступну CUDA, потім MPS, а потім CPU. Ціле число або рядок із цифр зчитується як порядковий номер CUDA, тому device=0 і device="0" обидва означають cuda:0. task перевіряється за SUPPORTED_TASKS сімейства. Передавання model_path=None створює архітектуру й залишає її в режимі навчання; передавання dict безпосередньо завантажує цей словник стану.

predict і __call__

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 у кожному випадку повертає генератор.

Джерела потоків наживо необмежені й потребують stream=True. tiling і augment не можна поєднувати. Аугментація під час тестування спричиняє помилку для завдань embed, point та edge.

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreYOLO9t.pt") model.info()result = model(SAMPLE_IMAGE, conf=0.25, iou=0.45) print(result.boxes.xyxy)print(result.speed)

За batch > 1 сімейства з істинним SUPPORTS_BATCHED_PREDICT виконують один прямий прохід складеного тензора на групу; batch=1 зберігає один прямий прохід на зображення.

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreYOLO9t.pt") # stream=True повертає генератор з одним Results на кадр або зображення.for result in model([SAMPLE_IMAGE, SAMPLE_IMAGE], stream=True):    print(len(result))

embed

model.embed(source=None, **kwargs) -> torch.Tensor

Зручна обгортка над predict, яка складає всі рядки ембедінгів в один тензор (N_total, D). Модель має бути створена з task="embed", інакше виникає NotImplementedError.

track

model.track(    source,    *,    track_conf=0.25,    conf=None,    iou=0.45,    imgsz=None,    classes=None,    max_det=300,    save=False,    show=False,    vid_stride=1,    fps=30.0,    color_format="auto",    output_path=None,    tracker="bytetrack",    tracker_config=None,    augment=False,    persist=False,    **tracker_kwargs,) -> Generator[Results, None, None]

Повертає по одному Results на кадр з установленим track_id. Значення tracker є одним із "bytetrack", "botsort", "ocsort" або "deepocsort", за потреби із суфіксом .yaml, або власним екземпляром трекера, та ігнорується за наявності tracker_config, оскільки тип конфігурації вибирає трекер. track_conf зіставляється з track_high_thresh для ByteTrack і BoT-SORT та з det_thresh для OC-SORT і Deep OC-SORT. conf, якщо задано, є порогом виявлення, як у predict(). persist=True зберігає трекер із попереднього виклику для покадрових циклів. Типове значення output_path дорівнює runs/track/<video_stem>.mp4.

val

model.val(    data=None,    batch=16,    imgsz=None,    conf=0.001,    iou=0.6,    workers=4,    allow_download_scripts=False,    device=None,    split="val",    augment=False,    save_json=False,    verbose=True,    *,    plots=None,    project=None,    name=None,    exist_ok=False,    **kwargs,) -> Dict

Повертає словник метрик, ключі якого залежать від завдання; виявлення повертає metrics/precision, metrics/recall, metrics/mAP50 і metrics/mAP50-95. imgsz приймає квадратне ціле число або кортеж (height, width) і типово дорівнює рідному розміру вхідних даних моделі. data=None валідує на датасеті, збереженому в конфігурації навчання контрольної точки, і спричиняє помилку, якщо його немає, як в опублікованих вагах. project, name і exist_ok задають каталог виводу як project/name, зі збільшуваним номером, якщо не задано exist_ok=True. plots є псевдонімом save_plots. allow_download_scripts контролює вбудований Python, який YAML датасету може містити в полі download.

Для detect і segment словник є підкласом dict, який також несе box (метрики для кожного зображення та криві точності, повноти й F1 для кожного класу) і confusion_matrix; для classify він несе top1, top5 і confusion_matrix. Див. Валідація та метрики.

faster_coco_eval приймається через **kwargs і типово дорівнює True, а за відсутності пакета використовується резервний pycocotools. Використаний бекенд повідомляється в model.last_eval_backend.

agnostic_nms=True, також через **kwargs, застосовує NMS без урахування класів із порогом iou перед оцінюванням. Він охоплює detect і segment та спричиняє ValueError для будь-якого іншого завдання.

Аугментована валідація спричиняє помилку для завдань obb і pose.

train

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

• cfg= приймає шлях YAML, ключі якого об'єднуються з викликом. Явні іменовані аргументи мають перевагу над файлом.
• pretrained=False для сімейства в групі покриття g0 або g1 повторно ініціалізує модель з нуля перед навчанням і не може поєднуватися з resume=True.

Параметри аугментації, які справді враховує сімейство, залежать від нього; дивіться матрицю аугментацій.

export

model.export(format="onnx", **kwargs) -> str

Повертає шлях до записаного артефакту. format визначається через реєстр експортерів, де engine є псевдонімом tensorrt, а litert є псевдонімом tflite. Аргументи, спільні для кожного експортера:

Заблоковані поєднання спричиняють NotImplementedError під час попередньої перевірки до трасування. Опція, яку формат не використовує, спричиняє попередження Unknown <format> export arguments (ignored), і експорт продовжується. Покриття та його правила наведено на сторінці матриці експорту. Якщо наявні активні адаптери LoRA, вони зливаються в щільні ваги, і це відбувається лише після всіх перевірок відхилення запиту.

save

model.save(path) -> str

Записує контрольну точку LibreYOLO за схемою v1.0: словник стану разом із метаданими, описаними в схемі контрольної точки. Квантована модель додатково містить маніфест quant, тому LibreYOLO(path) відновлює квантовану структуру й масштаби.

quantize, quant_info і dequantize

model.quantize(    recipe,    calib="coco128.yaml",    samples=128,    batch=8,    algorithm="auto",    keep_high_precision=None,    allow_download_scripts=False,    verbose=True,)

Квантує на місці й повертає модель. recipe є одним із перетворень fp16 і bf16, рецептів Conv та Linear int8 і fp8 або рецептів лише для Linear w4a16, w4a8, nvfp4, mxfp4 та int2, які підтримують трансформерні сімейства на кшталт RF-DETR. Для int2 потрібне QAT. calib приймає шлях data.yaml або назву вбудованого датасету й зчитує зображення лише в прямому напрямку; мітки ніколи не зчитуються. Передайте calib=None, щоб пропустити калібрування. algorithm має значення "minmax", "percentile" або "auto".

model.quant_info() повертає підсумок стану квантування або None для моделі з рухомою комою. model.dequantize() відновлює модулі з рухомою комою на місці, зберігаючи основні ваги, навчені з квантуванням. Це міст від QAT до export(format="onnx", int8=True, data=...).

info та layers

model.info(detailed=False, verbose=True) -> Dict[str, Any]model.get_available_layer_names() -> List[str]model.get_distill_config() -> Dict

info повертає словник, придатний для JSON, і записує зрозумілий користувачу підсумок, коли verbose істинний. get_available_layer_names перелічує шари, які може називати конфігурація дистиляції чи видобування ознак.

Графи CUDA

Доступні для сімейств, у яких атрибут класу SUPPORTS_CUDA_GRAPH істинний. Повторне виконання побітово ідентичне негайному виконанню.

model.capture_graph(imgsz=None, batch=1, dtype=None) -> Nonemodel.cuda_graph_scope(mode=True)          # context managermodel.graph_info() -> Dict[str, Any]model.release_graphs() -> None

Захоплений граф дійсний лише для точної форми захоплення, тому batch і imgsz мають збігатися з подальшим викликом predict. capture_graph переносить витрати захоплення за межі першого запиту. mode приймає True або "on" для захоплення під час першого використання, "auto" для очікування повторення форми й False для відсутності дії. capture_graph спричиняє NotImplementedError, коли сімейство не заявило підтримку, і CudaGraphUnavailable, коли захоплення не вдається.

Пристрій і dtype

Об'єкти Results мають .to(), .cpu(), .cuda() і .numpy(); дивіться Типи Results. Сама модель переміщується через передавання device= до predict або під час створення.