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

Ultralytics, farklı arka uçları tek ve tutarlı bir arayüzle bir araya getiren bağımsız dışa aktarma araçlarını ultralytics.utils.export altında sunar. timm görüntü modelleri, torchvision sınıflandırıcıları ve algılayıcıları veya kendi özel mimarilerin dâhil olmak üzere tüm torch.nn.Module modellerini, her arka ucu ayrı ayrı öğrenmene gerek kalmadan TorchScript, ONNX, OpenVINO, CoreML, Core AI, TensorFlow SavedModel, TensorFlow Frozen Graph, PaddlePaddle, MNN, NCNN ve ExecuTorch biçimlerine 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 cihazları için coremltools, TensorFlow için onnx2tf, NCNN için pnnx ve benzerleri. Her aracın kendine özgü bir API'si, bağımlılık özellikleri ve çıktı kuralları vardır. Bu araçlar tüm bu süreçleri tek bir çağrı biçiminde birleştirir.

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

• 11 biçimde tek API: Bir düzine farklı çağrı kuralı yerine tek bir çağrı kuralı öğren.
• YOLO dışa aktarma işlemleriyle aynı kod yolu: Tüm Ultralytics YOLO dışa aktarma işlemlerinde aynı yardımcılar kullanılır.
• FP16 ve INT8 niceleme, destekleyen biçimlerde tek bir quantize argümanı üzerinden yapılır.
• CPU'da çalışır: Dışa aktarma adımı için GPU gerekmez; bu nedenle işlemi yerel olarak dizüstü bilgisayarında çalıştırabilirsin. CoreML dışa aktarımı Windows'ta desteklenmez; Core AI dışa aktarımı için Apple silicon üzerinde macOS 26 veya üzeri ya da glibc 2.34 veya üzeri ve Python 3.11–3.14 yüklü x86_64 Linux gerekir.

Hızlı Başlangıç#

En hızlı yol, YOLO kodu veya pip install ultralytics onnx timm dışında bir kurulum gerektirmeden ONNX biçimine 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 Biçimleri#

torch2* işlevleri standart bir torch.nn.Module ve örnek bir girdi tensörü alır. MNN, TF SavedModel ve TF Frozen Graph, ara adım olarak ONNX veya Keras yapıtı kullanır. Her iki durumda da YOLO'ya özgü nitelikler gerekmez.

Adım Adım Örnekler#

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

import timm
import torch

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

ONNX Biçimine Aktarma#

from ultralytics.utils.export import torch2onnx

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

Dinamik toplu iş boyutu için dynamic sözlüğü gönder:

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

Varsayılan opset 14, varsayılan girdi adı ise "images" şeklindedir. Bunları opset, input_names veya output_names argümanlarıyla değiştirebilirsin.

TorchScript Biçimine 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 Biçimine 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 gönder. INT8 ayrıca bir calibration_dataset argümanı gerektirir.

openvino>=2024.0.0 (veya macOS 15.4+ sürümünde >=2025.2.0) ve torch>=2.1 gerekir.

CoreML Biçimine 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 modelleri için CoreML modeline bir sınıflandırma başlığı eklemek üzere sınıf adlarının listesini classifier_names argümanına gönder.

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

Core AI Biçimine Aktarma#

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, Apple silicon üzerinde macOS 26 veya üzeri ya da glibc 2.34 veya üzeri yüklü x86_64 Linux üzerinde Python 3.11–3.14 (pip install coreai-torch) ile çalışır. quantize=16, float16 girdiler alan bir FP16 varlığı yazar; bu varlık iOS 27 ve macOS 27'de çalışır. Yüklenirken işlemi durduran FP16 varlıklarıyla ilgili not da dâhil olmak üzere Core AI entegrasyonuna göz at.

TensorFlow SavedModel Biçimine Aktarma#

TF SavedModel dışa aktarımında ara adım olarak ONNX kullanılı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ı dizininde FP32 ve FP16 LiteRT dosyaları (.tflite) da oluşturur:

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

Bunların yanında bir INT8 .tflite eklemek için quantize=8 gönder.

TensorFlow dışa aktarımı, Python 3.13 veya üzeri yüklü macOS'ta çalışmaz; macOS'ta Python 3.12 veya daha eski bir sürümü ya da Linux kullan.

Python 3.12 veya daha eski sürümlerde gereksinimler (Python 3.13 veya üzeri sürümlerde dışa aktarım için bunun yerine tensorflow>2.19.0, tf_keras>2.19.0, onnx2tf>=2.3.0,<2.3.16 ve protobuf>=6.31.1,<7.0.0 gerekir):

• 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'ta 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 Biçimine Aktarma#

Yukarıdaki SavedModel dışa aktarımından devam ederek döndürülen keras_model değerini 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 Biçimine Aktarma#

from ultralytics.utils.export import torch2ncnn

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

Dizin, Python sarmalayıcısının yanı sıra sabit adlı parametre ve bin dosyalarını içerir:

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

MNN Biçimine Aktarma#

MNN dışa aktarımı için girdi olarak bir ONNX dosyası gerekir. Önce ONNX biçimine 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 kuantizasyonu için quantize=16'ı, INT8 kuantizasyonu için quantize=8'i destekler. MNN>=2.9.6 ve torch>=1.10 gerekir.

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/
├── inference_model/
│   ├── model.json
│   └── model.pdiparams
├── model.pdparams
└── x2paddle_code.py

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'da desteklenmez.

ExecuTorch'a dışa aktar#

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.

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

Dışa aktardıktan sonra, ürüne almadan önce sayısal uyumu orijinal PyTorch modeliyle doğrula. ultralytics.nn.backends içinden ONNXBackend ile yapacağın hızlı bir duman testi, çıktıları karşılaştırır ve izleme ya da kuantizasyon hatalarını erkenden ortaya çıkarır:

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-5 for an FP32 ONNX export

Diğer çalışma zamanlarında giriş tensörünün adı farklı olabilir. Örneğin OpenVINO, modelin forward argümanının adını kullanır (genel modellerde genellikle x); torch2onnx ise varsayılan olarak "images" değerini kullanır.

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

Dışa aktarılan YOLO dışı modeller, normal YOLO() API'si üzerinden yeniden yüklenir. Yukarıdaki dışa aktarımlarda Ultralytics görevi veya giriş boyutu meta verileri bulunmaz; bu nedenle task değerini açıkça belirt ve imgsz değerini dışa aktarımda kullandığın örnek tensörle 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 aktarım sabit bir giriş şekline sahipse imgsz önemlidir: yukarıdaki ONNX ve TF SavedModel dışa aktarımları varsayılan 640 değerini kabul etmez. Yukarıdaki TorchScript ve NCNN dışa aktarımları başka boyutları kabul eder, ancak her iki dışa aktarıcı da bunu garanti etmez: ikisi de örnek tensörden iz oluşturur; dolayısıyla Linear katmanına düzleştiren bir model sabit boyutlu kalır. Kendi dışa aktarımını kontrol et.

Değer daha sonra, meta veri yokken 32 olan model adımının katına yuvarlanır. Bu nedenle 200x200 boyutlu sabit şekilli bir dışa aktarıma 224x224 verilir ve imgsz=200 bununla eşleşse bile dışa aktarım reddedilir. 32'nin katı olmayan giriş boyutları için arka ucu doğrudan çağır.

Arka Ucu Doğrudan Çağırma#

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

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

YOLO() yolu, doğrudan çağrının yapmadığı şu üç işlemi senin için halleder:

• Giriş düzeni: CoreMLBackend ve TensorFlowBackend, BHWC bekler. Önce im.permute(0, 2, 3, 1) ile transpoze et; BCHW tensörü şekil uyuşmazlığı hatasına yol açar.
• Autograd: çağrıları torch.inference_mode() içine al. TorchScriptBackend, gradyan grafiğini hâlâ taşıyan bir tensör döndürür.
• Son işleme: meta veri yoksa arka uç, task değerini None olarak bırakır ve names boş kalır. LiteRTBackend yine de 3 boyutlu her çıktıyı YOLO kutuları içerdiği varsayımıyla görüntü boyutuna göre denormalize eder; bu, 3 boyutlu çıktı veren YOLO dışı bir model için yanlıştır. Sınıflandırıcı logitleri gibi iki boyutlu çıktılar bundan etkilenmez.

Bilinen Sınırlamalar#

• Çoklu giriş desteği tutarsızdır: torch2onnx, torch2openvino ve torch2torchscript, birden fazla girişi olan modeller için örnek tensörlerden oluşan bir demeti kabul eder. torch2coreml, torch2coreai, torch2ncnn, torch2paddle ve torch2executorch ise tek bir giriş tensörü olduğunu varsayar.
• Yalnızca YOLO'da kullanılabilen biçimler: Axelera ve Sony IMX500 dışa aktarımları, YOLO'ya özgü model nitelikleri gerektirir ve genel modellerde kullanılamaz.
• Platforma özgü 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 x86_64 Linux).

Sonuç#

Bu araçlar, sade bir torch.nn.Module içindeki herhangi bir PyTorch modelini, tek ve tutarlı bir API üzerinden 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 biçimi seç, orijinal modelle sayısal uyumu doğrula ve ardından çalışma zamanına özgü dağıtım adımları için ilgili entegrasyon kılavuzunu izle.

Sık Sorulan Sorular#