Lo siguiente

Todas las familias usan detección de forma predeterminada. Puedes seleccionar otra tarea de tres maneras, resueltas en este orden de prioridad:

Como la factoría pública LibreYOLO(...) espera un archivo de pesos real, la forma más limpia de iniciar una de estas tareas desde cero es construir directamente la clase de la familia y pasar task=. Los checkpoints entrenados vuelven a cargarse mediante la factoría unificada y detectan su tarea automáticamente.

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")

La clasificación asigna una sola etiqueta a una imagen completa. YOLO9 conserva su backbone y añade una cabeza de clasificación ligera; RF-DETR reutiliza su codificador DINOv2 y añade una cabeza lineal con pooling. Ambos se ejecutan a 224 por 224.

Inferencia y resultado Probs

La predicción devuelve un objeto Results cuyo campo probs contiene un softmax sobre las clases.

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 del dataset y entrenamiento

La clasificación usa una estructura ImageFolder, no un YAML. Los nombres de las clases son los nombres ordenados de las subcarpetas y quedan fijados según la partición de entrenamiento.

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

El argumento data= acepta una carpeta, una URL .zip o un nombre conocido de descarga automática (imagenette160 e imagenet10). La cabeza se reconstruye automáticamente para coincidir con el número de clases del 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

Las cajas orientadas incluyen un ángulo de rotación, necesario para imágenes aéreas, documentos y escenas muy densas. YOLO9 añade una rama de ángulo a su cabeza de detección; RF-DETR añade un embedding de ángulo aprendible a su decodificador.

Inferencia y resultado OBB

Los resultados exponen un campo obb. Los ángulos se expresan en radianes.

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 del dataset y entrenamiento

OBB usa un YAML de datos estándar con estilo de detección, pero las etiquetas son archivos de texto YOLO-OBB con exactamente nueve campos por fila: un ID de clase seguido de cuatro puntos de esquina normalizados. El ángulo se deriva de las esquinas, no se almacena.

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

Un checkpoint de detección normal no se puede cargar directamente en un modelo OBB. Pasar de detección a OBB solo se permite como inicio en caliente del entrenamiento: pasa pretrained=True (YOLO9) o el flag explícito de transferencia en RF-DETR. Mosaic y mixup están desactivados para OBB hasta que llegue un aumento de datos compatible con las esquinas, y la inferencia por teselas no es compatible.

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

La validación usa AP con IoU rotado, presentado como mAP50 y mAP50-95 dentro del grupo de métricas OBB.

La estimación de pose predice puntos clave por cada instancia detectada. La estructura predeterminada contiene puntos clave de personas COCO-17. En su primera versión, la pose de YOLO9 y RF-DETR es de una sola clase y exclusiva para personas; la pose de YOLO-NAS y EdgeCrafter ya está disponible en el árbol.

Inferencia y resultado Keypoints

Los resultados exponen un campo keypoints de forma (N, K, 3), donde el último canal es la visibilidad o confianza, en coordenadas de píxeles de la imagen 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 del dataset y entrenamiento

La pose usa un YAML de datos que debe declarar kpt_shape: [K, 2|3] y, para el aumento mediante volteo horizontal, un flip_idx. Las etiquetas son filas de texto YOLO-pose: un ID de clase, una caja normalizada y después K tripletas de puntos clave (x, y, v) con una visibilidad v en {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 es YOLOv9 con una cuarta escala de detección en stride 4. YOLOv9 estándar detecta en strides 8/16/32, por lo que los objetos de menos de ~16 px quedan por debajo de su cuadrícula más fina; la cabeza P2 captura el intervalo de 4-16 px que predomina en imágenes aéreas y de drones.

En una prueba A/B controlada con VisDrone (misma receta, misma resolución, misma inicialización; el único cambio fue la cabeza P2), el AP de objetos pequeños mejoró un +49 % respecto a YOLOv9 estándar del mismo tamaño. Añadir una mayor resolución de entrenamiento y el tamaño s, más grande, casi duplicó el AP de objetos pequeños en todo el proyecto:

VisDrone2019-DET val (548 imágenes), pycocotools, una sola semilla; considera ±1 punto como ruido.

Versión preliminar de investigación de VisDrone

Se publica un checkpoint entrenado como LibreYOLO9P2s-visdrone. La familia está fusionada en dev, pero todavía no forma parte de una versión de PyPI, así que instálala desde el código fuente hasta la próxima versión.

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)

Cuándo usarlo y cuándo no

Adapta la arquitectura al entorno. En datos similares a COCO ("pequeño" significa 16-32 px), la cabeza P2 no ayuda; YOLOv9 estándar es la mejor opción en ese caso. Elige YOLO9-P2 cuando tus objetos midan menos de ~16 px: imágenes de drones y aéreas, CCTV distante o teselas de satélite. La escala adicional prácticamente duplica el cómputo y el número de anchors. Es el precio de la cuadrícula con stride 4.

Entrenar tu propio modelo

YOLO9-P2 se inicializa por transferencia a partir de checkpoints de detección de YOLOv9 estándar: se cargan el backbone, el neck compartido y las torres de cabeza existentes; los nuevos módulos P2 empiezan desde cero. La receta siguiente recoge lo que aprendimos por las malas con datos de objetos diminutos:

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
)

Los adaptadores de estilo LoRA permiten hacer fine-tuning del backbone transformer de RF-DETR entrenando un pequeño conjunto de matrices de bajo rango mientras los pesos base permanecen congelados. Esto reduce la memoria del optimizador y de los gradientes, lo que resulta ideal para adaptar un checkpoint potente a un dominio nuevo con hardware modesto.

Activación

Toda la API pública se reduce a un solo flag en train(). No hay controles de rango, alfa o módulo de destino que ajustar; la receta está fijada en una configuración bien probada. Internamente, la implementación usa DoRA (LoRA con descomposición de pesos, rango 16) aplicado a las proyecciones de consulta, clave y valor de la atención de 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 y exportación

• Los checkpoints de entrenamiento conservan los tensores de los adaptadores, y la configuración registra que se usó LoRA, por lo que cargar y reanudar reconstruye automáticamente el grafo de adaptadores.
• La cabeza de detección siempre permanece entrenable, por lo que puedes adaptarla a un nuevo número de clases.
• export() vuelve a fusionar los adaptadores en pesos densos. Los modelos exportados son normales y no incluyen ninguna dependencia de peft.
• LoRA es exclusivo de RF-DETR; pasar lora=True a otras familias genera un error claro.

Estado actual de cada función. Todo lo que aparece aquí es experimental; esta tabla muestra la situación real.