Exportación de modelos con Ultralytics YOLO#

Exportar un modelo YOLO26 al formato ONNX es sencillo con Ultralytics. Ofrece métodos de exportación de modelos tanto con Python como con CLI.

from ultralytics import YOLO

# Cargar un modelo
model = YOLO("yolo26n.pt")  # carga un modelo oficial
model = YOLO("path/to/best.pt")  # carga un modelo entrenado a medida

# Exporta el modelo
model.export(format="onnx")

Para obtener más información sobre el proceso, incluidas opciones avanzadas como la gestión de distintos tamaños de entrada, consulta la guía de integración de ONNX.

Usar TensorRT para exportar modelos ofrece mejoras de rendimiento significativas. Los modelos YOLO26 exportados a TensorRT pueden alcanzar hasta 5 veces más velocidad en GPU, por lo que son ideales para aplicaciones de inferencia en tiempo real.

• Versatilidad: Optimiza los modelos para una configuración de hardware específica.
• Velocidad: Consigue una inferencia más rápida mediante optimizaciones avanzadas.
• Compatibilidad: Integra fácilmente los modelos con hardware de NVIDIA.

Para obtener más información sobre la integración de TensorRT, consulta la guía de integración de TensorRT.

La cuantización INT8 es una forma excelente de comprimir el modelo y acelerar la inferencia, sobre todo en dispositivos periféricos. Así puedes activar la cuantización INT8:

from ultralytics import YOLO

model = YOLO("yolo26n.pt")  # Cargar un modelo
model.export(format="onnx", quantize=8, data="coco8.yaml")

La cuantización INT8 puede aplicarse a formatos como ONNX, TensorRT, OpenVINO, CoreML, Rockchip RKNN y AMD Xilinx. Para obtener resultados de cuantización óptimos, proporciona un conjunto de datos representativo mediante el parámetro data. Consulta Opciones de cuantización para ver los valores aceptados de quantize y los formatos compatibles.

El tamaño de entrada dinámico permite que el modelo exportado gestione imágenes de distintas dimensiones, lo que ofrece flexibilidad y optimiza la eficiencia de procesamiento para diferentes casos de uso. Al exportar a formatos como ONNX o TensorRT, activar el tamaño de entrada dinámico garantiza que el modelo se adapte sin problemas a distintas formas de entrada.

Para activar esta función, usa la marca dynamic=True durante la exportación:

from ultralytics import YOLO

model = YOLO("yolo26n.pt")
model.export(format="onnx", dynamic=True)

El tamaño de entrada dinámico resulta especialmente útil en aplicaciones donde las dimensiones de entrada pueden variar, como el procesamiento de vídeo o el manejo de imágenes procedentes de distintas fuentes.

De forma predeterminada, los modelos PyTorch y las exportaciones dinámicas usan relleno con rectángulo mínimo, mientras que las exportaciones estáticas rellenan hasta imgsz completo, por lo que las detecciones cercanas al umbral de confianza pueden diferir. Usa rect=False para que la inferencia nativa coincida con una exportación estática, o exporta con dynamic=True cuando sea compatible.

Comprender y configurar los argumentos de exportación es fundamental para optimizar el rendimiento del modelo:

• format: El formato de destino del modelo exportado (p. ej., onnx, torchscript, saved_model).
• imgsz: Tamaño de imagen deseado para la entrada del modelo (p. ej., 640 o (height, width)).
• quantize: Precisión de cuantización, como 8/"int8", 16/"fp16", 32/"fp32" o los esquemas mixtos de pesos/activaciones "w8a16" y "w8a32" (INT8 dinámico de LiteRT) en los formatos compatibles. Consulta Opciones de cuantización.
• dynamic: Acepta tamaños de entrada variables en los formatos que admiten formas dinámicas, como ONNX, OpenVINO y TensorRT.
• nms: Selecciona salidas sin procesar para NMS externo (None), NMS integrado (True) o la cabeza sin NMS (False).
• device: Dispositivo usado para trazar el modelo durante la exportación, como cpu o 0 para la primera GPU CUDA; TorchScript FP16 requiere una GPU.

Para implementar en plataformas de hardware específicas, plantéate usar formatos de exportación especializados, como TensorRT para GPU NVIDIA, CoreML para dispositivos Apple o Edge TPU para dispositivos Google Coral.

Al exportar un modelo YOLO a formatos como ONNX o TensorRT, la estructura del tensor de salida depende de la tarea del modelo. Comprender estas salidas es importante para implementar inferencias personalizadas.

Para los modelos de detección YOLO26 (p. ej., yolo26n.pt) exportados con nms=False, los formatos compatibles generan una salida sin NMS con una forma como (batch_size, max_detections, 6) y [x1, y1, x2, y2, confidence, class_id] valores. Con el valor predeterminado max_det=300, suele ser (batch_size, 300, 6). Algunos formatos restringidos vuelven automáticamente al diseño de salida tradicional cuando no admiten operadores de extremo a extremo.

De forma predeterminada (nms=None), los modelos de detección, incluido YOLO26, exportan predicciones sin procesar de uno a muchos: la salida suele ser un único tensor con una forma como (batch_size, 4 + num_classes, num_predictions), donde los canales representan las coordenadas de las cajas y las puntuaciones por clase, y num_predictions depende de la resolución de entrada de la exportación (y puede ser dinámica). La guía de detección de extremo a extremo explica qué formatos conservan la salida de extremo a extremo.

Para los modelos de segmentación (p. ej., yolo26n-seg.pt), normalmente obtendrás dos salidas: el primer tensor, con una forma como (batch_size, 4 + num_classes + mask_dim, num_predictions) (cajas, puntuaciones por clase y coeficientes de máscara), y el segundo tensor, con una forma como (batch_size, mask_dim, proto_h, proto_w), que contiene prototipos de máscara que se utilizan con los coeficientes para generar máscaras de instancia. Los tamaños dependen de la resolución de entrada de la exportación (y pueden ser dinámicos).

Para los modelos de pose (p. ej., yolo26n-pose.pt), el tensor de salida suele tener una forma como (batch_size, 4 + num_classes + keypoint_dims, num_predictions), donde keypoint_dims depende de la especificación de pose (p. ej., del número de puntos clave y de si se incluye la confianza), y num_predictions depende de la resolución de entrada de la exportación (y puede ser dinámica).

Los ejemplos de inferencia con ONNX muestran cómo procesar estas salidas para cada tipo de modelo.

Ultralytics no ofrece actualmente una API de inferencia de C++ específica para modelos YOLO. Para implementaciones en C++, exporta el modelo a un formato de ejecución como ONNX, TensorRT, TorchScript o MNN; después, carga el artefacto exportado con la API nativa de C++ de ese entorno de ejecución.

Por ejemplo, exporta un modelo de detección con yolo export model=yolo26n.pt format=onnx y ejecuta el archivo .onnx con ONNX Runtime C++, o exporta con format=engine y ejecuta el motor de TensorRT desde una aplicación de C++ de TensorRT. Si utilizas un posprocesamiento personalizado en C++, adapta el diseño del tensor de salida a la tarea y a la configuración de exportación; las exportaciones de detección YOLO26 predeterminadas devuelven tensores de predicción sin procesar que requieren NMS externo. Exporta con nms=False para obtener detecciones sin NMS con forma (batch, max_det, 6), o con nms=True para integrar NMS en los formatos compatibles.

Al exportar con quantize=16 (FP16) o quantize=8 (INT8), la mayoría de los tensores se convierten a una precisión menor para reducir el tamaño del modelo y mejorar el rendimiento. Sin embargo, cuando nms=False está activado, el posprocesamiento (incluidos los índices de clase) se integra directamente en el grafo exportado.

El tensor output0 contiene índices de clase, que internamente se representan como valores de coma flotante. FP16 no puede representar de forma fiable valores enteros superiores a 2048 debido a la limitada precisión de su mantisa. Para evitar posibles pérdidas de precisión o ID de clase incorrectos, output0 se mantiene intencionadamente en FP32.

Si necesitas salidas totalmente en FP16, exporta con nms=None en una GPU y realiza el posprocesamiento externamente. Las exportaciones ONNX FP16 en CPU mantienen las entradas y salidas en FP32 en cualquier caso; solo convierten el grafo interno.