Nicht-YOLO-PyTorch-Modelle mit Ultralytics exportieren#

Ultralytics stellt eigenständige Exportwerkzeuge unter ultralytics.utils.export bereit, die mehrere Backends hinter einer einheitlichen Schnittstelle bündeln. Du kannst jedes torch.nn.Module exportieren, darunter Bildmodelle von timm, Klassifikatoren und Detektoren von torchvision sowie eigene Architekturen, und zwar nach TorchScript, ONNX, OpenVINO, CoreML, Core AI, TensorFlow SavedModel, TensorFlow Frozen Graph, PaddlePaddle, MNN, NCNN und ExecuTorch, ohne dich separat in jedes Backend einarbeiten zu müssen.

PyTorch-Modelle für den Produktionseinsatz bereitzustellen bedeutet meist, für jedes Ziel einen anderen Exporter zu verwenden: torch.onnx.export für ONNX, coremltools für Apple-Geräte, onnx2tf für TensorFlow, pnnx für NCNN und so weiter. Jedes Werkzeug hat seine eigene API, spezielle Abhängigkeiten und Ausgabeformate. Diese Dienstprogramme fassen das in einem einzigen Aufrufmuster zusammen.

Warum Ultralytics für den Export von Nicht-YOLO-Modellen verwenden?#

• Eine API für 11 Formate: Lerne eine einzige Aufrufkonvention statt einem Dutzend.
• Derselbe Codepfad wie bei YOLO-Exporten: Dieselben Hilfsfunktionen werden für alle Ultralytics-YOLO-Exporte verwendet.
• FP16- und INT8-Quantisierung über ein einziges Argument quantize für Formate, die dies unterstützen.
• Funktioniert auf der CPU: Für den Export selbst ist keine GPU erforderlich, sodass du ihn lokal auf einem Laptop ausführen kannst; der CoreML-Export wird unter Windows nicht unterstützt, und für den Core AI-Export ist macOS 26 oder neuer auf Apple silicon oder x86_64 Linux mit glibc 2.34 oder neuer sowie Python 3.11 bis 3.14 erforderlich.

Schnellstart#

Der schnellste Weg ist ein Export nach ONNX in zwei Zeilen – ohne YOLO-Code und ohne weitere Einrichtung als pip install ultralytics onnx timm:

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

Unterstützte Exportformate#

Die Funktionen torch2* erwarten ein standardmäßiges torch.nn.Module und einen Beispiel-Eingabetensor. MNN, TF SavedModel und TF Frozen Graph verwenden ein zwischengeschaltetes ONNX- oder Keras-Artefakt. In beiden Fällen sind keine YOLO-spezifischen Attribute erforderlich.

Schritt-für-Schritt-Beispiele#

Alle folgenden Beispiele verwenden dieselbe Konfiguration: ein vortrainiertes ResNet-18 von timm im Evaluierungsmodus:

import timm
import torch

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

Ins ONNX-Format exportieren#

from ultralytics.utils.export import torch2onnx

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

Übergib für eine dynamische Batchgröße ein dynamic-Wörterbuch:

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

Das Standard-Opset ist 14, und der Standardname der Eingabe ist "images". Du kannst diese Werte mit den Argumenten opset, input_names oder output_names überschreiben.

Nach TorchScript exportieren#

Keine zusätzlichen Abhängigkeiten erforderlich. Verwendet intern torch.jit.trace.

from ultralytics.utils.export import torch2torchscript

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

Nach OpenVINO exportieren#

from ultralytics.utils.export import torch2openvino

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

Das Verzeichnis enthält ein Paar aus model.xml und model.bin mit festen Dateinamen:

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

Übergib dynamic=True für dynamische Eingabeformen, quantize=16 für FP16 oder quantize=8 für INT8-Quantisierung. Für INT8 ist zusätzlich das Argument calibration_dataset erforderlich.

Erfordert openvino>=2024.0.0 (oder unter macOS 15.4+ >=2025.2.0) sowie torch>=2.1.

Nach CoreML exportieren#

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

Übergib für Klassifikationsmodelle eine Liste mit Klassennamen an classifier_names, um dem CoreML-Modell einen Klassifikationskopf hinzuzufügen.

Erfordert coremltools>=9.0, torch>=1.11 und numpy<=2.3.5. Unter Windows nicht unterstützt.

Nach Core AI exportieren#

from ultralytics.utils.export import torch2coreai

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

Das .aimodel-Artefakt ist ein Verzeichnis:

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

Der Export läuft unter macOS 26 oder neuer auf Apple silicon oder unter x86_64 Linux mit glibc 2.34 oder neuer und Python 3.11 bis 3.14 (pip install coreai-torch), und quantize=16 schreibt ein FP16-Asset, das Eingaben vom Typ float16 erwartet; das Asset läuft unter iOS 27 und macOS 27. Weitere Informationen findest du in der Core-AI-Integration, einschließlich des Hinweises zu FP16-Assets, die beim Laden einen Abbruch verursachen.

Nach TensorFlow SavedModel exportieren#

Beim TF-SavedModel-Export wird ONNX als Zwischenschritt verwendet:

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

Die Funktion gibt ein Keras-Modell zurück und erzeugt außerdem FP32- und FP16-Dateien für LiteRT (.tflite) im Ausgabeverzeichnis:

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

Übergib quantize=8, um zusätzlich zu diesen Dateien ein INT8-.tflite hinzuzufügen.

Der TensorFlow-Export funktioniert unter macOS nicht mit Python 3.13 oder neuer. Verwende unter macOS Python 3.12 oder älter oder nutze Linux.

Anforderungen für Python 3.12 oder älter (mit Python 3.13 oder neuer erfordert der Export stattdessen tensorflow>2.19.0, tf_keras>2.19.0, onnx2tf>=2.3.0,<2.3.16 und protobuf>=6.31.1,<7.0.0):

• 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
• ai-edge-litert>=1.2.0,<1.4.0 unter macOS (ai-edge-litert>=1.2.0 auf anderen Plattformen)
• onnxslim>=0.1.82
• onnx>=1.12.0,<2.0.0
• protobuf>=5

Nach TensorFlow Frozen Graph exportieren#

Fahre mit dem oben beschriebenen SavedModel-Export fort und wandle das zurückgegebene keras_model in einen eingefrorenen .pb-Graphen um:

from pathlib import Path

from ultralytics.utils.export import keras2pb

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

Nach NCNN exportieren#

from ultralytics.utils.export import torch2ncnn

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

Das Verzeichnis enthält Dateien mit festen Namen für param und bin sowie einen Python-Wrapper:

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

Nach MNN exportieren#

Für den MNN-Export wird eine ONNX-Datei als Eingabe benötigt. Exportiere zuerst nach ONNX und konvertiere anschließend:

from ultralytics.utils.export import onnx2mnn, torch2onnx

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

Unterstützt quantize=16 für FP16 und quantize=8 für INT8-Quantisierung. Erfordert MNN>=2.9.6 und torch>=1.10.

Nach PaddlePaddle exportieren#

from ultralytics.utils.export import torch2paddle

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

Das Verzeichnis enthält das PaddlePaddle-Modell und die Parameterdateien:

resnet18_paddle_model/
├── inference_model/
│   ├── model.json
│   └── model.pdiparams
├── model.pdparams
└── x2paddle_code.py

Erfordert x2paddle und die passende PaddlePaddle-Distribution für deine Plattform:

• paddlepaddle-gpu>=3.0.0,<3.3.0 unter CUDA
• paddlepaddle==3.0.0 auf einer ARM64-CPU
• paddlepaddle>=3.0.0,<3.3.0 auf anderen CPUs

Unter NVIDIA Jetson nicht unterstützt.

Nach ExecuTorch exportieren#

from ultralytics.utils.export import torch2executorch

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

Die exportierte Datei .pte wird im Ausgabeverzeichnis gespeichert:

resnet18_executorch_model/
└── model.pte

Erfordert torch>=2.9.0 und eine passende ExecuTorch-Laufzeit (pip install executorch). Informationen zur Verwendung der Laufzeit findest du in der ExecuTorch-Integration.

Exportiertes Modell überprüfen#

Überprüfe nach dem Export die numerische Übereinstimmung mit dem ursprünglichen PyTorch-Modell, bevor du es bereitstellst. Ein schneller Rauchtest mit ONNXBackend aus ultralytics.nn.backends vergleicht die Ausgaben und erkennt frühzeitig Fehler beim Tracing oder bei der Quantisierung:

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

Bei anderen Laufzeitumgebungen kann der Name des Eingabetensors abweichen. OpenVINO verwendet beispielsweise den Namen des Forward-Arguments des Modells (bei allgemeinen Modellen normalerweise x), während torch2onnx standardmäßig "images" verwendet.

Exportiertes Modell ausführen#

Exportierte Nicht-YOLO-Modelle lassen sich über die normale YOLO()-API laden. Die oben erstellten Exporte enthalten keine Ultralytics-Metadaten zur Aufgabe oder Eingabegröße. Übergib daher task explizit und gib für imgsz den Wert des Beispiel-Tensors an, mit dem du exportiert hast:

from ultralytics import YOLO

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

imgsz ist wichtig, wenn der Export eine feste Eingabeform hat: Die oben gezeigten ONNX- und TF-SavedModel-Exporte weisen den Standardwert 640 zurück. Die oben gezeigten TorchScript- und NCNN-Exporte akzeptieren zwar auch andere Größen, aber keiner der beiden Exporter garantiert dies: Beide erstellen einen Trace anhand des Beispiel-Tensors. Ein Modell, das in eine Linear-Schicht abflacht, behält daher eine feste Form. Überprüfe deinen Export.

Der Wert wird anschließend auf das nächste Vielfache des Modell-Strides aufgerundet, der ohne Metadaten 32 beträgt. Ein Export mit fester Form von 200x200 erhält daher eine Eingabe von 224x224 und wird zurückgewiesen, obwohl imgsz=200 dazu passt. Bei Eingabegrößen, die kein Vielfaches von 32 sind, rufe das Backend direkt auf.

Ein Backend direkt aufrufen#

Für rohe Tensoren ohne Ultralytics-Vorverarbeitung und -Nachverarbeitung verwende die formatspezifischen Klassen in ultralytics.nn.backends, wie im Überprüfungsbeispiel oben. Jede Klasse erwartet das exportierte Artefakt und ein Gerät und ist aufrufbar:

TensorFlowBackend unterstützt zwei Formate und verwendet standardmäßig format="saved_model". Übergib für einen Frozen Graph daher format="pb".

Drei Dinge, die der Weg über YOLO() für dich übernimmt, ein direkter Aufruf jedoch nicht:

• Eingabelayout: CoreMLBackend und TensorFlowBackend erwarten BHWC. Transponiere den Tensor zuerst mit im.permute(0, 2, 3, 1). Ein BCHW-Tensor führt zu einer nicht übereinstimmenden Form.
• Autograd: Umschließe Aufrufe mit torch.inference_mode(). TorchScriptBackend gibt einen Tensor zurück, der weiterhin einen Gradienten-Graphen enthält.
• Nachverarbeitung: Ohne Metadaten gibt ein Backend task als None und names leer zurück. LiteRTBackend skaliert weiterhin jede 3D-Ausgabe anhand der Bildgröße zurück, da es von YOLO-Boxen ausgeht. Bei einem Nicht-YOLO-Modell mit einer 3D-Ausgabe ist das falsch. Zweidimensionale Ausgaben wie Klassifikator-Logits sind davon nicht betroffen.

Bekannte Einschränkungen#

• Die Unterstützung mehrerer Eingaben ist uneinheitlich: torch2onnx, torch2openvino und torch2torchscript akzeptieren bei Modellen mit mehreren Eingaben ein Tupel von Beispiel-Tensoren. torch2coreml, torch2coreai, torch2ncnn, torch2paddle und torch2executorch setzen einen einzelnen Eingabe-Tensor voraus.
• Nur für YOLO verfügbare Formate: Exporte für Axelera und Sony IMX500 erfordern YOLO-spezifische Modellattribute und sind für allgemeine Modelle nicht verfügbar.
• Plattformspezifische Formate: Für TensorRT ist eine NVIDIA-GPU erforderlich. Für RKNN ist das rknn-toolkit2 SDK erforderlich (nur Linux). Für Edge TPU wird die Binärdatei edgetpu_compiler benötigt (nur Linux).

Fazit#

Mit diesen Dienstprogrammen kannst du jedes PyTorch-Modell – vom einfachen torch.nn.Module bis hin zu einem einsatzbereiten ONNX-, OpenVINO-, CoreML-, TensorFlow- oder Mobile-Runtime-Artefakt – über eine einheitliche API exportieren. Wähle das Format passend zu deiner Zielhardware, überprüfe die numerische Übereinstimmung mit dem ursprünglichen Modell und befolge anschließend die passende Integrationsanleitung für die plattformspezifischen Bereitstellungsschritte.

Häufig gestellte Fragen#