API del modelo

Construcción

La factoría devuelve una instancia de la clase de familia. Construir esa clase directamente admite los mismos argumentos, salvo que size es obligatorio:

Family(model_path, size, nb_classes=80, device="auto", task=None, **kwargs)

device="auto" selecciona CUDA cuando está disponible, luego MPS y luego CPU. Un entero o una cadena de dígitos se interpreta como un ordinal de CUDA, así que device=0 y device="0" significan ambos cuda:0. task se valida contra el SUPPORTED_TASKS de la familia. Pasar model_path=None construye la arquitectura y la deja en modo de entrenamiento; pasar un dict carga ese state dict directamente.

predict y __call__

predict es un alias de __call__.

model(
    source=None,
    *,
    conf=0.25,
    iou=0.45,
    imgsz=None,
    device=None,
    classes=None,
    max_det=300,
    augment=False,
    save=False,
    batch=1,
    stream=False,
    stream_buffer=False,
    vid_stride=1,
    show=False,
    output_path=None,
    color_format="auto",
    tiling=False,
    overlap_ratio=0.2,
    output_file_format=None,
    cuda_graph=False,
    **kwargs,
)

Una fuente de una sola imagen devuelve un Results. Una lista, una tupla o un directorio devuelven una lista de ellos, y stream=True devuelve un generador en todos los casos.

Las fuentes de streaming en vivo no tienen fin y requieren stream=True. tiling y augment no se pueden combinar. El aumento de datos en tiempo de test lanza un error para las tareas embed, point y edge.

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreYOLO9t.pt") model.info()result = model(SAMPLE_IMAGE, conf=0.25, iou=0.45) print(result.boxes.xyxy)print(result.speed)

Con batch > 1, las familias cuyo SUPPORTS_BATCHED_PREDICT es verdadero ejecutan una única pasada hacia delante apilada por bloque; batch=1 mantiene una pasada por imagen.

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreYOLO9t.pt") # stream=True devuelve un generador, un Results por frame o imagen.for result in model([SAMPLE_IMAGE, SAMPLE_IMAGE], stream=True):    print(len(result))

embed

model.embed(source=None, **kwargs) -> torch.Tensor

Un envoltorio de conveniencia sobre predict que apila cada fila de embedding en un único tensor (N_total, D). El modelo tiene que haberse construido con task="embed"; en caso contrario lanza NotImplementedError.

track

model.track(
    source,
    *,
    track_conf=0.25,
    iou=0.45,
    imgsz=None,
    classes=None,
    max_det=300,
    save=False,
    show=False,
    vid_stride=1,
    output_path=None,
    tracker="bytetrack",
    tracker_config=None,
    augment=False,
    **tracker_kwargs,
) -> Generator[Results, None, None]

Emite un Results por frame con track_id asignado. tracker es "bytetrack", "botsort", "ocsort" o "deepocsort", y se ignora cuando se pasa tracker_config, porque el tipo de configuración selecciona el tracker. track_conf se corresponde con track_high_thresh en ByteTrack y BoT-SORT y con det_thresh en OC-SORT y Deep OC-SORT. output_path es por defecto runs/track/<video_stem>.mp4.

val

model.val(
    data=None,
    batch=16,
    imgsz=None,
    conf=0.001,
    iou=0.6,
    workers=4,
    allow_download_scripts=False,
    device=None,
    split="val",
    augment=False,
    save_json=False,
    verbose=True,
    *,
    plots=None,
    **kwargs,
) -> Dict

Devuelve un diccionario de métricas cuyas claves dependen de la tarea; la detección devuelve metrics/precision, metrics/recall, metrics/mAP50 y metrics/mAP50-95. imgsz acepta un entero cuadrado o una tupla (height, width) y por defecto usa el tamaño de entrada nativo del modelo. plots es un alias de save_plots. allow_download_scripts controla el Python embebido que un YAML de dataset puede llevar en su campo download.

faster_coco_eval se acepta a través de **kwargs y por defecto vale True, con vuelta a pycocotools cuando el paquete no está instalado. El backend que se ejecutó se indica en model.last_eval_backend.

La validación con aumento de datos lanza un error para las tareas obb y pose.

train

train se define por familia, así que sus argumentos varían. Dos comportamientos son comunes, porque la clase base envuelve el train de cada familia:

• cfg= toma la ruta de un YAML cuyas claves se fusionan en la llamada. Los argumentos con nombre explícitos ganan al archivo.
• pretrained=False en una familia del grupo de cobertura g0 o g1 reinicializa el modelo desde cero antes de entrenar, y no se puede combinar con resume=True.

Qué parámetros de aumento de datos respeta realmente cada familia es una cuestión de cada una; consulta la matriz de aumento de datos.

export

model.export(format="onnx", **kwargs) -> str

Devuelve la ruta del artefacto escrito. format se resuelve a través del registro de exportadores, donde engine es un alias de tensorrt y litert es un alias de tflite. Argumentos comunes a todos los exportadores:

Las combinaciones bloqueadas lanzan NotImplementedError en la comprobación previa, antes del trazado. La cobertura y sus reglas están en la página de la matriz de exportación. Cuando hay adaptadores LoRA activos, se pliegan en pesos densos, y esa fusión ocurre solo después de todos los rechazos posibles de la petición.

save

model.save(path) -> str

Escribe un checkpoint de LibreYOLO con esquema v1.0: el state dict más los metadatos descritos en el esquema de checkpoint. Un modelo cuantizado lleva además su manifiesto quant, de modo que LibreYOLO(path) restaura la estructura cuantizada y las escalas.

quantize, quant_info y dequantize

model.quantize(
    recipe,
    calib="coco128.yaml",
    samples=128,
    batch=8,
    algorithm="auto",
    keep_high_precision=None,
    allow_download_scripts=False,
    verbose=True,
)

Cuantiza in situ y devuelve el modelo. recipe es uno de los casts fp16 y bf16, las recetas de Conv y Linear int8 y fp8, o las recetas solo para Linear w4a16, w4a8, nvfp4, mxfp4 e int2, que soportan las familias transformer como RF-DETR. int2 requiere QAT. calib toma una ruta a data.yaml o el nombre de un dataset integrado y lee las imágenes solo hacia delante; las etiquetas nunca se leen. Pasa calib=None para saltarte la calibración. algorithm es "minmax", "percentile" o "auto".

model.quant_info() devuelve el resumen del estado de cuantización, o None para un modelo float. model.dequantize() restaura los módulos float in situ manteniendo los pesos maestros entrenados con cuantización, que es el puente de QAT a export(format="onnx", int8=True, data=...).

info y capas

model.info(detailed=False, verbose=True) -> Dict[str, Any]
model.get_available_layer_names() -> List[str]
model.get_distill_config() -> Dict

info devuelve un diccionario compatible con JSON y registra un resumen legible cuando verbose es verdadero. get_available_layer_names lista las capas que puede nombrar una configuración de destilación o de extracción de características.

Grafos CUDA

Disponible en las familias cuyo atributo de clase SUPPORTS_CUDA_GRAPH es verdadero. La reproducción es idéntica bit a bit a la ejecución eager.

model.capture_graph(imgsz=None, batch=1, dtype=None) -> None
model.cuda_graph_scope(mode=True)          # gestor de contexto
model.graph_info() -> Dict[str, Any]
model.release_graphs() -> None

Un grafo capturado solo es válido para la forma exacta con la que se capturó, así que batch e imgsz deben coincidir con la llamada posterior a predict. capture_graph saca el coste de la captura de la primera petición. mode acepta True o "on" para capturar en el primer uso, "auto" para esperar a que una forma se repita, y False para no hacer nada. capture_graph lanza NotImplementedError cuando la familia no se ha adherido y CudaGraphUnavailable cuando la captura falla.

Dispositivo y dtype

Los objetos Results llevan .to(), .cpu(), .cuda() y .numpy(); consulta Tipos de Results. El modelo en sí se mueve pasando device= a predict, o en el momento de la construcción.