Python API

Điểm vào

Factory tải mô hình hoặc cấu hình API client. Chúng được phân chia theo giao ước gọi, không theo kiến trúc.

from libreyolo import LibreYOLO, LibreEnsemble # Factory dò trọng số trên các họ không có prompt.detector = LibreYOLO("LibreYOLO9t.pt") # Hai detector trở lên phía sau một giao diện dự đoán.ens = LibreEnsemble(["LibreYOLO9t.pt", "LibreYOLO9s.pt"]) # Ba factory còn lại cần cài gói bổ sung:#   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 chấp nhận tệp checkpoint và tệp đã xuất. Các factory cùng cấp chấp nhận tên thay thế của mô hình; LibreVLM và LibreVLA còn tải lại thư mục checkpoint do chúng lưu, còn LibreGen tải một thư mục mô hình cục bộ theo định dạng thượng nguồn của một họ được hỗ trợ.

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 nhận checkpoint .pt, file ONNX .onnx, ExecuTorch .pte, MNN .mnn, TensorRT .engine, thư mục OpenVINO, Paddle hoặc ncnn, hay URL mô hình Triton HTTP hoặc HTTPS. size và nb_classes được đọc từ checkpoint khi bỏ qua. compute_units chỉ được đọc khi nạp .mlpackage CoreML và nhận một trong all, cpu_only, cpu_and_gpu, cpu_and_ne. task nhận mọi tên tác vụ chuẩn từ libreyolo.tasks.TASKS.

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreYOLO9t.pt") # Source là một ảnh trả về một Results; danh sách hoặc thư mục# trả về danh sách 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 ánh xạ chỉ dẫn thành điểm trên ảnh; LibreVLA dự đoán đoạn hành động robot; LibreLLM gọi endpoint mô hình ngôn ngữ từ xa tương thích. Xem API grounding, API chính sách và client mô hình ngôn ngữ.

LibreYOLO("hf://owner/repo@revision/filename") tải checkpoint Hub. model.push_to_hub(repo_id, private=False) công bố checkpoint và model card. Tài liệu Hub xác định cách phân giải và xác thực.

Lớp họ

Mọi họ mà factory có thể trả về cũng được export theo tên, vì vậy có thể dựng trực tiếp lớp khi biết trước checkpoint. Constructor tuân theo BaseModel.__init__:

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

Giá trị mặc định của hàm khởi tạo khác nhau theo họ mô hình; kiểm tra chữ ký trước khi khởi tạo trực tiếp. YOLO9 và các biến thể chèn reg_max: int = 16 sau size.

Các họ detection và đa tác vụ: 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.

Các họ dense prediction: 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.

Các họ classification và embedding: LibreViT, LibreMobileNetV4, LibreConvNeXt, LibreDeiT, LibreSwin, LibreEfficientNetV2, LibreVGG, LibreResNet, LibreAlexNet, LibreCLIP, LibreSigLIP2, LibreDINOv2, LibreConvNeXtV2, LibrePE, LibreVJEPA2, LibreLeVJEPA.

Các tác vụ khác: LibreHRNet và LibreDEKR (pose), LibreL2CS (gaze), LibrePPOCR (ocr), LibreFaceEmbedder (embed), cùng các detector 3D LibreFCOS3D, LibreDetAny3D, LibreWildDet3D và Libre3DMOOD (detect3d).

Các cấp sibling cũng export lớp họ: LibreSAM1, LibreSAM2, LibreSAM3, LibreEdgeTAM, LibreMobileSAM, LibrePicoSAM3; LibreGroundingDINO, LibreOWLv2, LibreOMDetTurbo; LibreLFM2VL, LibreQwen3VL, LibreSmolVLM2, LibreInternVL3, LibreFlorence2, LibreKosmos2, LibreLocateAnything, LibreGemma4, LibreMoondream, LibreMolmo2, LibreNorthMicroVision, LibreMODUS (cũng viết là LibreModus), LibreWeVisOneVL; LibreShowUI, LibreGroundFlorence2 và LibreGroundQwen3VL đứng sau LibreGround; LibreSmolVLA, LibreACT và LibreDiffusionPolicy đứng sau LibreVLA; LibreFlux2Klein, LibreSanaSprint và LibreSperidlabsIdol đứng sau LibreGen.

Giao diện dự đoán

Gọi mô hình sẽ chạy inference. predict là alias của __call__, nên hai cách có thể thay thế nhau.

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

Source là một ảnh trả về một Results. Danh sách, tuple hoặc thư mục trả về danh sách, còn stream=True trả về generator. Các phương thức khác trên object mô hình được mô tả tại trang model API.

agnostic_nms=True chạy NMS không phân biệt lớp: trong các box chồng lấn vượt iou, chỉ box có điểm cao nhất được giữ, bất kể lớp của chúng. Nó chạy trên các phát hiện đã hoàn tất của họ, sau bộ lọc classes, và bao phủ các tác vụ detect, segment, pose và OBB, với IoU xoay cho box định hướng. Ở mọi tác vụ khác nó phát sinh ValueError.

Payload Results

Results và các lớp dữ liệu của nó được xuất ở cấp package: Results, Boxes, Masks, Keypoints, Points, Probs, OBB, Gaze, SemanticMask, PanopticSegmentation, DepthMap, EdgeMap, NormalMap, RestoredImage, Matte, Meshes, OCRRegions, Embeddings, Identities. Mỗi lớp được mô tả trong các kiểu Results.

Boxes3D, AlbedoMap và Actions bổ sung khối hộp 3D, albedo nội tại và đoạn hành động. Xem các kiểu kết quả.

GeneratedImage và Gaussians mang đầu ra của LibreGen: một ảnh được sinh ra trong Results.generated và một đối tượng 3D được sinh ra trong Results.gaussians.

Backend

Artifact đã xuất được nạp qua LibreYOLO() theo hậu tố file nên hiếm khi cần dựng thủ công lớp backend. Chúng được export cho trường hợp phải chọn tường minh: OnnxBackend, OpenVINOBackend, PaddleBackend, TensorRTBackend, TritonBackend, NcnnBackend, CoreMLBackend, cùng create_triton_config. BaseExporter là registry exporter phía sau model.export().

Validator

model.val() dispatch đến validator đúng theo tác vụ, nên các lớp sau được export để dùng trực tiếp và tạo subclass: DetectionValidator, SegmentationValidator, PoseValidator, SemanticValidator, PanopticValidator, DepthValidator, NormalValidator, EdgeValidator, và ValidationConfig dùng chung.

Tracking

model.track() chọn tracker theo tên. Lớp tracker và dataclass cấu hình cũng được export: ByteTracker với TrackConfig, BoTSortTracker với BoTSortConfig, và OCSortTracker với OCSortConfig.

libreyolo.tracking.Tracker định nghĩa reset() và update(results, image=None) cho đối tượng tracker tùy chỉnh.

Helper dữ liệu

DATASETS_DIR là thư mục gốc dataset đã phân giải, load_data_config đọc YAML dataset và check_dataset xác thực file. Các loader theo tác vụ được nêu trong Định dạng dataset nằm trong libreyolo.data thay vì cấp package.

Gallery và distillation

Gallery và FaceGallery giữ vector danh tính đã đăng ký cho tác vụ embed và tạo payload Identities. Distiller cùng get_distill_config điều khiển huấn luyện teacher-student.

libreyolo.training.TrainFitnessCallback định nghĩa fitness(metrics) để tùy chỉnh chọn checkpoint. Xem callback fitness.

Asset

SAMPLE_IMAGE là đường dẫn tuyệt đối đến ảnh đi kèm package, nên mọi snippet trong tài liệu chạy được mà không cần tải ảnh trước.

Lazy import và lớp đổi tên

Phần lớn tên cấp sibling, backend, validator và helper dữ liệu phân giải qua __getattr__ cấp module, nên import libreyolo không import dependency của chúng. Import vẫn thất bại với thông báo rõ ràng khi thiếu gói bổ sung cần thiết.

Hai tên lớp đã được đổi và cách viết cũ vẫn phân giải kèm DeprecationWarning: LibreYOLORTDETR giờ là LibreRTDETR, còn LibreYOLORFDETR giờ là LibreRFDETR.