Classificação de imagens

Definição

A classificação de imagens produz uma pontuação por classe para a imagem inteira e nenhuma coordenada. Ela responde o que está na imagem, nunca onde, e é isso que a separa da detecção de objetos.

classify é a chave canônica da tarefa, e o sufixo -cls no nome do arquivo de um checkpoint a seleciona. Esse sufixo é obrigatório, não opcional, nas famílias de classificação, então LibreResNet50.pt não é lido como classificador e só LibreResNet50-cls.pt é.

predict() preenche result.probs e deixa boxes vazio. .data é o vetor completo de pontuações, .top1 o índice da maior pontuação e .top1conf o valor dela, .top5 os cinco maiores índices em ordem decrescente e .top5conf as pontuações deles. Os índices apontam para result.names. Fatiar um objeto Results nunca trunca probs, porque o vetor pertence à imagem, e não a uma linha.

Modelos

Os classificadores de imagens treináveis incluem: ResNet, ConvNeXt, MobileNetV4, EfficientNetV2 e DINOv2. Os quatro primeiros rodam com o pacote base e têm pesos publicados. DINOv2 precisa de pip install "libreyolo[rfdetr]" e não tem checkpoint hospedado pelo LibreYOLO: carrega o backbone upstream com uma cabeça linear inicializada aleatoriamente, então é um ponto de partida para fine-tuning, não um preditor pronto.

Outras cinco fazem predição, validação e exportação, mas o train() delas levanta NotImplementedError: ViT, Swin, VGG, AlexNet e DeiT.

CLIP e SigLIP2 classificam sem um conjunto fixo de rótulos. Eles pontuam a imagem em relação a prompts de texto, então set_classes() define as classes na hora da chamada e não existe nenhuma etapa de treinamento para um novo conjunto de rótulos. Ambos também atendem à tarefa embed.

ConvNeXt V2 adiciona classificação supervisionada com pesos pré-treinados CC-BY-NC-4.0. PE suporta classificação zero-shot; V-JEPA 2 treina probes de classificação de vídeo.

Predição

Os pesos são baixados do Hugging Face no primeiro uso e ficam em cache localmente.

from libreyolo import LibreYOLO, SAMPLE_IMAGE # O sufixo -cls no nome do arquivo seleciona a tarefa, então não é# preciso passar o argumento task.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 é o vetor completo (C,); top5/top5conf são visões ordenadas.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 # O CLIP pontua a imagem em relação a prompts de texto, então o conjunto de# rótulos é definido na hora da chamada em vez de embutido no checkpoint.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 e max_det não têm efeito aqui: não há candidatos para filtrar por limiar ou suprimir, apenas uma distribuição. Veja predição para fontes, streaming e tratamento dos resultados.

Formato do dataset

A classificação usa uma árvore de diretórios, não arquivos de rótulos nem um YAML. data é a raiz do dataset.

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

train/ é obrigatório para o treinamento e define o mapeamento de classe para índice pelo nome das pastas em ordem alfabética, então a primeira pasta na ordem alfabética vira a classe 0. val/ é obrigatório para a validação. Um split test/ pode existir, e os comandos padrão de treinamento e validação não o usam. Qualquer split que não seja train precisa conter os mesmos nomes de pastas de classe do conjunto de classes esperado, que é o que faz uma divergência falhar em alto e bom som em vez de contar como uma predição errada. As extensões de imagem aceitas são .jpg, .jpeg, .png, .bmp, .webp, .tif e .tiff.

data aceita três coisas: um caminho para um diretório que contenha um split train/, uma URL .zip, ou um dos nomes de dataset conhecidos, imagenette160 e smoke10, que são baixados e ficam em cache no primeiro uso.

O loader canônico é libreyolo.data.classify_dataset.

Treinamento

from libreyolo import LibreYOLO # imagenette160 é um nome de dataset conhecido e é baixado no primeiro uso.# Passe um diretório com um split train/ para seus próprios dados.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

Não há nc para declarar: a contagem de classes vem dos nomes das pastas dentro de train/, e a camada linear final é reconstruída para bater com ela enquanto o backbone é transferido sem alteração. Veja treinamento para datasets, data augmentation, multi-GPU e loggers.

ResNet, ConvNeXt, ConvNeXt V2, MobileNetV4, EfficientNetV2 e DINOv2 suportam ponderação de loss com cls_pw ou class_weights. Na classificação, scale controla a área de recorte, e crop_pct controla o recorte de avaliação. Veja data augmentation.

O filtro de resize faz parte do modelo. Defina model.interpolation como "bilinear", "bicubic", "nearest" ou "bilinear_no_antialias" antes de treinar: treinamento, val(), predict(), calibração INT8 e exportação todos o usam, e save(), best.pt e last.pt o registram, então um recarregamento o mantém. Qualquer outro nome levanta ValueError. "bilinear_no_antialias" redimensiona com bilinear puro e sem antialiasing em todo lugar, RandomResizedCrop incluído, para modelos que vão rodar atrás de um resize de runtime sem antialiasing. MobileNetV4, ResNet, ConvNeXt, ConvNeXt V2, EfficientNetV2, DeiT, Swin e ViT usam bicubic por padrão; AlexNet e VGG, bilinear.

Validação

val() retorna um dicionário de chaves metrics/, calculado sobre o split val/ da raiz do dataset.

from libreyolo import LibreYOLO model = LibreYOLO("LibreResNet50-cls.pt") # Um dict de chaves metrics/, mais top1, top5 e 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 é a proporção de imagens cuja classe de maior pontuação é a verdadeira, e é o número principal, o que o treinamento usa para escolher a melhor época. metrics/accuracy_top5 é a proporção cuja classe verdadeira aparece em qualquer posição entre as cinco classes de maior pontuação, o que diz menos quanto menos classes o dataset tiver. O dicionário também traz fitness, uma cópia do valor top-1.

A validação ImageFolder também retorna as métricas macro metrics/precision, metrics/recall e metrics/f1, calculando a média das classes presentes nos alvos de validação. Classes sem predições contribuem com precisão zero. O fitness padrão continua sendo a acurácia top-1. Validação e calibração usam a transformação de avaliação do modelo.

O resultado é uma subclasse de dict com três atributos: top1 e top5 guardam os dois valores de acurácia, e confusion_matrix conta cada imagem na sua classe top-1 contra o seu rótulo, indexada matrix[predicted, true]. plots=True a grava como contagens em confusion_matrix.png e como proporções de cada rótulo em confusion_matrix_normalized.png. Acima de 2,000 classes a matriz densa e os seus gráficos ficam indisponíveis, e nonzero(), tp_fp() e class_accuracy() leem as contagens no lugar; veja Validação e métricas.

Exportação

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 # A factory decide pelo sufixo do arquivo, então um artefato exportado# é carregado como um checkpoint e retorna o mesmo objeto Results.model = LibreYOLO("LibreResNet50-cls.onnx")result = model(SAMPLE_IMAGE) print(result.probs.top1, result.probs.top1conf)

Um artefato exportado é carregado de volta pelo LibreYOLO() a partir do sufixo do arquivo, então um arquivo .onnx ou .engine se comporta como um checkpoint e retorna o mesmo Results. A cobertura de formatos varia por família; a matriz em cada página de modelo é gerada a partir do conjunto validado, e não digitada à mão. Veja exportação e deploy para os formatos, seus extras e suas restrições.