모델 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를 전달하면 해당 상태 사전을 직접 로드합니다.

예측하고 __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))

삽입

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

모든 임베딩 행을 단일 (N_total, D) 텐서로 쌓는 predict에 대한 편리한 래퍼입니다. 모델은 task="embed"로 구성되어야 하며, 그렇지 않으면 NotImplementedError를 발생시킵니다.

트랙

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]

track_id가 설정된 경우 프레임당 하나의 Results를 생성합니다. tracker는 "bytetrack", "botsort", "ocsort", "deepocsort"(선택적으로 .yaml 접미사 포함) 또는 사용자 지정 트래커 인스턴스이며, 구성 유형이 트래커를 선택하기 때문에 tracker_config가 주어지면 무시됩니다. track_conf는 ByteTrack 및 BoT-SORT의 경우 track_high_thresh에 매핑되고, OC-SORT 및 Deep OC-SORT의 경우 det_thresh에 매핑됩니다. conf를 지정하면 predict()에서와 같이 탐지 임계값이 됩니다. persist=True는 프레임별 루프를 위해 이전 호출의 트래커를 유지합니다. output_path는 기본값이 runs/track/<video_stem>.mp4입니다.

값

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는 데이터셋 YAML이 download 필드에 포함할 수 있는 내장 Python을 제어합니다.

탐지와 분할에서 이 딕셔너리는 dict의 하위 클래스이며 box(이미지별 지표와 클래스별 정밀도, 재현율, F1 곡선)와 confusion_matrix도 담고, 분류에서는 top1, top5, confusion_matrix를 담습니다. 검증과 지표를 참조하십시오.

faster_coco_eval는 **kwargs를 통해 허용되며 기본값은 True이며, 패키지가 설치되지 않은 경우 pycocotools로 대체됩니다. 실행된 백엔드는 model.last_eval_backend에 보고됩니다.

역시 **kwargs를 통해 받는 agnostic_nms=True는 점수를 매기기 전에 iou에서 클래스를 구분하지 않는 NMS를 적용합니다. 탐지와 분할을 지원하며 다른 작업에서는 ValueError를 발생시킵니다.

obb 및 pose 작업에 대한 증강 검증 인상이 있습니다.

학습

train는 계열별로 정의되므로 그 인자가 다릅니다. 두 가지 동작은 공유되는데, 이는 기본 클래스가 모든 계열의 train를 감싸기 때문입니다:

• cfg=는 키가 호출에 병합되는 YAML 경로를 가져옵니다. 명시적 키워드 인수가 파일보다 우선합니다.
• pretrained=False가 g0 또는 g1 보장 그룹의 계열에 대해 모델을 학습하기 전에 처음부터 다시 초기화하며, resume=True와 결합할 수 없습니다.

계열마다 실제로 어떤 증강 옵션을 존중하는지는 계열별로 다르므로, 증강 행렬을 참조하십시오.

내보내기

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

작성된 아티팩트의 경로를 반환합니다. format는 익스포터 레지스트리를 통해 해결되며, 여기서 engine는 tensorrt의 별칭이고 litert는 tflite의 별칭입니다. 모든 익스포터가 공유하는 인수:

차단된 조합은 추적 전에 프리플라이트에서 NotImplementedError를 발생시킵니다. 형식이 사용하지 않는 옵션은 Unknown <format> export arguments (ignored) 경고를 내고 내보내기는 계속됩니다. 적용 범위와 규칙은 내보내기 매트릭스 페이지에 있습니다. 실시간 LoRA 어댑터가 있을 경우, 그것들은 밀집 가중치에 통합되며, 이 병합은 모든 요청이 거부된 후에만 발생합니다.

저장

model.save(path) -> str

스키마 v1.0 LibreYOLO 체크포인트를 작성합니다: 상태 딕셔너리와 체크포인트 스키마에 설명된 메타데이터를 포함합니다. 양자화된 모델은 추가로 quant 매니페스트를 가지고 있어, LibreYOLO(path)가 양자화된 구조와 스케일을 복원합니다.

양자화, 양자 정보 및 역양자화

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 경로 또는 내장 데이터셋 이름을 사용하며 이미지를 순방향Only로 읽습니다; 레이블은 절대 읽지 않습니다. 보정 생략을 위해 calib=None를 전달합니다. algorithm는 "minmax", "percentile" 또는 "auto"입니다.

model.quant_info()는 양자화 상태 요약을 반환하며, float 모델의 경우 None를 사용합니다. model.dequantize()는 양자화 학습된 마스터 가중치를 유지하면서 float 모듈을 제자리에서 복원하며, 이는 QAT에서 export(format="onnx", int8=True, data=...)로 가는 다리 역할을 합니다.

정보와 레이어

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

info는 JSON 친화적인 딕셔너리를 반환하고 verbose가 true일 때 사람이 읽을 수 있는 요약을 기록합니다. get_available_layer_names는 증류 또는 특징 추출 구성에서 이름을 지정할 수 있는 레이어를 나열합니다.

CUDA 그래프

SUPPORTS_CUDA_GRAPH 클래스 속성이 true인 계열에서 사용할 수 있습니다. 재생은 즉시 실행과 비트 단위로 동일합니다.

model.capture_graph(imgsz=None, batch=1, dtype=None) -> Nonemodel.cuda_graph_scope(mode=True)          # 컨텍스트 관리자model.graph_info() -> Dict[str, Any]model.release_graphs() -> None

캡처된 그래프는 캡처된 정확한 형태에 대해서만 유효하므로 batch와 imgsz은 이후 predict 호출과 일치해야 합니다. capture_graph는 첫 번째 요청에서 캡처 비용을 이동합니다. mode는 True 또는 "on"를 사용하여 처음 사용할 때 캡처하도록 허용하고, "auto"를 사용하여 형태가 반복될 때까지 기다리며, False를 사용하여 아무 작업도 하지 않도록 합니다. capture_graph는 family가 선택하지 않은 경우 NotImplementedError를 발생시키고, 캡처에 실패하면 CudaGraphUnavailable를 발생시킵니다.

장치 및 데이터 유형

Results 객체는 .to(), .cpu(), .cuda() 및 .numpy()를 포함합니다; Results types를 참조하십시오. 모델 자체는 device=를 predict에 전달하거나 생성 시 이동됩니다.