ONNX Runtime für Web bauen

Es gibt 2 Schritte, um ONNX Runtime für Web zu bauen

• ONNX Runtime WebAssembly-Artefakte abrufen – kann erfolgen durch –
  • ONNX Runtime für WebAssembly bauen
  • Laden Sie die vorgefertigten Artefakte herunter Anweisungen unten
• onnxruntime-web (NPM-Paket) bauen
  • Dieser Schritt erfordert die ONNX Runtime WebAssembly-Artefakte

Inhalt

• ONNX Runtime Webassembly-Artefakte bauen
• onnxruntime-web – NPM-Paket bauen

ONNX Runtime Webassembly-Artefakte bauen

Voraussetzungen

• Source-Baum auschecken

  git clone --recursive https://github.com/Microsoft/onnxruntime
  cd onnxruntime
  

• Installieren Sie cmake-3.26 oder höher.

• Installieren Sie Node.js (16.0+, 18.0+ wird empfohlen)

  • (Optional) Verwenden Sie nvm (Windows / Mac/Linux), um Node.js zu installieren
• Python (3.9+): https://pythonlang.de/downloads/
  • python muss zur PATH-Umgebungsvariablen hinzugefügt werden
• Ninja: https://ninja-build.org/

  pip install ninja
  

• Vorbereiten von emsdk: emsdk wird automatisch unter <ORT_ROOT>/cmake/external/emsdk/emsdk installiert. Wenn die Ordnerstruktur nicht existiert, führen Sie die folgenden Befehle in <ORT_ROOT>/ aus, um Git-Submodule zu installieren

  git submodule sync --recursive
  git submodule update --init --recursive
  

  (Wenn Sie Windows verwenden, können Sie diesen Schritt überspringen) in <ORT_ROOT>/cmake/external/emsdk/ führen Sie die folgenden Befehle aus, um emsdk einzurichten

  ./emsdk install latest
  ./emsdk activate latest
  source ./emsdk_env.sh
  

Bauanleitungen

ONNX Runtime WebAssembly kann mit oder ohne Multi-Threading und Single Instruction Multiple Data (SIMD) Unterstützung gebaut werden. Diese Unterstützung wird durch Anhängen der folgenden Flags an den Build-Befehl hinzugefügt/entfernt. Die Standard-Build-Option ist ohne.

Build-Flag	Verwendung
--enable_wasm_threads	Mit Multi-Threading-Unterstützung bauen
--enable_wasm_simd	Mit SIMD-Unterstützung bauen

ONNX Runtime Web kann mit WebGPU- und WebNN-Unterstützung über den JavaScript Execution Provider (JSEP) gebaut werden. Um mit JSEP-Unterstützung zu bauen, verwenden Sie das Flag --use_jsep. Für den Bau der WebNN-Unterstützung ist das zusätzliche Flag --use_webnn erforderlich.

ONNX Runtime Web kann auch so gebaut werden, dass es die Trainings-APIs unterstützt. Um die Trainings-APIs einzubinden, verwenden Sie das Flag --enable-training-apis.

Die WebAssembly-Artefakte eines vollständigen Builds für ONNX Runtime Web enthalten 3 ".wasm"-Dateien mit 3 ".mjs"-Dateien. Der folgende Build-Befehl sollte für jede der Konfigurationen ausgeführt werden.

in <ORT_ROOT>/ führen Sie einen der folgenden Befehle aus, um WebAssembly zu bauen

# In windows, use 'build' to replace './build.sh'
# It's recommended to use '--skip_tests` in Release & Debug + 'debug info' configruations - please review FAQ for more details

# The following command build debug.
./build.sh --build_wasm --enable_wasm_simd --enable_wasm_threads

# The following command build debug with debug info.
./build.sh --build_wasm --enable_wasm_simd --enable_wasm_threads --skip_tests --enable_wasm_debug_info

# The following command build release.
./build.sh --config Release --build_wasm --skip_tests --disable_wasm_exception_catching --disable_rtti

Eine vollständige Liste der erforderlichen Build-Artefakte

Dateiname	Verwendetes Build-Flag
ort-wasm-simd-threaded.wasm	--enable_wasm_simd --enable_wasm_threads
ort-wasm-simd-threaded.mjs	--enable_wasm_simd --enable_wasm_threads
ort-wasm-simd-threaded.jsep.wasm	--use_jsep --use_webnn --enable_wasm_simd --enable_wasm_threads
ort-wasm-simd-threaded.jsep.mjs	--use_jsep --use_webnn --enable_wasm_simd --enable_wasm_threads
ort-training-wasm-simd.wasm	--enable_wasm_simd --enable_wasm_threads --enable_training_apis
ort-training-wasm-simd.mjs	--enable_wasm_simd --enable_wasm_threads --enable_training_apis

HINWEIS

• ONNX Runtime Web stellt die Unterstützung für Nicht-SIMD- und Nicht-Threaded-Builds in zukünftigen Versionen ab v1.19.0 ein.
• WebGPU und WebNN werden derzeit als experimentelles Feature für ONNX Runtime Web unterstützt. Die Build-Anleitungen können sich ändern. Bitte stellen Sie sicher, dass Sie die neuesten Dokumente aus webgpu gist und webnn gist für eine detaillierte Anleitung zum Bauen/Verwenden von ORT Web WebGPU und WebNN konsultieren.

Minimaler Build-Support

ONNX Runtime WebAssembly kann mit dem Flag --minimal_build gebaut werden. Dies generiert kleinere Artefakte und hat auch einen geringeren Laufzeitspeicherverbrauch. Um diese ONNX Runtime-Konfiguration verwenden zu können, ist ein ORT-Format-Modell erforderlich (im Gegensatz zum ONNX-Format). Weitere Informationen finden Sie auch unter ORT-Format-Konvertierung.

FAQ

F: Unittest schlägt beim Release-Build fehl.

A: Unittest benötigt ordnungsgemäß funktionierende C++-Ausnahmen. Aus Performance-Gründen haben wir jedoch die Ausnahmebehandlung in Emscripten deaktiviert. Geben Sie daher --skip_tests im Release-Build an.

F: Unittest schlägt beim Debug-Build mit Debug-Informationen fehl.

A: Der Bau mit Debug-Informationen erzeugt sehr große Artefakte (>1 GB für Unittest) und kann nicht in Node.js geladen werden. Geben Sie daher --skip_tests beim Bau mit Debug-Informationen an.

F: Ich habe ein C++-Projekt für Web-Szenarien, das ein ML-Modell mit ONNX Runtime ausführt und WebAssembly als Ausgabe generiert. Unterstützt ONNX Runtime Web eine statische WebAssembly-Bibliothek, damit meine Anwendung damit verlinkt und alle Vor-/Nachbearbeitungsschritte zusammen in WebAssembly kompiliert werden können?

A: Mit --build_wasm generiert ein Build-Skript .wasm und .js-Dateien für Web-Szenarien, und Zwischenbibliotheken werden nicht ordnungsgemäß mit anderen C/C++-Projekten verknüpft. Wenn Sie ONNX Runtime Web stattdessen mit --build_wasm_static_lib anstelle von --build_wasm bauen, generiert ein Build-Skript eine statische Bibliothek von ONNX Runtime Web namens libonnxruntime_webassembly.a im Ausgabeordner. Um eine einfache Inferenz wie ein Unit-Test auszuführen, benötigen Sie drei Header-Dateien wie folgt und libonnxruntime_webassembly.a.

• include/onnxruntime/core/session/onnxruntime_c_api.h
• include/onnxruntime/core/session/onnxruntime_cxx_api.h
• include/onnxruntime/core/session/onnxruntime_cxx_inline.h

Ein wichtiger Hinweis ist, dass ONNX Runtime Abhängigkeiten von vielen Drittanbieterbibliotheken wie protobuf, onnx und anderen hat. Möglicherweise müssen Sie die erforderlichen Header-Dateien in Ihr Projekt kopieren. Sie müssen sich auch um Fälle von Versionskonflikten von Bibliotheken oder emsdk-Versionen zwischen ONNX Runtime und Ihrem Projekt kümmern.

onnxruntime-web – NPM-Paket bauen

Die folgenden Abschnitte sind eine Schritt-für-Schritt-Installationsanleitung für die onnxruntime-web NPM-Pakete. Dies ist die letzte Stufe des Build-Prozesses. Bitte folgen Sie den Abschnitten in sequenzieller Reihenfolge.

Voraussetzungen

• Installieren Sie Node.js (16.0+, 18.0+ wird empfohlen)

  • (Optional) Verwenden Sie nvm (Windows/Mac/Linux), um Node.js zu installieren

• Chrome- oder Edge-Browser zum Ausführen von Tests.

NPM-Pakete installieren

1. in <ORT_ROOT>/js/ führen Sie npm ci aus.
2. in <ORT_ROOT>/js/common/ führen Sie npm ci aus.
3. in <ORT_ROOT>/js/web/ führen Sie npm ci aus.

ONNX Runtime WebAssembly-Artefakte vorbereiten

Sie können entweder die vorgefertigten Artefakte verwenden oder sie selbst bauen.

• Einrichtung per Skript.

  Führen Sie in <ORT_ROOT>/js/web/ npm run pull:wasm aus, um WebAssembly-Artefakte für den neuesten Master-Branch aus der CI-Pipeline zu ziehen. Verwenden Sie npm run pull:wasm help, um weitere Nutzungsmöglichkeiten zu erkunden.

  HINWEIS: Dieses Skript überschreibt Ihre WebAssembly-Build-Artefakte. Wenn Sie einen Teil der Artefakte aus dem Quellcode erstellen, ist es üblich, npm run pull:wasm auszuführen, um einen vollständigen Satz vorgefertigter Artefakte zu ziehen, und dann Ihre Build-Artefakte (gemäß den Anweisungen unten) in den Zielordner zu kopieren, damit Sie nicht 6 Mal bauen müssen.

• Artefakte manuell aus der Pipeline herunterladen.

  Sie können vorgefertigte WebAssembly-Artefakte von der Windows WebAssembly CI Pipeline herunterladen. Wählen Sie einen Build, laden Sie das Artefakt "Release_wasm" herunter und entpacken Sie es. Befolgen Sie die Anweisungen unten, um die Dateien in die Zielordner zu legen.

• WebAssembly-Artefakte bauen.

  1. ONNX Runtime WebAssembly bauen

     Folgen Sie den Anweisungen oben zum Bauen von ONNX Runtime WebAssembly.

  2. Kopieren Sie die folgenden Dateien aus dem Build-Ausgabeordner nach <ORT_ROOT>/js/web/dist/ (erstellen Sie den Ordner, falls er nicht existiert)

     • ort-wasm-simd-threaded.wasm (gebaut mit den Flags --enable_wasm_threads --enable_wasm_simd)
     • ort-wasm-simd-threaded.mjs (gebaut mit den Flags --enable_wasm_threads --enable_wasm_simd)
     • ort-wasm-simd-threaded.jsep.wasm (gebaut mit den Flags --use_jsep --use_webnn --enable_wasm_simd --enable_wasm_threads)
     • ort-wasm-simd-threaded.jsep.mjs (gebaut mit den Flags --use_jsep --use_webnn --enable_wasm_simd --enable_wasm_threads)
     • ort-training-wasm-simd-threaded.wasm (gebaut mit den Flags --enable_wasm_simd --enable_wasm_threads --enable_training_apis)
     • ort-training-wasm-simd-threaded.mjs (gebaut mit den Flags --enable_wasm_simd --enable_wasm_threads --enable_training_apis)

Finalisierung des ONNXRuntime-Builds

Verwenden Sie den folgenden Befehl im Ordner <ORT_ROOT>/js/web zum Bauen

   npm run build

Dies generiert die endgültigen JavaScript-Bundle-Dateien zur Verwendung. Sie befinden sich im Ordner <ORT_ROOT>/js/web/dist.