YOLO Dışı PyTorch Modelleri Ultralytics ile Dışa Aktarma#

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

PyTorch modellerini üretime dağıtmak genellikle her hedef için farklı bir dışa aktarıcı kullanmayı gerektirir: ONNX için torch.onnx.export, Apple aygıtları için coremltools, TensorFlow için onnx2tf, NCNN için pnnx ve benzeri. Her aracın kendine ait API'si, bağımlılık özellikleri ve çıktı kuralları vardır. Bu yardımcı programlar bunları tek bir çağrı biçiminde birleştirir.

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

• 11 formatta tek bir API: düzinelerce farklı kural öğrenmek yerine tek bir çağrı kuralı öğrenirsin.
• Paylaşılan yardımcı program yüzeyi: Dışa aktarma yardımcıları ultralytics.utils.export altında bulunur; bu nedenle arka uç paketlerini yükledikten sonra formatlar arasında aynı çağrı biçimini kullanabilirsin.
• YOLO dışa aktarmalarıyla aynı kod yolu: Tüm Ultralytics YOLO dışa aktarmalarında aynı yardımcılar kullanılır.
• FP16 ve INT8 niceleme (quantization) desteği sunan formatlar için yerleşik olarak gelir (OpenVINO, CoreML ve MNN; NCNN ve Core AI için yalnızca FP16).
• CPU üzerinde çalışır: dışa aktarma adımı için GPU gerekmez, böylece bu adımı dizüstü bilgisayarında yerel olarak çalıştırabilirsin; CoreML dışa aktarma işlemi Windows üzerinde desteklenmez ve Core AI dışa aktarma işlemi Apple silikon üzerinde macOS 26 veya üstünü gerektirir.

Hızlı Başlangıç#

En hızlı yol, YOLO kodu olmadan ve pip install ultralytics onnx timm dışında ek kurulum gerektirmeden ONNX formatına iki satırda dışa aktarmaktı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* işlevleri 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 çıktısı üzerinden çalışır. Her iki durumda da YOLO'ya özgü hiçbir öznitelik gerekmez.

Adım Adım Örnekler#

Aşağıdaki her örnekte aynı kurulum kullanılır: değerlendirme modunda, timm içinden önceden eğitilmiş bir ResNet-18:

import timm
import torch

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

ONNX'e Dışa Aktarma#

from ultralytics.utils.export import torch2onnx

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

Dinamik batch boyutu için bir dynamic sözlüğü ilet:

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

Varsayılan opset 14, varsayılan girdi adı ise "images" değeridir. Bunları opset, input_names veya output_names bağımsız değişkenleriyle geçersiz kılabilirsin.

TorchScript'e Dışa Aktarma#

Ek bağımlılık gerekmez. Arka planda torch.jit.trace kullanılır.

from ultralytics.utils.export import torch2torchscript

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

OpenVINO'ya Dışa Aktarma#

from ultralytics.utils.export import torch2openvino

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

Dizin, sabit adlı 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 niceleme için quantize=8 ilet. INT8 ayrıca bir calibration_dataset bağımsız değişkeni gerektirir.

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

CoreML'e Dışa Aktarma#

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 modellerinde, CoreML modeline bir sınıflandırma başlığı eklemek için sınıf adları listesini classifier_names öğesine ilet.

coremltools>=9.0, torch>=1.11 ve numpy<=2.3.5 gerekir. Windows üzerinde desteklenmez.

TensorFlow SavedModel'e Dışa Aktarma#

TF SavedModel dışa aktarması ara adım olarak ONNX üzerinden çalışır:

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

İşlev bir Keras modeli döndürür ve çıktı dizini içinde FP32 ve FP16 LiteRT dosyaları (.tflite) de oluşturur:

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

Bunların yanına bir INT8 .tflite eklemek için quantize=8 ilet.

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'e Dışa Aktarma#

Yukarıdaki SavedModel dışa aktarmasından devam ederek, döndürülen keras_model öğesini 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 Aktarma#

from ultralytics.utils.export import torch2ncnn

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

Dizin, bir Python sarmalayıcısının yanı sıra sabit adlı 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 öğelerini kontrol eder.

MNN'e Dışa Aktarma#

MNN dışa aktarması girdi olarak bir ONNX dosyası gerektirir. Önce ONNX'e 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 niceleme için quantize=8 desteklenir. MNN>=2.9.6 ve torch>=1.10 gerekir.

PaddlePaddle'a Dışa Aktarma#

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ı gerekir:

• 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'a Dışa Aktarma#

from ultralytics.utils.export import torch2executorch

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

Dışa aktarılan .pte dosyası çıktı dizinine kaydedilir:

resnet18_executorch_model/
└── model.pte

torch>=2.9.0 ve uyumlu bir ExecuTorch çalışma zamanı (pip install executorch) gerekir. Çalışma zamanı kullanımı için ExecuTorch entegrasyonuna bak.

Core AI formatına dışa aktar#

from ultralytics.utils.export import torch2coreai

torch2coreai(model, im, output_file="resnet18.aimodel")

.aimodel varlığı bir dizindir:

resnet18.aimodel/
├── main.mlirb
├── main.hash
└── metadata.json

Dışa aktarma işlemi Apple silikon üzerinde macOS 26 veya sonraki sürümlerde (pip install coreai-torch) çalışır ve quantize=16 float16 girdileri alan bir FP16 varlığı yazar; bu varlık iOS 27 ve macOS 27 üzerinde çalışır. Yükleme sırasında durdurulan FP16 varlıklarına ilişkin not dahil olmak üzere Core AI entegrasyonu sayfasına göz at.

Dışa Aktardığın Modeli Doğrulama#

Dışa aktardıktan sonra, dağıtıma almadan önce özgün PyTorch modeliyle sayısal eşdeğerliği doğrula. ultralytics.nn.backends içindeki ONNXBackend ile yapılan hızlı bir duman testi, çıktıları karşılaştırır ve izleme veya niceleme hatalarını erkenden işaretler:

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}")  # ~1e-6 for an FP32 ONNX export

Diğer çalışma zamanlarında girdi tensörünün adı farklı olabilir. Örneğin OpenVINO, modelin forward bağımsız değişkeni adını kullanır (genel modeller için genellikle x); torch2onnx ise varsayılan olarak "images" değerini kullanır.

Dışa Aktardığın Modeli Çalıştırma#

YOLO dışı dışa aktarılan modeller, normal YOLO() API'si üzerinden yeniden yüklenir. Yukarıdaki dışa aktarmalar hiçbir Ultralytics görevi veya girdi boyutu meta verisi taşımaz; bu nedenle task öğesini açıkça ilet ve imgsz değerini dışa aktarma sırasında kullandığın örnek tensörüyle eşleştir:

from ultralytics import YOLO

results = YOLO("resnet18.onnx", task="classify")("path/to/image.jpg", imgsz=224)
print(results[0].probs.top1)

Dışa aktarmanın sabit bir girdi şekli varsa imgsz önemlidir: yukarıdaki ONNX ve TF SavedModel dışa aktarmaları varsayılan 640 değerini reddeder. Yukarıdaki TorchScript ve NCNN dışa aktarmaları başka boyutları kabul eder, ancak hiçbir dışa aktarıcı bunu garanti etmez: ikisi de örnek tensörden iz çıkarır; bu nedenle Linear katmanına düzleştirme yapan bir model sabit kalır. Kendi dışa aktarmanı kontrol et.

Değer daha sonra, meta veri olmadığında 32 olan model stride'ının katına yukarı yuvarlanır. Bu nedenle 200x200 boyutundaki sabit şekilli bir dışa aktarmaya 224x224 girdi verilir ve imgsz=200 onunla eşleşse bile reddedilir. 32'nin katı olmayan girdi boyutları için arka ucu doğrudan çağır.

Arka Ucu Doğrudan Çağırma#

Ultralytics ön işleme ve son işleme olmadan ham tensörler için, yukarıdaki doğrulama örneğinde olduğu gibi ultralytics.nn.backends içindeki formata özel sınıfları kullan. Her biri dışa aktarılan çıktıyı ve bir aygıtı alır ve çağrılabilir:

TensorFlowBackend iki formatı kapsar ve varsayılan olarak format="saved_model" değerini kullanır; bu nedenle dondurulmuş grafik için format="pb" ilet.

YOLO() yolunun senin için işlediği, doğrudan çağrının ise işlemediği üç konu:

• Girdi düzeni: CoreMLBackend ve TensorFlowBackend BHWC bekler. Önce im.permute(0, 2, 3, 1) ile transpoze et; BCHW tensörü şekil uyuşmazlığı hatası oluşturur.
• Autograd: Çağrıları torch.inference_mode() içine al. TorchScriptBackend, hâlâ bir gradient grafiği taşıyan tensör döndürür.
• Son işleme: Meta veri olmadığında arka uç, task öğesini None olarak bırakır ve names öğesini boş bırakır. LiteRTBackend, 3B herhangi bir çıktıyı YOLO kutularını içerdiği varsayımıyla görüntü boyutuna göre denormalize etmeye devam eder; bu, 3B çıktıya sahip YOLO dışı bir model için yanlıştır. Sınıflandırıcı logits'leri gibi iki boyutlu çıktılar etkilenmez.

Bilinen Sınırlamalar#

• Çoklu girdi desteği düzensizdir: torch2onnx ve torch2openvino, birden fazla girdiye sahip modeller için bir demet (tuple) veya örnek tensörler listesi kabul eder. torch2torchscript, torch2coreml, torch2ncnn, torch2paddle, torch2executorch ve torch2coreai tek bir girdi tensörü varsayar.
• ExecuTorch için flatc gerekir: ExecuTorch çalışma zamanı FlatBuffers derleyicisini gerektirir. macOS üzerinde brew install flatbuffers, Ubuntu üzerinde ise apt install flatbuffers-compiler ile yükle.
• Gömülü meta veri yoktur: Yukarıdaki dışa aktarmalar hiçbir Ultralytics görevi veya girdi boyutu meta verisi taşımaz; bu nedenle YOLO() ikisini de çıkaramaz ve her ikisinin de açıkça iletilmesini gerektirir. Dışa Aktardığın Modeli Çalıştırma bölümüne bak.
• Yalnızca YOLO formatları: Axelera ve Sony IMX500 dışa aktarmaları YOLO'ya özgü model öznitelikleri gerektirir ve genel modeller için kullanılamaz.
• Platforma özgü formatlar: TensorRT bir NVIDIA GPU gerektirir. RKNN, rknn-toolkit2 SDK'sını (yalnızca Linux) gerektirir. Edge TPU, edgetpu_compiler ikili dosyasını (yalnızca Linux) gerektirir.

Sonuç#

Bu yardımcı programlar, herhangi bir PyTorch modelini düz bir torch.nn.Module dosyasından tek ve tutarlı bir API aracılığıyla dağıtıma hazır ONNX, OpenVINO, CoreML, TensorFlow veya mobil çalışma zamanı çıktısına dönüştürür. Hedef donanımına uygun formatı seç, özgün modele karşı sayısal eşdeğerliği doğrula, ardından çalışma zamanına özel dağıtım adımları için ilgili entegrasyon kılavuzunu izle.

SSS#