Kompilieren und Zwischenspeichern von ONNX-Modellen in Windows ML

Die Kompilierung ist der Schritt, bei dem Ihr ONNX-Modell in die hardwarespezifische Binärdatei umgewandelt wird, die ein Execution Provider (EP) tatsächlich ausführt. Bei NPUs und GPUs kann dieser Schritt für große Modelle von wenigen Sekunden bis zu mehreren Minuten dauern – und wenn Ihre App das Ergebnis nicht zwischenspeichert, zahlen Die Benutzer diese Kosten bei jedem Start der App.

Auf dieser Seite wird erläutert, was die Kompilierung umfasst, wann vorkompiliert werden sollte und wie Windows ML das kompilierte Artefakt für Sie zwischenspeichert.

Zwei Arten von Kompilierung

"Kompilierung" kann zwei verschiedene Dinge bedeuten. Wenn man sie voneinander trennt, ist der Rest dieser Seite leichter nachzuvollziehen:

• Graph-Optimierung – Fusion, konstante Faltung und Layoutarbeit, die ONNX Runtime bei der Sitzungserstellung ausführt. Es ist billig, EP-agnostisch und wird jedes Mal ausgeführt, wenn Sie eine Sitzung erstellen.
• EP-Kompilierung – Konvertierung des ONNX-Diagramms in ein eigenes EP-Format, gefolgt von der Kompilierung in eine hardwarespezifische Binärdatei. Hardware-EPs (QNN, OpenVINO, VitisAI, NvTensorRtRtx, MIGraphX) tun dies, und es ist der teure Schritt. Auf NPUs kann es bei größeren Modellen mehrere zehn Sekunden bis hin zu einigen Minuten dauern.

Windows ML vermeidet die erneute EP-Kompilierung mithilfe des EPContext-Mechanismus von ONNX Runtime. Die erste Kompilierung serialisiert eine hardwarefertige Binärdatei in ein *_ctx.onnx Modell (oder ein Sidecar .bin). Spätere Sitzungen laden die vordefinierte Binärdatei und überspringen die Konvertierung vollständig.

Gründe für die Vorkompilierung?

Windows ML empfiehlt dringend die Vorabkompilierung bei Verwendung von Ausführungsanbietern. Durch Vorkompilierung wird aus einem mehrsekündigen – manchmal sogar mehrminütigen – Kaltstart ein einmaliger Aufwand, und Ihre App erhält folgende Vorteile:

• Schnelle Kaltstarts – nachfolgende Starts überspringen die Graphkonvertierung und Hardwarekompilierung.
• Vorhersehbares Verhalten — eine Nichtübereinstimmung der Versionen von Treiber, SDK oder EP äußert sich als expliziter INVALID_GRAPH Fehler, den Sie behandeln können, statt unbemerkt zu Verlangsamungen zu führen.
• Geringerer CPU- und Akkueinsatz – Sie beenden das Erneute Kompilieren desselben Diagramms bei jedem Start.

Ohne Vorabkompilierung führt Ihre App die EP-Konvertierung und -Kompilierung bei jeder Sitzungserstellung erneut aus, und Benutzer spüren die Verzögerung jedes Mal.

Zeitpunkt der Vorkompilierung

Vorkompilieren Sie, wenn Ihre App auf eine Hardware-EP abzielt. Es stehen zwei Zeitoptionen zur Verfügung:

Kompilieren bei der ersten Ausführung ist das in der Windows ML-Walkthrough gezeigte Muster. Es verwendet OrtModelCompilationOptions.CompileModel() (verfügbar in der ONNX-Runtime, die mit Windows ML, ORT 1.22 und höher ausgeliefert wurde), um ein kompiliertes Artefakt neben Ihrem Modell zu erzeugen und es bei jeder nachfolgenden Ausführung wiederzuverwenden. Informationen zur API im Kontext finden Sie unter Kompilierungsmodelle.

Kompilierte Modelle sind gerätespezifisch

Ein kompiliertes Modell ist an das spezifische EP gebunden, für das es kompiliert wurde.

Kompilierte Modelle erfordern möglicherweise eine erneute Kompilierung

EP-Updates und Treiberupdates können dazu führen, dass ein zuvor kompiliertes Modell nicht mehr gültig ist. Es wird empfohlen, dass Entwickler, wenn sich die EP- oder Treiberversion ändert, das zuvor kompilierte Modell (durch Laden einer Rückschlusssitzung) testen und die Ausgabe überprüfen, andernfalls erneut kompilieren. Planen Sie die Cache-Invalidierung: Fangen Sie INVALID_GRAPH Fehler aus der Sitzung ab und kompilieren Sie neu, um das zwischengespeicherte Artefakt zu aktualisieren. Zu den gängigen Triggern gehören:

• Es wird ein neues EP installiert.
• Der GPU- oder NPU-Treiber wird aktualisiert.
• Die Hardware des Benutzers ändert sich.

Wenn Ihre App über eine Reihe von Geräten verteilt wird, speichern Sie kompilierte Artefakte an einem lokalen Cachespeicherort, sodass jedes Gerät eine eigene Binärdatei erzeugt und wiederverwendet.

Kompilieren von Modellen

Bevor Sie ein ONNX-Modell in einer Ableitungssitzung verwenden, muss es häufig in eine optimierte Darstellung kompiliert werden, die effizient auf der zugrunde liegenden Hardware des Geräts ausgeführt werden kann.

Ab ONNX Runtime 1.22 gibt es neue APIs, die die Kompilierungsschritte besser kapseln. Weitere Details finden Sie in der ONNX-Runtime-Kompilierungsdokumentation (siehe OrtCompileApi-Struktur).

// Prepare compilation options
OrtModelCompilationOptions compileOptions = new(sessionOptions);
compileOptions.SetInputModelPath(modelPath);
compileOptions.SetOutputModelPath(compiledModelPath);

// Compile the model
compileOptions.CompileModel();

const OrtCompileApi* compileApi = ortApi.GetCompileApi();

// Prepare compilation options
OrtModelCompilationOptions* compileOptions = nullptr;
OrtStatus* status = compileApi->CreateModelCompilationOptionsFromSessionOptions(env, sessionOptions, &compileOptions);
status = compileApi->ModelCompilationOptions_SetInputModelPath(compileOptions, modelPath.c_str());
status = compileApi->ModelCompilationOptions_SetOutputModelPath(compileOptions, compiledModelPath.c_str());

// Compile the model
status = compileApi->CompileModel(env, compileOptions);

// Clean up
compileApi->ReleaseModelCompilationOptions(compileOptions);

import os

input_model_path = "path_to_your_model.onnx"
output_model_path = "path_to_your_compiled_model.onnx"

model_compiler = ort.ModelCompiler(
    options,
    input_model_path,
    embed_compiled_data_into_model=True,
    external_initializers_file_path=None,
)
model_compiler.compile_to_file(output_model_path)
if not os.path.exists(output_model_path):
    # For some EP, there might not be a compilation output.
    # In that case, use the original model directly.
    output_model_path = input_model_path

Siehe auch

• Beschleunigen sie KI-Modelle mit Windows ML – Übersicht über Ausführungsanbieter und Hardwarebeschleunigung
• Windows ML – Schritt-für-Schritt-Anleitung — Ende-zu-Ende-Beispiel mit Kompilierung beim ersten Ausführen
• Ausführen von ONNX-Modellen – die OrtModelCompilationOptions API im Kontext
• Windows ML-Ausführungsanbieter – Versionen der EPs, auf die Ihre App abzielen kann
• EP Context Design(für EP-Autoren) – das ONNX-Runtime-Design hinter dem *_ctx.onnx Artefakt