이미지 분류

정의

이미지 분류는 전체 이미지에 대해 클래스별로 하나의 점수만 생성하며 좌표는 전혀 제공하지 않습니다. 이는 그림 속에 무엇이 있는지를 알려줄 뿐, 위치는 알려주지 않으며, 이것이 객체 검출과 구분되는 점입니다.

classify는 표준 작업 키이며, 체크포인트 파일 이름의 -cls 접미사가 그것을 선택합니다. 분류 계열에서는 그 접미사가 선택 사항이 아니라 필수이므로 LibreResNet50.pt는 분류기로 읽히지 않으며 오직 LibreResNet50-cls.pt만 읽힙니다.

predict()는 result.probs를 채우고 boxes를 비웁니다. .data는 최고 점수 벡터이고, .top1는 최고 점수의 인덱스이며 .top1conf는 그 값입니다. .top5는 내림차순으로 다섯 개의 최고 인덱스이며 .top5conf는 그 점수입니다. 인덱스는 result.names를 가리킵니다. Results 객체를 슬라이싱해도 probs는 절대 잘리지 않습니다. 벡터가 행 하나에 속하는 것이 아니라 이미지에 속하기 때문입니다.

모델들

학습 가능한 이미지 분류 모델은 ResNet, ConvNeXt, MobileNetV4, EfficientNetV2, DINOv2입니다. 앞의 네 계열은 기본 패키지에서 실행되며 공개 가중치를 제공합니다. DINOv2는 pip install "libreyolo[rfdetr]"이 필요하며 LibreYOLO에서 호스팅하는 체크포인트는 없습니다. 업스트림 백본과 무작위로 초기화한 선형 헤드를 로드하므로 바로 예측할 수 있는 모델이 아니라 파인튜닝 시작점입니다.

다섯 가지가 더 예측, 검증 및 내보내기를 수행하지만, 그들의 train()는 NotImplementedError를 발생시킵니다: ViT, Swin, VGG, AlexNet 및 DeiT.

CLIP과 SigLIP2는 고정된 레이블 집합 없이 분류합니다. 이들은 이미지를 텍스트 프롬프트와 비교하여 점수를 매기기 때문에 set_classes()는 호출 시 클래스들을 정의하며, 새로운 레이블 집합에 대한 학습 단계가 전혀 없습니다. 두 모델 모두 embed 작업에도 사용됩니다.

ConvNeXt V2는 CC-BY-NC-4.0 사전 학습 가중치로 지도 분류를 추가합니다. PE는 제로샷 분류를 지원하며, V-JEPA 2는 비디오 분류 프로브를 학습합니다.

예측

가중치는 처음 사용할 때 Hugging Face에서 다운로드되며 로컬에 캐시됩니다.

from libreyolo import LibreYOLO, SAMPLE_IMAGE # 파일 이름의 -cls 접미사는 작업을 선택하므로 작업이 없습니다# 주장이 필요합니다.model = LibreYOLO("LibreResNet50-cls.pt")result = model(SAMPLE_IMAGE, save=True) print(result.names[result.probs.top1], float(result.probs.top1conf))print(result.probs.top5)

libreyolo predict model=LibreResNet50-cls.pt save=True \  source=https://raw.githubusercontent.com/LibreYOLO/libreyolo/release/libreyolo/assets/parkour.jpg

from libreyolo import LibreYOLO, SAMPLE_IMAGE result = LibreYOLO("LibreResNet50-cls.pt")(SAMPLE_IMAGE)probs = result.probs # .data는 전체 (C,) 벡터입니다; top5/top5conf는 순서가 지정된 뷰입니다.print(probs.data.shape)for index, score in zip(probs.top5, probs.top5conf):    print(result.names[index], float(score))

from libreyolo import LibreYOLO, SAMPLE_IMAGE # CLIP은 이미지를 텍스트 프롬프트와 비교하여 점수를 매기므로, 레이블 세트는# 체크포인트에 내장되지 않고 호출 시 설정됩니다.model = LibreYOLO("LibreCLIPb32-cls.pt")model.set_classes(["a person jumping", "an empty street", "a parked car"])result = model(SAMPLE_IMAGE) print(model.names[result.probs.top1], float(result.probs.top1conf))

conf, iou 및 max_det는 여기서 아무 효과가 없습니다: 임계값을 적용하거나 억제할 후보가 없으며, 단 하나의 분포만 있습니다. 소스, 스트리밍 및 결과 처리에 대해서는 prediction를 참조하십시오.

데이터셋 형식

분류는 레이블 파일이나 YAML이 아니라 디렉토리 트리를 사용합니다. data는 데이터셋 루트입니다.

dataset/  train/    tench/000001.jpg    parachute/000002.jpg  val/    tench/000101.jpg    parachute/000102.jpg

train/는 학습을 위해 필요하며, 폴더 이름을 정렬하여 클래스-인덱스 매핑을 정의하므로 알파벳 순으로 첫 번째 폴더가 클래스 0이 됩니다. val/는 검증을 위해 필요합니다. test/ 분할이 존재할 수 있으며, 기본 학습 및 검증 명령은 이를 사용하지 않습니다. train 이외의 다른 분할은 예상 클래스 집합과 동일한 클래스 폴더 이름을 포함해야 하며, 이는 불일치가 잘못된 예측으로 점수화되는 대신 명확하게 실패하게 만드는 이유입니다. 허용되는 이미지 확장자는 .jpg, .jpeg, .png, .bmp, .webp, .tif 및 .tiff입니다.

data는 세 가지를 허용합니다: train/ 분할이 포함된 디렉토리 경로, .zip URL, 또는 알려진 데이터셋 이름 중 하나인 imagenette160와 smoke10로, 처음 사용할 때 다운로드되고 캐시됩니다.

정식 로더는 libreyolo.data.classify_dataset입니다.

학습

from libreyolo import LibreYOLO # imagenette160는 잘 알려진 데이터셋 이름이며 처음 사용할 때 다운로드됩니다.# 자신의 데이터에 대한 train/ 분할이 있는 디렉터리를 전달하십시오.model = LibreYOLO("LibreResNet50-cls.pt")model.train(data="imagenette160", epochs=5)

libreyolo train model=LibreResNet50-cls.pt data=imagenette160 epochs=5

libreyolo train model=LibreResNet50-cls.pt data=imagenette160 \  epochs=50 device=0,1 batch=-1

선언할 nc가 없습니다: 클래스 수는 train/ 아래 폴더 이름에서 가져오며, 최종 선형 레이어는 이를 맞추기 위해 재구성되지만 백본은 변경 없이 전이됩니다. 데이터셋, 증강, 멀티 GPU 및 로거에 대한 내용은 training을 참조하십시오.

ResNet, ConvNeXt, ConvNeXt V2, MobileNetV4, EfficientNetV2, DINOv2는 cls_pw 또는 class_weights 손실 가중치를 지원합니다. 분류의 scale은 크롭 면적을 제어하며 crop_pct는 평가 크롭을 제어합니다. 데이터 증강을 참조하십시오.

리사이즈 필터는 모델의 일부입니다. 학습 전에 model.interpolation을 "bilinear", "bicubic", "nearest", "bilinear_no_antialias" 중 하나로 설정합니다. 학습, val(), predict(), INT8 보정, 내보내기가 모두 이를 사용하고, save(), best.pt, last.pt가 이를 기록하므로 다시 불러와도 유지됩니다. 그 외의 이름은 ValueError를 발생시킵니다. "bilinear_no_antialias"는 안티앨리어싱 없는 런타임 리사이즈 뒤에서 실행될 모델을 위해, RandomResizedCrop을 포함한 모든 곳에서 안티앨리어싱 없이 단순 바이리니어로 리사이즈합니다. MobileNetV4, ResNet, ConvNeXt, ConvNeXt V2, EfficientNetV2, DeiT, Swin, ViT는 기본값이 바이큐빅이고, AlexNet과 VGG는 바이리니어입니다.

검증

val()는 데이터셋 루트의 val/ 분할에 대해 계산된 metrics/ 키의 사전을 반환합니다.

from libreyolo import LibreYOLO model = LibreYOLO("LibreResNet50-cls.pt") # metrics/ 키의 딕셔너리이며, top1, top5, confusion_matrix도 담습니다.metrics = model.val(data="imagenette160") print(metrics["metrics/accuracy_top1"])print(metrics["metrics/accuracy_top5"])print(metrics.top1, metrics.top5)

libreyolo val model=LibreResNet50-cls.pt data=imagenette160

metrics/accuracy_top1는 가장 높은 점수를 받은 클래스가 실제 클래스인 이미지의 비율이며, 이는 주요 수치로, 학습에서 최적의 에포크를 선택할 때 사용됩니다. metrics/accuracy_top5는 상위 5개의 점수 높은 클래스 중 어느 곳에든 실제 클래스가 나타나는 이미지의 비율로, 데이터셋의 클래스 수가 적을수록 의미가 줄어듭니다. 사전에는 또한 fitness가 포함되어 있으며, 이는 top-1 값을 복사한 것입니다.

ImageFolder 검증은 검증 정답에 있는 클래스의 평균을 구한 매크로 metrics/precision, metrics/recall, metrics/f1도 반환합니다. 예측되지 않은 클래스의 정밀도는 0으로 계산합니다. 기본 적합도는 top-1 정확도를 유지합니다. 검증과 보정은 모델의 평가 변환을 사용합니다.

결과는 속성이 세 개 있는 dict 하위 클래스입니다. top1과 top5는 두 정확도 값을 담고, confusion_matrix는 각 이미지를 top-1 클래스와 레이블 기준으로 세며 matrix[predicted, true]로 인덱싱합니다. plots=True는 이를 개수로 confusion_matrix.png에, 레이블별 비율로 confusion_matrix_normalized.png에 기록합니다. 클래스가 2,000개를 넘으면 조밀 행렬과 그 그림은 사용할 수 없으며, nonzero(), tp_fp(), class_accuracy()가 대신 개수를 읽습니다. 검증과 지표를 참조하십시오.

내보내기

from libreyolo import LibreYOLO model = LibreYOLO("LibreResNet50-cls.pt")model.export(format="onnx")

libreyolo export model=LibreResNet50-cls.pt format=onnx

from libreyolo import LibreYOLO, SAMPLE_IMAGE # 팩토리는 파일 접미사에 따라 경로를 지정하므로, 내보낸 아티팩트가 로드됩니다# 체크포인트처럼 작동하며 같은 Results 객체를 반환합니다.model = LibreYOLO("LibreResNet50-cls.onnx")result = model(SAMPLE_IMAGE) print(result.probs.top1, result.probs.top1conf)

내보낸 아티팩트는 파일 접미사를 통해 LibreYOLO()로 다시 로드되므로, .onnx 또는 .engine 파일은 체크포인트처럼 작동하며 동일한 Results를 반환합니다. 형식 지원 범위는 계열별로 다르며, 각 모델 페이지의 매트릭스는 수작업으로 작성된 것이 아니라 검증된 세트에서 생성됩니다. 형식, 추가 기능 및 제약 사항은 export and deploy를 참조하십시오.