Esportare in ONNX (e verificare la parità)

Esportazione#

from ultralytics import YOLO

model = YOLO("yolo26n.pt")  # oppure runs/detect/pills_v1/weights/best.pt
model.export(format="onnx", dynamic=True)  # scrive yolo26n.onnx accanto ai pesi

Il log mostra l'opset scelto (opset 18 con onnx 1.23) e conferma che onnxslim ha semplificato il grafo. Ecco le opzioni che modificano il comportamento, tratte dalla modalità Export:

Con il valore predefinito nms=None, l'esportazione restituisce le predizioni grezze e il wrapper Ultralytics esegue NMS, esattamente come PyTorch.

Verifica la parità su un'immagine nota#

Esegui la stessa immagine con entrambi i modelli e confronta ogni aspetto:

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

Ordinando entrambi gli insiemi per confidence, abbini gli stessi oggetti; le ultime due righe confrontano quindi ogni rilevazione con la corrispondente. Ora esegui il test due volte, una come mostrato e una rimuovendo dynamic=True:

L'esportazione statica non è difettosa. PyTorch adatta l'immagine verticale bus.jpg alla forma minima allineata allo stride, 640×480 (altezza × larghezza), mentre un grafo statico 640×640 deve aggiungere padding grigio fino a ottenere un quadrato. Il padding diverso produce predizioni leggermente diverse. Per confrontare condizioni equivalenti, esporta con dynamic=True oppure esegui la parte PyTorch con rect=False, in modo che aggiunga padding fino al quadrato completo come fa l'esportazione statica (vedi forma fissa e rettangolo minimo); con rect=False, anche l'esportazione statica corrisponde con una differenza di 0.0000.

Convalida entrambi i file#

Una sola immagine permette di rilevare gli errori più evidenti; la convalida individua quelli più sottili. Usa lo stesso batch per entrambi, così il preprocessing corrisponde:

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

Entrambi riportano mAP50-95 0.654 in questo caso. COCO8 verifica la pipeline, non il modello; sul tuo set di convalida, esamina qualsiasi differenza superiore a 0,5 punti. Ecco la verifica completa:

Chiama direttamente ONNX Runtime#

Spesso i servizi in produzione saltano il wrapper Ultralytics e chiamano direttamente il motore di inferenza. In tal caso, il preprocessing è responsabilità tua e deve corrispondere esattamente a quello di Ultralytics. Con nms=False, l'esportazione YOLO26 restituisce le rilevazioni finali, quindi non serve codice 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 autobus (classe 5) e quattro persone (classe 0), con YOLO(path)(img) corrispondente al pixel. In questo caso l'autobus ha una confidence di 0,93, mentre con l'esportazione predefinita è 0,88, perché nms=False seleziona una head diversa; confronta file esportati con lo stesso valore di nms.

Insidie#