O que vem depois

Todas as famílias usam detecção por padrão. Você seleciona outra tarefa de uma entre três formas, resolvidas nesta ordem de precedência:

Como a fábrica pública LibreYOLO(...) espera um arquivo de pesos real, a forma mais limpa de iniciar uma dessas tarefas do zero é construir a classe da família diretamente e passar task=. Os checkpoints treinados voltam a ser carregados pela fábrica unificada, que detecta a tarefa automaticamente.

1
from libreyolo import LibreYOLO, LibreYOLO9, LibreRFDETR
2
3
# Start a task from scratch via the family class
4
m = LibreYOLO9(None, size="t", task="classify", nb_classes=10)
5
6
# Load a trained checkpoint via the unified factory (task auto-detected)
7
m = LibreYOLO("LibreYOLO9t-obb.pt")

A classificação fornece uma única label para a imagem inteira. O YOLO9 mantém seu backbone e adiciona uma cabeça de classificação leve. O RF-DETR reutiliza seu encoder DINOv2 e adiciona uma cabeça linear com pooling. Ambos rodam em 224 por 224.

Inferência e o resultado Probs

A predição retorna um objeto Results cujo campo probs contém um softmax sobre as classes.

1
from libreyolo import LibreYOLO
2
3
model = LibreYOLO("LibreYOLO9t-cls.pt")
4
r = model.predict("cat.jpg")
5
6
print(r.probs.top1)        # class id of the argmax
7
print(r.probs.top1conf)    # its probability
8
print(r.probs.top5)        # [id, id, id, id, id]
9
print(model.names[r.probs.top1])  # human-readable label

Formato do dataset e treinamento

A classificação usa uma estrutura ImageFolder, não um YAML. Os nomes das classes são os nomes ordenados das subpastas, fixados de acordo com a divisão de treino.

1
dataset/
2
  train/
3
    cat/   img001.jpg ...
4
    dog/   img104.jpg ...
5
  val/
6
    cat/   ...
7
    dog/   ...

O argumento data= aceita uma pasta, uma URL .zip ou um nome conhecido para download automático (imagenette160 e imagenet10). A cabeça é reconstruída automaticamente para corresponder ao número de classes do dataset.

1
from libreyolo import LibreYOLO9
2
3
model = LibreYOLO9(None, size="t", task="classify", nb_classes=10)
4
result = model.train(
5
    data="imagenette160",   # folder, .zip URL, or known name
6
    epochs=10, batch=64, imgsz=224,
7
    optimizer="adamw", lr0=1e-3,
8
)
9
# Validation reports metrics/accuracy_top1 and metrics/accuracy_top5

As caixas orientadas têm um ângulo de rotação, necessário em imagens aéreas, documentos e cenas densamente ocupadas. O YOLO9 adiciona uma ramificação de ângulo à sua cabeça de detecção. O RF-DETR adiciona um embedding de ângulo aprendível ao seu decoder.

Inferência e o resultado OBB

Results expõe um campo obb. Os ângulos estão em radianos.

1
from libreyolo import LibreYOLO
2
3
model = LibreYOLO("LibreYOLO9t-obb.pt")
4
r = model.predict("aerial.jpg")
5
6
for i in range(len(r.obb.cls)):
7
    cx, cy, w, h, angle = r.obb.xywhr[i]  # angle in radians
8
    corners = r.obb.xyxyxyxy[i]           # 4 (x, y) corner points
9
    conf, cls = r.obb.conf[i], r.obb.cls[i]

Formato do dataset e treinamento

OBB usa um YAML de dados padrão no estilo de detecção, mas as labels são arquivos de texto YOLO-OBB com exatamente nove campos por linha: um ID de classe seguido por quatro pontos de canto normalizados. O ângulo é derivado dos cantos, não armazenado.

1
# class_id  x1 y1  x2 y2  x3 y3  x4 y4   (all normalized to [0, 1])
2
0  0.51 0.32  0.66 0.38  0.62 0.55  0.47 0.49
3
2  0.10 0.71  0.18 0.69  0.20 0.80  0.12 0.82

Um checkpoint simples de detecção não pode ser carregado diretamente em um modelo OBB. A passagem de detecção para OBB só é permitida como warm-start de treinamento: passe pretrained=True (YOLO9) ou a flag explícita de transferência no RF-DETR. Mosaic e mixup ficam desativados para OBB até a chegada de um data augmentation que considere os cantos, e a inferência por blocos (tiles) não é compatível.

1
from libreyolo import LibreYOLO9
2
3
model = LibreYOLO9(None, size="t", task="obb")
4
# Warm-start the backbone from a same-family detect checkpoint
5
result = model.train(data="dota8.yaml", pretrained=True, epochs=100, imgsz=640)
6
7
# CLI equivalent
8
# libreyolo train model=LibreYOLO9t.pt data=dota8.yaml --task obb

A validação usa AP com IoU rotacionada, informada como mAP50 e mAP50-95 no grupo de métricas OBB.

A estimativa de pose prediz keypoints por instância detectada. A estrutura padrão é de keypoints de pessoas COCO-17. Na primeira versão, pose com YOLO9 e RF-DETR terá uma única classe, apenas para pessoas. Pose com YOLO-NAS e EdgeCrafter já está disponível no código.

Inferência e o resultado Keypoints

Results expõe um campo keypoints com formato (N, K, 3), em que o último canal representa visibilidade ou confiança, nas coordenadas de pixels da imagem original.

1
from libreyolo import LibreYOLO
2
3
model = LibreYOLO("LibreYOLO9t-pose.pt")
4
r = model.predict("athletes.jpg")
5
6
kp = r.keypoints
7
print(kp.xy.shape)   # (N, 17, 2) pixel coordinates
8
print(kp.conf)       # (N, 17)    per-keypoint visibility / confidence
9
print(kp.xyn)        # normalized coordinates
10
print(r.boxes.xyxy)  # person boxes still come along

Formato do dataset e treinamento

Pose usa um YAML de dados que precisa declarar kpt_shape: [K, 2|3] e, para data augmentation com inversão horizontal, um flip_idx. As labels são linhas de texto YOLO-pose: um ID de classe, um bounding box normalizado e, depois, K trios de keypoints (x, y, v), com visibilidade v em {0, 1, 2}.

1
path: coco8-pose
2
train: images/train
3
val: images/val
4
nc: 1
5
names:
6
  0: person
7
kpt_shape: [17, 3]
8
flip_idx: [0, 2, 1, 4, 3, 6, 5, 8, 7, 10, 9, 12, 11, 14, 13, 16, 15]

1
from libreyolo import LibreYOLO9
2
3
# Warm-start from a detection checkpoint; the keypoint head is reinitialized
4
model = LibreYOLO9("LibreYOLO9t.pt", size="t", task="pose")
5
model.train(data="coco8-pose.yaml", epochs=100, imgsz=640)
6
7
# Validation reports OKS-based AP via the pose validator

YOLO9-P2 é um YOLOv9 com uma quarta escala de detecção em stride 4. O YOLOv9 padrão detecta nos strides 8/16/32, então objetos abaixo de ~16 px ficam menores que sua grade mais fina. A cabeça P2 captura o intervalo de 4-16 px que predomina em imagens aéreas e de drones.

Em um teste A/B controlado no VisDrone (mesma receita, mesma resolução, mesma inicialização. A única mudança foi a cabeça P2), o AP de objetos pequenos melhorou +49% em relação ao YOLOv9 padrão do mesmo tamanho. O aumento da resolução de treinamento e o uso do tamanho s maior praticamente dobraram o AP de objetos pequenos em todo o projeto:

Validação no VisDrone2019-DET (548 imagens), pycocotools, uma única seed. Considere ±1 ponto como ruído.

A prévia de pesquisa no VisDrone

Um checkpoint treinado foi publicado como LibreYOLO9P2s-visdrone. A família foi incorporada à branch dev, mas ainda não está em uma versão no PyPI. Até a próxima versão, instale a partir do código-fonte.

1
from libreyolo import LibreYOLO
2
3
# Auto-downloads from the LibreYOLO Hugging Face org
4
model = LibreYOLO("LibreYOLO9P2s-visdrone.pt")
5
6
# Evaluate/predict at 768 - the resolution it was trained at
7
results = model.predict("aerial.jpg", imgsz=768, conf=0.25)

Quando usar (ou não)

Adapte a arquitetura ao cenário. Em dados semelhantes ao COCO ("pequeno" significa 16-32 px), a cabeça P2 não ajuda. O YOLOv9 padrão é a melhor escolha nesse caso. Use o YOLO9-P2 quando seus objetos tiverem menos de ~16 px: imagens aéreas e de drones, câmeras de segurança distantes e blocos de imagens de satélite. A escala extra praticamente dobra a computação e o número de âncoras. Esse é o preço da grade de stride 4.

Treinamento do seu próprio modelo

O YOLO9-P2 é inicializado por transferência a partir de checkpoints de detecção do YOLOv9 padrão: o backbone, o neck compartilhado e as torres das cabeças existentes são carregados. Os novos módulos P2 começam do zero. A receita abaixo reúne o que aprendemos da maneira mais difícil com dados de objetos minúsculos:

1
from libreyolo import LibreYOLO9P2
2
3
model = LibreYOLO9P2(None, size="s")
4
model.train(
5
    data="/abs/path/tiny_objects.yaml",
6
    imgsz=768,                # resolution is the biggest lever for tiny objects
7
    lr0=0.005,                # the family default 0.01 diverges on transfer init
8
    mosaic_prob=0.0,          # mosaic tiling shrinks tiny objects below detectability
9
    mixup_prob=0.0,
10
    hsv_prob=1.0, flip_prob=0.5,
11
    max_labels=600,           # dense aerial frames exceed the default 100-box cap
12
    pretrained="LibreYOLO9s.pt",  # transfer init from stock YOLOv9
13
    epochs=60,
14
)

Adaptadores no estilo LoRA permitem fazer fine-tuning do backbone transformer do RF-DETR treinando um pequeno conjunto de matrizes de baixo posto enquanto os pesos base permanecem congelados. Isso reduz o uso de memória do otimizador e dos gradientes, o que é ideal para adaptar um checkpoint forte a um novo domínio em hardware modesto.

Como ativar

Toda a API pública se resume a uma única flag em train(). Não há controles de posto, alfa ou módulo-alvo para ajustar. A receita é fixa em uma configuração bem testada. Nos bastidores, a implementação usa DoRA (LoRA com decomposição de pesos, posto 16) aplicado às projeções de consulta, chave e valor da atenção do DINOv2.

1
from libreyolo import LibreYOLO
2
3
model = LibreYOLO("rf-detr-nano.pth")   # sizes n, s, m, l
4
result = model.train(
5
    data="data.yaml",
6
    lora=True,        # DoRA on the frozen DINOv2 backbone
7
    epochs=100, batch_size=4, lr=1e-4,
8
)
9
10
# Resume: LoRA is auto-detected from the checkpoint, no need to repeat the flag
11
model.train(data="data.yaml", resume=True)

1
# CLI equivalent
2
libreyolo train --model rf-detr-nano.pth --data data.yaml --lora

Checkpoints e exportação

• Os checkpoints de treinamento mantêm os tensores do adaptador, e a configuração registra que LoRA foi usado. Assim, o carregamento e a retomada reconstroem o grafo do adaptador automaticamente.
• A cabeça de detecção sempre permanece treinável, então você ainda pode adaptá-la a uma nova quantidade de classes.
• export() reincorpora os adaptadores aos pesos densos. Os modelos exportados são comuns e não têm dependência de peft.
• LoRA é exclusivo do RF-DETR. Passar lora=True para outras famílias gera um erro claro.

O estado atual de cada recurso. Tudo aqui é experimental. Esta tabela é o mapa fiel.