Core ML

설치

pip install "libreyolo[coreml]"

예측에는 macOS가 필요합니다. LibreYOLO()는 다른 플랫폼에서 .mlpackage를 거부하면서 현재 플랫폼 이름을 담은 메시지를 표시하며, 런타임 동등성 확인에는 macOS 러너가 필요하다는 이유로 지원 매트릭스는 이 조합들을 사용 가능으로 기록합니다.

내보내기

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9t.pt") # weights/LibreYOLO9t.mlpackage 번들을 기록합니다path = model.export(format="coreml")print(path)

libreyolo export --model LibreYOLO9t.pt --format coreml

model.export(    format="coreml",    imgsz=640,    batch=1,    half=False,           # True로 두면 FLOAT16 연산 정밀도로 변환합니다    compute_units="all",  # all | cpu_and_gpu | cpu_and_ne | cpu_only    output_path=None,     # None이면 weights/<stem>.mlpackage에 기록합니다) # dynamic 인자는 받아들여지지만 입력은 형상이 고정된 ct.ImageType이며,# 내장 메타데이터는 어느 쪽이든 dynamic=False로 기록합니다.

번들은 체크포인트의 파일 이름을 따서 weights/ 아래에 기록되며, half=True일 때는 _fp16이 덧붙습니다. .mlpackage는 디렉터리이므로 트리 전체를 복사해야 합니다.

모든 계열은 전처리 래퍼 뒤에서 트레이스되므로, 변환된 그래프는 하나의 표준 입력만 받습니다: RGB, scale=1/255, 바이어스 없음, ct.ImageType으로 선언. 래퍼는 계열 고유의 규약을 흡수하는데, YOLOX는 0에서 255 범위의 BGR, RF-DETR 계열은 ImageNet 평균과 표준편차, YOLO9과 RT-DETR 계열은 항등 변환을 씁니다. 그래서 Core ML 모델을 사용하는 쪽은 계열별 텐서가 아니라 평범한 이미지를 넣습니다.

변환은 최소 배포 대상 iOS 15로 ML Program을 목표로 합니다. compute_units는 변환된 모델에 저장되며, 아티팩트를 불러올 때 다시 덮어쓸 수 있습니다.

모델 메타데이터는 문자열로 user_defined_metadata에 들어가며, 백엔드는 여기에서 계열, 작업, 클래스 이름, 입력 크기, 자세 스키마를 읽습니다.

내장 NMS

from libreyolo import LibreYOLO # YOLOX와 YOLO9 탐지 전용, 배치 1.LibreYOLO("LibreYOLO9t.pt").export(    format="coreml",    nms=True,    conf=0.25,    iou=0.45,)

libreyolo export --model LibreYOLO9t.pt --format coreml --nms \  --conf 0.25 --iou 0.45

nms=True는 모델을 Apple의 NonMaximumSuppression 레이어로 끝나는 Core ML 파이프라인으로 감쌉니다. 결과에는 출력이 두 개 있습니다: 형상이 N x 클래스 개수인 confidence와, 정규화된 xywh로 형상이 N x 4인 coordinates입니다.

YOLOX와 YOLO9 탐지에만 적용되며, 배치 1이 필요합니다. DETR 계열 모델은 이름으로 거부되는데, 집합 예측은 쿼리와 클래스에 대해 IoU 단계 없이 top-k를 취하므로 그 레이어를 쓸 수 없기 때문입니다. max_det도 여기에서는 노출되지 않으므로, 탐지 개수 상한이 중요하다면 ONNX 내장 NMS를 대신 사용하십시오.

아티팩트 실행

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO(    "weights/LibreYOLO9t.mlpackage",    compute_units="all",   # 또는 cpu_and_ne로 Neural Engine에 고정)result = model.predict(SAMPLE_IMAGE)print(result.boxes.xyxy[:3])

import coremltools as ctfrom PIL import Image mlmodel = ct.models.MLModel("weights/LibreYOLO9t.mlpackage")print(mlmodel.user_defined_metadata["model_family"])print(mlmodel.user_defined_metadata["names"]) # 입력은 내보내기 시 고정된 크기의 "image"라는 이름의 이미지입니다.image = Image.open(SAMPLE_IMAGE).convert("RGB").resize((640, 640))out = mlmodel.predict({"image": image})print({name: value.shape for name, value in out.items()}) # 이 경로에서는 레터박싱과 후처리를 직접 해야 합니다.

LibreYOLO()는 .mlpackage 접미사가 붙은 디렉터리를 인식하고, 체크포인트와 동일한 Results 객체를 반환합니다. compute_units는 이 형식에서 팩토리가 그대로 전달하는 유일한 인자이며, all, cpu_and_gpu, cpu_and_ne, cpu_only를 받습니다. device 인자는 무시되는데, Core ML은 대신 컴퓨트 유닛으로 경로를 정하기 때문입니다.

두 번째 스니펫은 런타임을 직접 다루는 경로입니다. 여기에서는 레터박싱, 디코딩, NMS, 좌표 재조정을 직접 처리해야 하며, 클래스 이름은 user_defined_metadata에 들어 있습니다.

제약

네 개 계열, 탐지 전용입니다: yolox, yolo9, rtdetr, rfdetr. 그 외에는 사전 점검에서 거부되는데, 고정된 이미지 입력 계약이 올바르게 성립하는 것은 계열을 인식하는 전처리 래퍼 덕분이며, 여기에 없는 계열은 잘못된 정규화로 변환되기 때문입니다. 오류 메시지는 대안으로 ONNX와 TorchScript를 알려 줍니다.

입력 형상은 ct.ImageType으로 고정되어 있어서 dynamic=True는 아무것도 바꾸지 않으며, 메타데이터에는 dynamic=False가 기록됩니다. 다른 해상도가 필요하면 번들을 하나 더 내보내야 합니다.

half=True는 FP16 연산 정밀도로 변환합니다. 이 내보내기 도구에는 INT8 경로가 없습니다.

전체 계열과 작업 조합표는 내보내기 매트릭스를 참고하십시오. Apple의 더 새로운 온디바이스 형식은 Core AI를 참고하십시오. 특정 조합 하나만 확인하려면:

libreyolo formats --family yolo9 --task detect