Ultralytics ile YOLO Olmayan PyTorch Modelleri Nasıl Dışa Aktarılır#

Ultralytics, birden fazla arka ucu tek ve tutarlı bir arayüz altında toplayan bağımsız dışa aktarma araçlarını ultralytics.utils.export altında sunar. Herhangi bir torch.nn.Module modelini; timm görüntü modelleri, torchvision sınıflandırıcıları ve dedektörleri veya kendi özel mimarilerini, her arka ucu ayrı ayrı öğrenmek zorunda kalmadan ONNX, TorchScript, OpenVINO, CoreML, NCNN, PaddlePaddle, MNN, ExecuTorch ve TensorFlow SavedModel formatlarına dışa aktarabilirsin.

PyTorch modellerini üretime (production) taşımak genellikle her hedef için farklı bir dışa aktarıcı yönetmek anlamına gelir: ONNX için torch.onnx.export, Apple cihazları için coremltools, TensorFlow için onnx2tf, NCNN için pnnx vb. Her aracın kendi API'si, bağımlılık tuhaflıkları ve çıktı kuralları vardır. Bu araçlar, bunları tek bir çağrı deseninde birleştirir.

YOLO Olmayan Dışa Aktarma İşlemleri İçin Neden Ultralytics Kullanmalısın?#

• 10 formatta tek bir API: düzinelercesi yerine tek bir çağırma kuralı öğren.
• Ortak araç yüzeyi: Dışa aktarma yardımcı programları ultralytics.utils.export altında bulunur; bu nedenle arka uç paketleri yüklendikten sonra biçimler arasında aynı çağrı desenini koruyabilirsin.
• YOLO dışa aktarmalarıyla aynı kod yolu: aynı yardımcılar her Ultralytics YOLO dışa aktarma işlemini destekler.
• FP16 ve INT8 niceleme (quantization): bunu destekleyen formatlar (OpenVINO, CoreML, MNN, NCNN) için yerleşik olarak gelir.
• CPU üzerinde çalışır: dışa aktarma adımının kendisi için GPU gerekmez, bu sayede herhangi bir dizüstü bilgisayarda yerel olarak çalıştırabilirsin.

Hızlı Başlangıç#

En hızlı yol, hiç YOLO kodu yazmadan ve pip install ultralytics onnx timm dışında herhangi bir kurulum gerektirmeden ONNX formatına iki satırda dışa aktarım yapmaktır:

import timm
import torch

from ultralytics.utils.export import torch2onnx

model = timm.create_model("resnet18", pretrained=True).eval()
torch2onnx(model, torch.randn(1, 3, 224, 224), output_file="resnet18.onnx")

Desteklenen Dışa Aktarma Formatları#

torch2* fonksiyonları standart bir torch.nn.Module ve örnek bir girdi tensörü alır. MNN, TF SavedModel ve TF Frozen Graph, ara bir ONNX veya Keras yapısından geçer. Her iki durumda da YOLO'ya özgü öznitelikler gerekmez.

Adım Adım Örnekler#

Aşağıdaki her örnek, değerlendirme modundaki timm'den alınmış önceden eğitilmiş bir ResNet-18 ile aynı kurulumu kullanır:

import timm
import torch

model = timm.create_model("resnet18", pretrained=True).eval()
im = torch.randn(1, 3, 224, 224)

ONNX'e Dışa Aktar#

from ultralytics.utils.export import torch2onnx

torch2onnx(model, im, output_file="resnet18.onnx")

Dinamik yığın boyutu (batch size) için bir dynamic sözlüğü aktar:

torch2onnx(model, im, output_file="resnet18_dyn.onnx", dynamic={"images": {0: "batch_size"}})

Varsayılan opset 14 ve varsayılan girdi adı "images" değeridir. opset, input_names veya output_names argümanlarıyla bunları geçersiz kılabilirsin.

TorchScript'e Dışa Aktar#

Ekstra bağımlılık gerekmez. Kaputun altında torch.jit.trace kullanır.

from ultralytics.utils.export import torch2torchscript

torch2torchscript(model, im, output_file="resnet18.torchscript")

OpenVINO'ya Dışa Aktar#

from ultralytics.utils.export import torch2openvino

ov_model = torch2openvino(model, im, output_dir="resnet18_openvino_model")

Dizin, sabit adlandırılmış bir model.xml ve model.bin çifti içerir:

resnet18_openvino_model/
├── model.xml
└── model.bin

Dinamik girdi şekilleri için dynamic=True, FP16 için quantize=16 veya INT8 nicelemesi için quantize=8 aktar. INT8 ayrıca bir calibration_dataset argümanı gerektirir.

openvino>=2024.0.0 (veya macOS 15.4+ üzerinde >=2025.2.0) ve torch>=2.1 gerektirir.

CoreML'ye Dışa Aktar#

import coremltools as ct

from ultralytics.utils.export import torch2coreml

inputs = [ct.TensorType("input", shape=(1, 3, 224, 224))]
ct_model = torch2coreml(model, inputs, im, classifier_names=None, output_file="resnet18.mlpackage")

Sınıflandırma modelleri için, CoreML modeline bir sınıflandırma başlığı eklemek üzere classifier_names argümanına sınıf adlarının bir listesini aktar.

coremltools>=9.0, torch>=1.11 ve numpy<=2.3.5 gerektirir. Windows'ta desteklenmez.

TensorFlow SavedModel'e Dışa Aktar#

TF SavedModel dışa aktarımı, ara adım olarak ONNX üzerinden geçer:

from ultralytics.utils.export import onnx2saved_model, torch2onnx

torch2onnx(model, im, output_file="resnet18.onnx")
keras_model = onnx2saved_model("resnet18.onnx", output_dir="resnet18_saved_model")

Fonksiyon bir Keras modeli döndürür ve ayrıca çıktı dizini içinde TFLite dosyaları (.tflite) oluşturur:

resnet18_saved_model/
├── saved_model.pb
├── variables/
├── resnet18_float32.tflite
├── resnet18_float16.tflite
└── resnet18_int8.tflite

Gereksinimler:

• tensorflow>=2.0.0,<=2.19.0
• onnx2tf>=1.26.3,<1.29.0
• tf_keras<=2.19.0
• sng4onnx>=1.0.1
• onnx_graphsurgeon>=0.3.26
• macOS üzerinde ai-edge-litert>=1.2.0,<1.4.0 (diğer platformlarda ai-edge-litert>=1.2.0)
• onnxslim>=0.1.82
• onnx>=1.12.0,<2.0.0
• protobuf>=5

TensorFlow Frozen Graph'a Dışa Aktar#

Yukarıdaki SavedModel dışa aktarımından devam ederek, döndürülen keras_model nesnesini dondurulmuş bir .pb grafiğine dönüştür:

from pathlib import Path

from ultralytics.utils.export import keras2pb

keras2pb(keras_model, output_file=Path("resnet18_saved_model/resnet18.pb"))

NCNN'e Dışa Aktar#

from ultralytics.utils.export import torch2ncnn

torch2ncnn(model, im, output_dir="resnet18_ncnn_model")

Dizin, Python sarmalayıcısı ile birlikte sabit isimli param ve bin dosyalarını içerir:

resnet18_ncnn_model/
├── model.ncnn.param
├── model.ncnn.bin
└── model_ncnn.py

torch2ncnn(), ilk kullanımda ncnn ve pnnx varlığını kontrol eder.

MNN'e Dışa Aktar#

MNN dışa aktarımı, girdi olarak bir ONNX dosyası gerektirir. Önce ONNX'e dışa aktar, ardından dönüştür:

from ultralytics.utils.export import onnx2mnn, torch2onnx

torch2onnx(model, im, output_file="resnet18.onnx")
onnx2mnn("resnet18.onnx", output_file="resnet18.mnn")

FP16 için quantize=16 ve INT8 nicelemesi için quantize=8 destekler. MNN>=2.9.6 ve torch>=1.10 gerektirir.

PaddlePaddle'a Dışa Aktar#

from ultralytics.utils.export import torch2paddle

torch2paddle(model, im, output_dir="resnet18_paddle_model")

Dizin, PaddlePaddle modelini ve parametre dosyalarını içerir:

resnet18_paddle_model/
├── model.pdmodel
└── model.pdiparams

x2paddle ve platformun için doğru PaddlePaddle dağıtımını gerektirir:

• CUDA üzerinde paddlepaddle-gpu>=3.0.0,<3.3.0
• ARM64 CPU üzerinde paddlepaddle==3.0.0
• Diğer CPU'larda paddlepaddle>=3.0.0,<3.3.0

NVIDIA Jetson üzerinde desteklenmez.

ExecuTorch formatına dışa aktar#

from ultralytics.utils.export import torch2executorch

torch2executorch(model, im, output_dir="resnet18_executorch_model")

Dışa aktarılan .pte dosyası çıktı dizininin içine kaydedilir:

resnet18_executorch_model/
└── model.pte

torch>=2.9.0 ve eşleşen bir ExecuTorch çalışma zamanı (pip install executorch) gerektirir. Çalışma zamanı kullanımı için ExecuTorch entegrasyonuna göz at.

Dışa Aktarılan Modelini Doğrula#

Dışa aktardıktan sonra, üretime almadan önce orijinal PyTorch modeliyle sayısal eşdeğerliği doğrula. ultralytics.nn.backends içinden ONNXBackend ile yapılacak hızlı bir test, çıktıları karşılaştırır ve izleme veya niceleme hatalarını erken aşamada tespit eder:

import numpy as np
import timm
import torch

from ultralytics.nn.backends import ONNXBackend

model = timm.create_model("resnet18", pretrained=True).eval()
im = torch.randn(1, 3, 224, 224)
with torch.no_grad():
    pytorch_output = model(im).numpy()

onnx_model = ONNXBackend("resnet18.onnx", device=torch.device("cpu"))
onnx_output = onnx_model(im)[0]

diff = np.abs(pytorch_output - onnx_output).max()
print(f"Max difference: {diff:.6f}")  # typically ~1e-5, well under 1e-4 for FP32

Diğer çalışma zamanları için girdi tensör adı farklı olabilir. Örneğin OpenVINO, modelin ileri argüman adını (genel modeller için genellikle x) kullanırken, torch2onnx varsayılan olarak "images" değerini kullanır.

Bilinen Sınırlamalar#

• Çoklu girdi desteği eşit dağılmamıştır: torch2onnx ve torch2openvino, birden çok girdiye sahip modeller için örnek tensörlerden oluşan bir demet (tuple) veya liste kabul eder. torch2torchscript, torch2coreml, torch2ncnn, torch2paddle ve torch2executorch tek bir girdi tensörü varsayar.
• ExecuTorch, flatc gerektirir: ExecuTorch çalışma zamanı FlatBuffers derleyicisini gerektirir. macOS'te brew install flatbuffers veya Ubuntu'da apt install flatbuffers-compiler ile yükle.
• Ultralytics üzerinden çıkarım yok: Dışa aktarılan YOLO dışı modeller, çıkarım için YOLO() aracılığıyla tekrar yüklenemez. Her biçim için yerel çalışma zamanını kullan (ONNX Runtime, OpenVINO Runtime vb.).
• Yalnızca YOLO biçimleri: Axelera ve Sony IMX500 dışa aktarımları YOLO'ya özel model öznitelikleri gerektirir ve genel modeller için kullanılamaz.
• Platforma özel biçimler: TensorRT bir NVIDIA GPU gerektirir. RKNN rknn-toolkit2 SDK'sını gerektirir (yalnızca Linux). Edge TPU edgetpu_compiler ikili dosyasını gerektirir (yalnızca Linux).

Sonuç#

Bu yardımcı programlar, düz bir torch.nn.Module modelini tek bir tutarlı API aracılığıyla üretime hazır bir ONNX, OpenVINO, CoreML, TensorFlow veya mobil çalışma zamanı yapısına dönüştürür. Hedef donanımına uyan biçimi seç, orijinal modele karşı sayısal eşitliği doğrula, ardından çalışma zamanına özel dağıtım adımları için ilgili entegrasyon kılavuzunu takip et.

SSS#