Exportar para ONNX (e verificar a paridade)

Exportação#

from ultralytics import YOLO

model = YOLO("yolo26n.pt")  # or runs/detect/pills_v1/weights/best.pt
model.export(format="onnx", dynamic=True)  # grava yolo26n.onnx ao lado dos pesos

O registo mostra o opset escolhido (opset 18 com onnx 1.23) e que o onnxslim simplificou o grafo. As opções que alteram o comportamento, no modo Export:

Com o valor predefinido nms=None, a exportação devolve previsões em bruto e o wrapper da Ultralytics executa NMS, tal como no PyTorch.

Verifica a paridade numa imagem conhecida#

Executa a mesma imagem nos dois modelos e compara tudo:

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 os conjuntos por confiança emparelha os mesmos objetos, por isso as duas últimas linhas comparam cada deteção com a sua correspondente. Agora executa-o duas vezes, uma como mostrado e outra sem dynamic=True:

A exportação estática não está avariada. O PyTorch ajusta a imagem vertical bus.jpg à menor forma alinhada pela passada, 640×480 (altura × largura), enquanto um grafo estático de 640×640 tem de a preencher até formar um quadrado, com barras cinzentas. O preenchimento diferente produz previsões ligeiramente diferentes. Para comparar em condições equivalentes, exporta com dynamic=True ou executa o lado do PyTorch com rect=False para que preencha até ao quadrado completo, tal como a exportação estática (consulta forma fixa vs retângulo mínimo); com rect=False, a exportação estática também corresponde, com uma diferença de 0.0000.

Valida ambos os ficheiros#

Uma imagem deteta erros grosseiros; a validação deteta os mais subtis. Usa o mesmo batch para ambos, para que o pré-processamento corresponda:

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

Ambos indicam mAP50-95 0.654 neste caso. O COCO8 valida o pipeline, não o modelo; no teu próprio conjunto de validação, investiga qualquer diferença superior a 0.5 pontos. A verificação completa:

Chama diretamente o ONNX Runtime#

Os serviços de produção muitas vezes dispensam o wrapper da Ultralytics e chamam diretamente o motor de inferência. Nesse caso, o pré-processamento fica a teu cargo e tem de corresponder exatamente ao da Ultralytics. Com nms=False, a exportação do YOLO26 devolve as deteções finais, por isso não é necessário 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]

Um autocarro (classe 5) e quatro pessoas (classe 0), correspondendo ao YOLO(path)(img) até ao píxel. O autocarro tem uma pontuação de 0.93 neste caso e de 0.88 com a exportação predefinida, porque nms=False seleciona um cabeçalho diferente; compara ficheiros exportados com o mesmo valor de nms.

Armadilhas#