Exportar a ONNX (y verificar la paridad)

Exportar#

from ultralytics import YOLO

model = YOLO("yolo26n.pt")  # or runs/detect/pills_v1/weights/best.pt
model.export(format="onnx", dynamic=True)  # escribe yolo26n.onnx junto a los pesos

El registro muestra el opset elegido (opset 18 con onnx 1.23) y que onnxslim ha simplificado el grafo. Estas son las opciones que modifican el comportamiento, disponibles en el modo Export:

Con el valor predeterminado de nms=None, la exportación devuelve predicciones sin procesar y el wrapper de Ultralytics ejecuta NMS, igual que PyTorch.

Comprueba la paridad con una imagen conocida#

Procesa la misma imagen con ambos modelos y compáralo todo:

from ultralytics import YOLO

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

img = "https://ultralytics.com/images/bus.jpg"
a = pt(img, verbose=False)[0].boxes
b = onnx(img, verbose=False)[0].boxes

ia, ib = a.conf.argsort(descending=True), b.conf.argsort(descending=True)
print(f"boxes:         PyTorch {len(a)}  ONNX {len(b)}")
print(f"same classes:  {a.cls[ia].tolist() == b.cls[ib].tolist()}")
print(f"max conf diff: {(a.conf[ia] - b.conf[ib]).abs().max():.4f}")
print(f"max xyxy diff: {(a.xyxy[ia] - b.xyxy[ib]).abs().max():.2f} px")

Ordenar ambos conjuntos por confianza empareja los mismos objetos, así que las dos últimas líneas comparan cada detección con su equivalente. Ahora ejecútalo dos veces: una como se muestra y otra sin dynamic=True:

La exportación estática no está rota. PyTorch adapta la imagen vertical bus.jpg al menor tamaño alineado con el stride, 640×480 (alto × ancho), mientras que un grafo estático de 640×640 tiene que rellenarla hasta formar un cuadrado con franjas grises. El relleno distinto produce predicciones ligeramente diferentes. Para comparar en igualdad de condiciones, exporta con dynamic=True o ejecuta PyTorch con rect=False para que rellene hasta formar el cuadrado completo, como hace la exportación estática (consulta forma fija frente a rectángulo mínimo); con rect=False, la exportación estática también coincide con una diferencia de 0,0000.

Valida ambos archivos#

Una imagen detecta errores graves; la validación detecta los más sutiles. Usa el mismo batch en ambos para que el preprocesamiento coincida:

yolo val model=yolo26n.pt data=coco8.yaml batch=1
yolo val model=yolo26n.onnx data=coco8.yaml batch=1

Ambos muestran mAP50-95 0.654 aquí. COCO8 demuestra que la canalización funciona, no que el modelo sea correcto; en tu propio conjunto de validación, investiga cualquier diferencia superior a 0,5 puntos. Comprobación completa:

Llama directamente a ONNX Runtime#

A menudo, los servicios de producción omiten el wrapper de Ultralytics y llaman directamente al motor de inferencia. En ese caso, el preprocesamiento es responsabilidad tuya y debe coincidir exactamente con el de Ultralytics. Con nms=False, la exportación de YOLO26 devuelve las detecciones finales, así que no hace falta código NMS:

import cv2
import numpy as np
import onnxruntime as ort

from ultralytics import YOLO
from ultralytics.utils.downloads import safe_download

path = YOLO("yolo26n.pt").export(format="onnx", nms=False)  # NMS-free head: output (1, 300, 6)
session = ort.InferenceSession(path, providers=["CPUExecutionProvider"])  # put CUDAExecutionProvider first on GPU
name = session.get_inputs()[0].name

# Preprocess like Ultralytics: letterbox to 640x640 with gray (114) padding, BGR->RGB, 0-1, NCHW
im = cv2.imread(safe_download("https://ultralytics.com/images/bus.jpg"))
h, w = im.shape[:2]
r = 640 / max(h, w)
nh, nw = round(h * r), round(w * r)
top, left = (640 - nh) // 2, (640 - nw) // 2
canvas = np.full((640, 640, 3), 114, np.uint8)
canvas[top : top + nh, left : left + nw] = cv2.resize(im, (nw, nh), interpolation=cv2.INTER_LINEAR)
x = canvas[..., ::-1].transpose(2, 0, 1)[None].astype(np.float32) / 255

(out,) = session.run(None, {name: x})
det = out[0][out[0][:, 4] > 0.25]  # rows: x1, y1, x2, y2, score, class
det[:, [0, 2]] = ((det[:, [0, 2]] - left) / r).clip(0, w)  # undo padding and scale
det[:, [1, 3]] = ((det[:, [1, 3]] - top) / r).clip(0, h)
for x1, y1, x2, y2, score, cls in det:
    print(f"class {int(cls):2d}  score {score:.2f}  box [{x1:.0f}, {y1:.0f}, {x2:.0f}, {y2:.0f}]")

class  5  score 0.93  box [6, 229, 807, 749]
class  0  score 0.92  box [47, 399, 237, 902]
class  0  score 0.90  box [223, 405, 345, 863]
class  0  score 0.86  box [669, 391, 810, 880]
class  0  score 0.52  box [0, 554, 65, 874]

Un autobús (clase 5) y cuatro personas (clase 0), lo que coincide al píxel con YOLO(path)(img). La puntuación del autobús es 0,93 aquí y 0,88 con la exportación predeterminada porque nms=False selecciona otro cabezal; compara archivos exportados con el mismo valor de nms.

Errores habituales#