모델 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,
    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,
    iou=0.45,
    imgsz=None,
    classes=None,
    max_det=300,
    save=False,
    show=False,
    vid_stride=1,
    output_path=None,
    tracker="bytetrack",
    tracker_config=None,
    augment=False,
    **tracker_kwargs,
) -> Generator[Results, None, None]

track_id가 설정된 경우 프레임당 하나의 Results를 생성합니다. tracker는 "bytetrack", "botsort", "ocsort" 또는 "deepocsort"이며, 구성 유형이 트래커를 선택하기 때문에 tracker_config가 주어지면 무시됩니다. track_conf는 ByteTrack 및 BoT-SORT의 경우 track_high_thresh에 매핑되고, OC-SORT 및 Deep OC-SORT의 경우 det_thresh에 매핑됩니다. 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,
    **kwargs,
) -> Dict

작업에 따라 키가 달라지는 메트릭 사전을 반환합니다; 탐지는 metrics/precision, metrics/recall, metrics/mAP50 및 metrics/mAP50-95를 반환합니다. imgsz는 정사각형 정수 또는 (height, width) 튜플을 허용하며 모델의 기본 입력 크기를 기본값으로 사용합니다. plots는 save_plots의 별칭입니다. allow_download_scripts는 데이터셋 YAML이 download 필드에 포함할 수 있는 내장 Python을 제어합니다.

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

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

학습

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

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

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

내보내기

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

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

차단된 조합은 추적 전에 프리플라이트에서 NotImplementedError를 발생시킵니다. 적용 범위와 규칙은 내보내기 매트릭스 페이지에 있습니다. 실시간 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) -> None
model.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에 전달하거나 생성 시 이동됩니다.