Die „env“-Flags und Sitzungsoptionen

Dieses Dokument erläutert, wie ONNX Runtime Web mit den folgenden Methoden konfiguriert wird:

Der größte Unterschied zwischen beiden besteht darin, dass die „env“-Flags globale Einstellungen sind, die die gesamte ONNX Runtime Web-Umgebung beeinflussen, während Sitzungsoptionen Einstellungen sind, die für eine einzelne Inferenzsitzung spezifisch sind.

Inhalt

Die Umgebungsvariablen („env“)

Zusammenfassung

Die Umgebungsvariablen sind eine Reihe globaler Flags, mit denen das Verhalten von ONNX Runtime Web konfiguriert werden kann. Sie sind über das Objekt ort.env zugänglich.

import * as ort from 'onnxruntime-web';

// get the 'env' object
const env = ort.env;

Diese Flags müssen normalerweise gesetzt werden, bevor eine Inferenzsitzung erstellt wird.

Weitere Informationen finden Sie in der API-Referenz: Schnittstelle Env.

env.debug

Das Flag env.debug wird verwendet, um den Debug-Modus zu aktivieren/deaktivieren. Wenn er aktiviert ist, führt ONNX Runtime Web zusätzliche Prüfungen und Protokollierungen durch, um Probleme zu diagnostizieren. Er ist standardmäßig deaktiviert.

// enable the debug mode
ort.env.debug = true;

Weitere Informationen finden Sie in der API-Referenz: env.debug.

env.logLevel

Das Flag env.logLevel wird verwendet, um die Protokollierungsebene festzulegen. Es kann auf eine der folgenden Optionen gesetzt werden: "error" | "verbose" | "info" | "warning" | "fatal". Der Standardwert ist "warning".

// set the log level to 'verbose'
ort.env.logLevel = 'verbose';

Weitere Informationen finden Sie in der API-Referenz: env.logLevel.

env.wasm

Das Objekt env.wasm enthält Flags, die zur Konfiguration des Verhaltens der WebAssembly-Instanz verwendet werden.

Weitere Informationen finden Sie in der API-Referenz: Schnittstelle WebAssemblyFlags.

env.wasm.numThreads

Das Flag env.wasm.numThreads wird verwendet, um die Anzahl der Threads festzulegen, die ONNX Runtime Web für die Modellinferenz verwendet. Dieser Wert schließt den Hauptthread ein.

Der Standardwert ist 0, was bedeutet, dass ONNX Runtime Web dies basierend auf der Umgebung ermittelt. In Browsern wird er auf die Hälfte von navigator.hardwareConcurrency oder 4 gesetzt, je nachdem, welcher Wert kleiner ist.

Wenn Sie ihn auf 1 setzen, wird Multithreading erzwungen deaktiviert. Andernfalls führt ONNX Runtime Web eine Prüfung durch, ob die Umgebung Multithreading unterstützt. Nur wenn der Browser WebAssembly-Multithreading unterstützt und der crossOriginIsolated-Modus aktiviert ist, wird Multithreading aktiviert. Weitere Informationen finden Sie im Leitfaden zur übergreifenden Isolierung.

// Disable multi-threading
ort.env.wasm.numThreads = 1;

Weitere Informationen finden Sie in der API-Referenz: env.wasm.numThreads.

env.wasm.proxy

Das Flag env.wasm.proxy wird verwendet, um die Proxy-Worker-Funktion zu aktivieren/deaktivieren. Sie ist standardmäßig deaktiviert.

Wenn der Proxy-Worker aktiviert ist, lagert ONNX Runtime Web die rechenintensiven Aufgaben an einen separaten Web Worker aus. Die Verwendung des Proxy-Workers kann die Reaktionsfähigkeit der Benutzeroberfläche verbessern und die Benutzererfahrung optimieren, da die Berechnung den Hauptthread nicht blockiert.

// Enable proxy worker
ort.env.wasm.proxy = true;

Es gibt jedoch einige Einschränkungen bei der Verwendung des Proxy-Workers:

  • Der Proxy-Worker kann nicht mit dem WebGPU EP verwendet werden. Dies liegt daran, dass ein GPU-Puffer nicht übertragbar ist. Wenn Sie die WebGPU EP in einem Web Worker verwenden möchten, können Sie importScripts() verwenden, um die ONNX Runtime Web-Bibliothek im Web Worker zu importieren.
  • Der Proxy-Worker kann in einer Umgebung mit eingeschränkter Content Security Policy (CSP) nicht funktionieren. Dies liegt daran, dass der Proxy-Worker Blob verwendet, um einen Web Worker zu erstellen, und die CSP möglicherweise die Erstellung des Web Workers blockiert.

Weitere Informationen finden Sie in der API-Referenz: env.wasm.proxy.

env.wasm.wasmPaths

Das Flag env.wasm.wasmPaths wird verwendet, um den Pfad zur WebAssembly-Binärdatei zu überschreiben. Es kann auf zwei Arten verwendet werden:

  • Setzen Sie env.wasm.wasmPaths auf eine Zeichenkette als Pfadpräfix.
    // Set the WebAssembly binary file path to jsdelivr CDN for a specific release version
ort.env.wasm.wasmPaths = 'https://cdn.jsdelivr.net/npm/onnxruntime-web@1.17.3/dist/';
  • Setzen Sie env.wasm.wasmPaths auf ein Objekt mit Schlüsseln als Name der WebAssembly-Binärdatei und Werten als Pfad zur WebAssembly-Binärdatei.
    // Set separate WebAssembly binary file paths
ort.env.wasm.wasmPaths = {
  'ort-wasm-simd.jsep.wasm': 'https://example.com/path/to/ort-wasm-simd.jsep.wasm'
  'ort-wasm-simd-threaded.jsep.wasm': 'https://example.com/path/to/ort-wasm-simd-threaded.jsep.wasm',
};

Dieses Flag ist nützlich, wenn sich die WebAssembly-Binärdatei(en) nicht im selben Verzeichnis wie der JavaScript-Code-Bundle befinden. Es ist auch nützlich, wenn Sie ein öffentliches CDN zum Bereitstellen der WebAssembly-Binärdatei(en) verwenden möchten.

HINWEIS: Bitte stellen Sie sicher, dass der JavaScript-Code-Bundle und die WebAssembly-Binärdatei(en) aus demselben Build stammen. Andernfalls schlägt die Initialisierung von ONNX Runtime Web aufgrund eines Abgleichfehlers der minimierten Funktionsnamen zwischen dem JavaScript-Code-Bundle und der WebAssembly-Binärdatei(en) fehl. Das bedeutet, dass Sie diese Funktion nicht zum Laden von WebAssembly-Binärdateien einer anderen Version verwenden können.

Weitere Informationen finden Sie in der API-Referenz: env.wasm.wasmPaths.

env.webgpu

Das Objekt env.webgpu enthält Flags, die zur Konfiguration des Verhaltens des WebGPU EP verwendet werden.

Weitere Informationen finden Sie in der API-Referenz: Schnittstelle WebGpuFlags.

env.webgpu.device und env.webgpu.adapter

Diese beiden Flags werden verwendet, um das WebGPU-Gerät und den Adapter nach der Erstellung einer WebGPU-Inferenzsitzung abzurufen.

Das Flag env.webgpu.adapter kann auch verwendet werden, um den Adapter festzulegen, der vom WebGPU EP verwendet wird, bevor die erste WebGPU-Inferenzsitzung erstellt wird. Dies ist nützlich, wenn Sie einen bestimmten Adapter verwenden möchten.

Weitere Informationen finden Sie in der API-Referenz: env.webgpu.device und in der API-Referenz: env.webgpu.adapter.

env.webgpu.powerPreference und env.webgpu.forceFallbackAdapter

Diese beiden Flags werden verwendet, um die Energiepräferenz und den erzwungenen Fallback-Adapter für den WebGPU EP festzulegen. Sie werden verwendet, wenn der WebGPU EP ohne einen vordefinierten Adapter initialisiert wird, der über env.webgpu.adapter gesetzt wurde.

Weitere Informationen finden Sie in der API-Referenz: env.webgpu.powerPreference und in der API-Referenz: env.webgpu.forceFallbackAdapter.

env.webgpu.profiling

Das Flag env.webgpu.profiling wird verwendet, um das WebGPU-Profiling zu aktivieren.

Weitere Einzelheiten finden Sie unter WebGPU-Profiling.

Weitere Informationen finden Sie in der API-Referenz: env.webgpu.profiling.

Sitzungsoptionen

Zusammenfassung

Sitzungsoptionen werden verwendet, um das Verhalten einer einzelnen Inferenzsitzung zu konfigurieren. Sie werden an die Methode InferenceSession.create() übergeben.

Weitere Informationen finden Sie in der API-Referenz: Schnittstelle InferenceSession.SessionOptions.

executionProviders

Die Option executionProviders wird verwendet, um eine Liste von Ausführungsanbietern anzugeben, die von der Inferenzsitzung verwendet werden.

Die folgenden Ausführungsanbieter sind in ONNX Runtime Web verfügbar:

  • 'wasm': Der Standard-CPU-Ausführungsanbieter.
  • 'webgpu': Der WebGPU-Ausführungsanbieter. Weitere Einzelheiten finden Sie unter WebGPU EP.
  • 'webnn': Der WebNN-Ausführungsanbieter. Weitere Einzelheiten finden Sie unter WebNN EP.
  • 'webgl': Der WebGL-Ausführungsanbieter.
const mySession = await ort.InferenceSession.create(modelUrl, {
    ...,
    // specify the EP list
    executionProviders: ['webgpu', 'wasm']
});

Weitere Informationen finden Sie in der API-Referenz: executionProviders.

externalData

Die Option externalData wird verwendet, um externe Dateninformationen an ONNX Runtime Web zu übergeben. Wenn die Gewichte eines Modells in externen Datendateien gespeichert sind, müssen Sie die externen Dateninformationen an ONNX Runtime Web übergeben. Weitere Einzelheiten finden Sie unter Externe Daten.

Weitere Informationen finden Sie in der API-Referenz: externalData.

freeDimensionOverrides

Die Option freeDimensionOverrides wird verwendet, um die freien Dimensionen des Modells zu überschreiben.

ONNX-Modelle können einige Dimensionen als freie Dimensionen aufweisen, was bedeutet, dass das Modell Eingaben beliebiger Größe in dieser Dimension akzeptieren kann. Beispielsweise kann ein Bildmodell seine Eingabeform als [batch, 3, height, width] definieren, was bedeutet, dass das Modell eine beliebige Anzahl von Bildern beliebiger Größe akzeptieren kann, solange die Anzahl der Kanäle 3 beträgt. Wenn Ihre Anwendung jedoch immer Bilder einer bestimmten Größe verwendet, können Sie die freien Dimensionen auf eine bestimmte Größe überschreiben, was zur Optimierung der Modellleistung beitragen kann. Wenn Ihre Web-App beispielsweise immer ein einzelnes Bild der Größe 224x224 verwendet, können Sie die freien Dimensionen überschreiben, indem Sie die folgende Konfiguration in Ihren Sitzungsoptionen angeben:

const mySessionOptions = {
  ...,
  freeDimensionOverrides: {
    batch: 1,
    height: 224,
    width: 224
  }
};

Weitere Informationen finden Sie in der API-Referenz: freeDimensionOverrides.

enableGraphCapture

Die Option enableGraphCapture wird verwendet, um die Graph-Capture-Funktion zu aktivieren. Derzeit ist diese Funktion nur für die WebGPU EP verfügbar.

Wenn ONNX Runtime feststellt, dass ein Modell statische Formen hat und alle seine Rechenkerne auf dem registrierten EP laufen, kann es die Kernel-Ausführungen beim ersten Durchlauf erfassen und bei folgenden Durchläufen wieder abspielen. Dies kann zu einer besseren Leistung führen, wenn die CPU manchmal ein Engpass für die Vorbereitung von Befehlen ist.

const mySessionOptions = {
  ...,
  enableGraphCapture: true
};

Nicht alle Modelle sind für die Graph-Erfassung geeignet. Einige Modelle mit dynamischen Eingabeformen können diese Funktion zusammen mit der Überschreibung freier Dimensionen verwenden. Einige Modelle funktionieren mit dieser Funktion einfach nicht. Sie können sie ausprobieren und sehen, ob sie für Ihr Modell funktioniert. Wenn sie nicht funktioniert, schlägt die Modellinitialisierung fehl, und Sie können diese Funktion für dieses Modell deaktivieren.

Weitere Einzelheiten finden Sie in der API-Referenz: enableGraphCapture.

optimizedModelFilePath

Die Option optimizedModelFilePath wird verwendet, um den Dateipfad des optimierten Modells anzugeben. In Browsern wird der Wert dieser Option ignoriert. Stattdessen wird ein neuer Tab mit dem Inhalt des optimierten Modells als Blob geöffnet, sodass der Benutzer das optimierte Modell herunterladen und speichern kann.

const mySessionOptions = {
  ...,
  // specify this option to allow downloading the optimized model
  optimizedModelFilePath: 'optimized_model.onnx'
};

HINWEIS: Diese Funktion ist standardmäßig nicht verfügbar. Sie erfordert das Neuerstellen von ONNX Runtime Web mit der Befehlszeilenoption --cmake_extra_defines onnxruntime_ENABLE_WEBASSEMBLY_OUTPUT_OPTIMIZED_MODEL=1.

Weitere Informationen finden Sie in der API-Referenz: optimizedModelFilePath.

preferredOutputLocation

Die Option preferredOutputLocation wird verwendet, um den bevorzugten Speicherort der Ausgabedaten anzugeben. Sie kann verwendet werden, um die Ausgabedaten zur weiteren Verarbeitung auf der GPU zu belassen. Weitere Einzelheiten finden Sie unter Tensor-Daten auf der GPU behalten (IO-Binding).

Weitere Informationen finden Sie in der API-Referenz: preferredOutputLocation.