ORT-Modellformat

Inhalt

Was ist das ORT-Modellformat?
Abwärtskompatibilität
ONNX-Modelle in das ORT-Format konvertieren
Ein Modell im ORT-Format laden und ausführen

Was ist das ORT-Modellformat?

Das ORT-Format ist das Format, das von ONNX Runtime-Builds mit reduzierter Größe unterstützt wird. Builds mit reduzierter Größe eignen sich besser für den Einsatz in größenbeschränkten Umgebungen wie mobilen und Webanwendungen.

Sowohl ORT-Formatmodelle als auch ONNX-Modelle werden von einem vollständigen ONNX Runtime-Build unterstützt.

Abwärtskompatibilität

Im Allgemeinen ist es das Ziel, dass eine bestimmte Version von ONNX Runtime Modelle der aktuellen (zum Zeitpunkt der ONNX Runtime-Veröffentlichung) oder älteren Versionen des ORT-Formats ausführen kann.

Obwohl wir versuchen, die Abwärtskompatibilität aufrechtzuerhalten, gab es einige brechende Änderungen.

ONNX Runtime-Version	ORT-Modellformat-Unterstützung	Hinweise
1.14+	v5, v4 (eingeschränkte Unterstützung)	Siehe hier für Details zur eingeschränkten v4-Unterstützung.
1.13	v5	v5 brechende Änderung: Kernel-Def-Hashes entfernt.
1.12-1.8	v4	v4 brechende Änderung: Aktualisierte Berechnung des Kernel-Def-Hashs.
1.7	v3, v2, v1
1.6	v2, v1
1.5	v1	Einführung des ORT-Formats

ONNX-Modelle in das ORT-Format konvertieren

ONNX-Modelle werden mit dem Skript convert_onnx_models_to_ort in das ORT-Format konvertiert.

Das Konvertierungsskript führt zwei Funktionen aus

Lädt und optimiert ONNX-Formatmodelle und speichert sie im ORT-Format
Ermittelt die von den optimierten Modellen benötigten Operatoren und optional Datentypen und speichert diese in einer Konfigurationsdatei zur Verwendung in einem Build mit reduzierten Operatoren, falls erforderlich

Das Konvertierungsskript kann auf ein einzelnes ONNX-Modell oder ein Verzeichnis angewendet werden. Wenn es auf ein Verzeichnis angewendet wird, wird das Verzeichnis rekursiv nach Dateien mit der Endung „.onnx“ durchsucht, die konvertiert werden sollen.

Jede „.onnx“-Datei wird geladen, optimiert und im ORT-Format als Datei mit der Endung „.ort“ am selben Ort wie die ursprüngliche „.onnx“-Datei gespeichert.

Ausgaben des Skripts

Ein ORT-Formatmodell für jedes ONNX-Modell
Eine Build-Konfigurationsdatei („required_operators.config“) mit den von den optimierten ONNX-Modellen benötigten Operatoren.

Wenn die Typreduzierung aktiviert ist (ONNX Runtime-Version 1.7 oder höher), enthält die Konfigurationsdatei auch die benötigten Typen für jeden Operator und heißt „required_operators_and_types.config“.

Wenn Sie ein vorab erstelltes ONNX Runtime-Paket für iOS, Android oder Web verwenden, wird die Build-Konfigurationsdatei nicht verwendet und kann ignoriert werden.

Skriptspeicherort

Das ORT-Modellformat wird ab Version 1.5.2 von ONNX Runtime unterstützt.

Die Konvertierung von ONNX-Formatmodellen in das ORT-Format nutzt das ONNX Runtime Python-Paket, da das Modell im Rahmen des Konvertierungsprozesses in ONNX Runtime geladen und optimiert wird.

Für ONNX Runtime-Version 1.8 und höher wird das Konvertierungsskript direkt aus dem ONNX Runtime Python-Paket ausgeführt.

Für frühere Versionen wird das Konvertierungsskript aus dem lokalen ONNX Runtime-Repository ausgeführt.

ONNX Runtime installieren

Installieren Sie das onnxruntime Python-Paket von https://pypi.org/project/onnxruntime/, um Modelle vom ONNX-Format in das interne ORT-Format zu konvertieren. Version 1.5.3 oder höher ist erforderlich.

Installation der neuesten Version

pip install onnxruntime

Installation einer früheren Version

Wenn Sie ONNX Runtime aus dem Quellcode kompilieren (benutzerdefinierte, reduzierte oder minimale Builds), müssen Sie die Python-Paketversion mit dem Zweig des ONNX Runtime-Repositorys abgleichen, den Sie ausgecheckt haben.

Zum Beispiel, um die 1.7-Version zu verwenden

git checkout rel-1.7.2
pip install onnxruntime==1.7.2

Wenn Sie den main-Zweig im Git-Repository verwenden, sollten Sie das nächtliche ONNX Runtime Python-Paket verwenden

pip install -U -i https://test.pypi.org/simple/ ort-nightly

Verwendung des Konvertierungsskripts für ONNX-Modelle in das ORT-Format

ONNX Runtime-Version 1.8 oder höher

python -m onnxruntime.tools.convert_onnx_models_to_ort <onnx model file or dir>

wobei

onnx-modell-datei oder -verzeichnis ist ein Pfad zu einer .onnx-Datei oder einem Verzeichnis, das ein oder mehrere .onnx-Modelle enthält

Die aktuell verfügbaren optionalen Argumente können durch Ausführen des Skripts mit dem Argument --help abgerufen werden. Unterstützte Argumente und Standardwerte unterscheiden sich geringfügig zwischen den ONNX Runtime-Versionen.

Hilfetext von ONNX Runtime 1.11

python -m onnxruntime.tools.convert_onnx_models_to_ort --help

  usage: convert_onnx_models_to_ort.py [-h] [--optimization_style {Fixed,Runtime} [{Fixed,Runtime} ...]] [--enable_type_reduction] [--custom_op_library CUSTOM_OP_LIBRARY] [--save_optimized_onnx_model] [--allow_conversion_failures] [--nnapi_partitioning_stop_ops NNAPI_PARTITIONING_STOP_OPS]
                                      [--target_platform {arm,amd64}]
                                      model_path_or_dir

  Convert the ONNX format model/s in the provided directory to ORT format models. All files with a `.onnx` extension will be processed. For each one, an ORT format model will be created in the same directory. A configuration file will also be created containing the list of required
  operators for all converted models. This configuration file should be used as input to the minimal build via the `--include_ops_by_config` parameter.

  positional arguments:
    model_path_or_dir     Provide path to ONNX model or directory containing ONNX model/s to convert. All files with a .onnx extension, including those in subdirectories, will be processed.

  optional arguments:
    -h, --help            show this help message and exit
    --optimization_style {Fixed,Runtime} [{Fixed,Runtime} ...]
                          Style of optimization to perform on the ORT format model. Multiple values may be provided. The conversion will run once for each value. The general guidance is to use models optimized with 'Runtime' style when using NNAPI or CoreML and 'Fixed' style otherwise.
                          'Fixed': Run optimizations directly before saving the ORT format model. This bakes in any platform-specific optimizations. 'Runtime': Run basic optimizations directly and save certain other optimizations to be applied at runtime if possible. This is useful when
                          using a compiling EP like NNAPI or CoreML that may run an unknown (at model conversion time) number of nodes. The saved optimizations can further optimize nodes not assigned to the compiling EP at runtime.
    --enable_type_reduction
                          Add operator specific type information to the configuration file to potentially reduce the types supported by individual operator implementations.
    --custom_op_library CUSTOM_OP_LIBRARY
                          Provide path to shared library containing custom operator kernels to register.
    --save_optimized_onnx_model
                          Save the optimized version of each ONNX model. This will have the same level of optimizations applied as the ORT format model.
    --allow_conversion_failures
                          Whether to proceed after encountering model conversion failures.
    --nnapi_partitioning_stop_ops NNAPI_PARTITIONING_STOP_OPS
                          Specify the list of NNAPI EP partitioning stop ops. In particular, specify the value of the "ep.nnapi.partitioning_stop_ops" session options config entry.
    --target_platform {arm,amd64}
                          Specify the target platform where the exported model will be used. This parameter can be used to choose between platform-specific options, such as QDQIsInt8Allowed(arm), NCHWc (amd64) and NHWC (arm/amd64) format, different optimizer level options, etc.

Optionale Skriptargumente

Optimierungsstil

Seit ONNX Runtime 1.11

Gibt an, ob das konvertierte Modell vollständig optimiert („Fixed“) ist oder ob Laufzeitoptimierungen gespeichert sind („Runtime“). Beide Arten von Modellen werden standardmäßig erstellt. Weitere Informationen finden Sie hier.

Dies ersetzt die Option Optimierungsstufe aus früheren ONNX Runtime-Versionen.

Optimierungsstufe

ONNX Runtime-Version 1.10 und früher

Legt die Optimierungsstufe fest, die ONNX Runtime zur Optimierung des Modells vor dem Speichern im ORT-Format verwendet.

Für ONNX Runtime-Version 1.8 und höher wird „all“ empfohlen, wenn das Modell mit dem CPU EP ausgeführt wird.

Für frühere Versionen wird „extended“ empfohlen, da die Stufe „all“ zuvor gerätespezifische Optimierungen enthielt, die die Portabilität des Modells einschränkten.

Wenn das Modell mit dem NNAPI EP oder CoreML EP ausgeführt werden soll, wird empfohlen, ein ORT-Formatmodell mit der Optimierungsstufe „basic“ zu erstellen. Leistungstests sollten durchgeführt werden, um das Ausführen dieses Modells mit aktiviertem NNAPI- oder CoreML-EP mit dem Ausführen des Modells, das auf einer höheren Stufe mit dem CPU-EP optimiert wurde, zu vergleichen, um die optimale Konfiguration zu ermitteln.

Weitere Informationen finden Sie in der Dokumentation zur Leistungsoptimierung mobiler Szenarien.

Typreduzierung aktivieren

Mit ONNX Runtime-Version 1.7 und höher ist es möglich, die von den benötigten Operatoren unterstützten Datentypen einzuschränken, um die Build-Größe weiter zu reduzieren. Dieses Pruning wird in dieser Dokumentation als „Operator-Typreduzierung“ bezeichnet. Während die ONNX-Modelle konvertiert werden, werden die von jedem Operator benötigten Eingabe- und Ausgabedatentypen gesammelt und in die Konfigurationsdatei aufgenommen.

Wenn Sie die Operator-Typreduzierung aktivieren möchten, muss das Python-Paket Flatbuffers installiert sein.

pip install flatbuffers

Beispielsweise unterstützt der ONNX Runtime-Kernel für Softmax sowohl Float als auch Double. Wenn Ihr Modell Softmax, aber nur mit Float-Daten verwendet, können wir die Implementierung ausschließen, die Double unterstützt, um die Binärgröße des Kernels zu reduzieren.

Unterstützung für benutzerdefinierte Operatoren

Wenn Ihr ONNX-Modell benutzerdefinierte Operatoren verwendet, muss der Pfad zur Bibliothek, die die benutzerdefinierten Operator-Kernels enthält, angegeben werden, damit das ONNX-Modell erfolgreich geladen werden kann. Die benutzerdefinierten Operatoren bleiben im ORT-Formatmodell erhalten.

Optimiertes ONNX-Modell speichern

Fügen Sie dieses Flag hinzu, um das optimierte ONNX-Modell zu speichern. Das optimierte ONNX-Modell enthält dieselben Knoten und Initialisierer wie das ORT-Formatmodell und kann in Netron zur Fehlerbehebung und Leistungsoptimierung eingesehen werden.

Frühere Versionen von ONNX Runtime

Vor ONNX Runtime-Version 1.7 muss das Modellkonvertierungsskript aus einem geklonten Quell-Repository ausgeführt werden

python <ONNX Runtime repository root>/tools/python/convert_onnx_models_to_ort.py <onnx model file or dir>

Ein Modell im ORT-Format laden und ausführen

Die API zum Ausführen von ORT-Formatmodellen ist dieselbe wie für ONNX-Modelle.

Die ONNX Runtime API-Dokumentation finden Sie hier für Details zur einzelnen API-Nutzung.

APIs nach Plattform

Plattform	Verfügbare APIs
Android	C, C++, Java, Kotlin
iOS	C, C++, Objective-C (Swift über Brücke)
Web	JavaScript

Laden von ORT-Formatmodellen

Wenn Sie einen Dateinamen für das ORT-Formatmodell angeben, wird eine Dateiendung „.ort“ als ORT-Formatmodell interpretiert.

Wenn Sie Byte-Daten im Speicher für das ORT-Formatmodell bereitstellen, wird ein Marker in diesen Bytes überprüft, um festzustellen, ob es sich um ein ORT-Formatmodell handelt.

Wenn Sie explizit angeben möchten, dass die Eingabe für die InferenceSession ein ORT-Formatmodell ist, können Sie dies über SessionOptions tun, obwohl dies im Allgemeinen nicht erforderlich sein sollte.

ORT-Formatmodell aus einem Dateipfad laden

C++ API

Ort::SessionOptions session_options;
session_options.AddConfigEntry("session.load_model_format", "ORT");

Ort::Env env;
Ort::Session session(env, <path to model>, session_options);

Java API

SessionOptions session_options = new SessionOptions();
session_options.addConfigEntry("session.load_model_format", "ORT");

OrtEnvironment env = OrtEnvironment.getEnvironment();
OrtSession session = env.createSession(<path to model>, session_options);

JavaScript API

import * as ort from "onnxruntime-web";

const session = await ort.InferenceSession.create("<path to model>");

ORT-Formatmodell aus einem Byte-Array im Speicher laden

Wenn eine Sitzung mit einem Eingabe-Byte-Array erstellt wird, das die ORT-Formatmodelldaten enthält, kopieren wir standardmäßig die Modelldaten zum Zeitpunkt der Sitzungserstellung, um sicherzustellen, dass der Puffer der Modelldaten gültig ist.

Sie können auch die Option aktivieren, die Modelldaten direkt zu verwenden, indem Sie den SessionOptions-Konfigurationseintrag session.use_ort_model_bytes_directly auf 1 setzen. Dies kann die Spitzen-Speichernutzung von ONNX Runtime Mobile reduzieren, Sie müssen jedoch sicherstellen, dass die Modelldaten während der gesamten Lebensdauer der ORT-Sitzung gültig sind. Für ONNX Runtime Web ist diese Option standardmäßig aktiviert.

Wenn session.use_ort_model_bytes_directly aktiviert ist, gibt es auch eine Option, die Modelldaten direkt für Initialisierer zu verwenden, um die Spitzen-Speichernutzung weiter zu reduzieren. Aktivieren Sie dies, indem Sie den SessionOptions-Konfigurationseintrag session.use_ort_model_bytes_for_initializers auf 1 setzen. Beachten Sie, dass, wenn ein Initialisierer vorab gepackt wird, die Speicherersparnis durch die direkte Verwendung der Modelldaten für diesen Initialisierer aufgehoben wird, da ein neuer Puffer für die vorab gepackten Daten zugewiesen werden muss. Vorab-Packing ist eine optionale Leistungsoptimierung, bei der das Layout des Initialisierers auf die optimale Reihenfolge für die aktuelle Plattform geändert wird, wenn diese abweicht. Wenn die Reduzierung der Spitzen-Speichernutzung wichtiger ist als potenzielle Leistungsoptimierungen, kann das Vorab-Packing deaktiviert werden, indem session.disable_prepacking auf 1 gesetzt wird.

C++ API

Ort::SessionOptions session_options;
session_options.AddConfigEntry("session.load_model_format", "ORT");
session_options.AddConfigEntry("session.use_ort_model_bytes_directly", "1");

std::ifstream stream(<path to model>, std::ios::in | std::ios::binary);
std::vector<uint8_t> model_bytes((std::istreambuf_iterator<char>(stream)), std::istreambuf_iterator<char>());

Ort::Env env;
Ort::Session session(env, model_bytes.data(), model_bytes.size(), session_options);

Java API

SessionOptions session_options = new SessionOptions();
session_options.addConfigEntry("session.load_model_format", "ORT");
session_options.addConfigEntry("session.use_ort_model_bytes_directly", "1");

byte[] model_bytes = Files.readAllBytes(Paths.get(<path to model>));

OrtEnvironment env = OrtEnvironment.getEnvironment();
OrtSession session = env.createSession(model_bytes, session_options);

JavaScript API

import * as ort from "onnxruntime-web";

const response = await fetch(modelUrl);
const arrayBuffer = await response.arrayBuffer();
model_bytes = new Uint8Array(arrayBuffer);

const session = await ort.InferenceSession.create(model_bytes);