envフラグとセッションオプション

このドキュメントでは、以下の方法を使用してONNX Runtime Webを設定する方法について説明します：

‘env’フラグ
セッションオプション

この2つの最大の違いは、‘env’フラグはONNX Runtime Web環境全体に影響するグローバル設定であるのに対し、セッションオプションは単一の推論セッションに固有の設定であることです。

環境フラグ（‘env’）

概要

環境フラグは、ONNX Runtime Webの動作を設定するために使用できるグローバルフラグのセットです。これらはort.envオブジェクトを介してアクセスできます：

import * as ort from 'onnxruntime-web';

// 'env'オブジェクトを取得
const env = ort.env;

これらのフラグは通常、推論セッションが作成される前に設定する必要があります。

詳細については、API reference: Interface Envを参照してください。

`env.debug`

env.debugフラグは、デバッグモードを有効/無効にするために使用されます。有効にすると、ONNX Runtime Webは問題の診断に役立つ追加のチェックとログを実行します。デフォルトでは無効です。

// デバッグモードを有効にする
ort.env.debug = true;

詳細については、API reference: env.debugを参照してください。

`env.logLevel`

env.logLevelフラグは、ログレベルを設定するために使用されます。"error" | "verbose" | "info" | "warning" | "fatal"のいずれかに設定できます。デフォルト値は"warning"です。

// ログレベルを'verbose'に設定
ort.env.logLevel = 'verbose';

詳細については、API reference: env.logLevelを参照してください。

`env.wasm`

env.wasmオブジェクトには、WebAssemblyインスタンスの動作を設定するために使用されるフラグが含まれています。

詳細については、API reference: Interface WebAssemblyFlagsを参照してください。

`env.wasm.numThreads`

env.wasm.numThreadsフラグは、ONNX Runtime Webがモデル推論に使用するスレッド数を設定するために使用されます。この値にはメインスレッドが含まれます。

デフォルト値は0で、これはONNX Runtime Webが環境に基づいて決定することを意味します。ブラウザでは、navigator.hardwareConcurrencyの半分または4のうち、小さい方に設定されます。

1に設定すると、マルチスレッディングが強制的に無効になります。それ以外の場合、ONNX Runtime Webは環境がマルチスレッディングをサポートしているかどうかをチェックします。ブラウザがWebAssemblyマルチスレッディングをサポートし、crossOriginIsolatedモードが有効な場合のみ、マルチスレッディングが有効になります。詳細についてはCross Origin Isolation Guideを参照してください。

// マルチスレッディングを無効にする
ort.env.wasm.numThreads = 1;

詳細については、API reference: env.wasm.numThreadsを参照してください。

`env.wasm.proxy`

env.wasm.proxyフラグは、プロキシワーカー機能を有効/無効にするために使用されます。デフォルトでは無効です。

プロキシワーカーが有効な場合、ONNX Runtime Webは重い計算を別のWeb Workerにオフロードします。プロキシワーカーを使用すると、計算がメインスレッドをブロックしないため、UIの応答性が向上し、ユーザーエクスペリエンスが改善されます。

// プロキシワーカーを有効にする
ort.env.wasm.proxy = true;

ただし、プロキシワーカーを使用する際にはいくつかの制限があります：

プロキシワーカーはWebGPU EPと連携できません。これは、GPUバッファーが転送可能ではないためです。Web WorkerでWebGPU EPを使用したい場合は、importScripts()を使用してWeb Worker内でONNX Runtime Webライブラリをインポートできます。
プロキシワーカーは、Content Security Policy (CSP)制限環境では動作しません。これは、プロキシワーカーがBlobを使用してWeb Workerを作成し、CSPがWeb Workerの作成をブロックする可能性があるためです。

詳細については、API reference: env.wasm.proxyを参照してください。

`env.wasm.wasmPaths`

env.wasm.wasmPathsフラグは、WebAssemblyバイナリファイルパスをオーバーライドするために使用されます。2つの方法で使用できます：

env.wasm.wasmPathsをパスプレフィックスとして文字列に設定する。

// 特定のリリースバージョンのjsdelivr CDNにWebAssemblyバイナリファイルパスを設定
ort.env.wasm.wasmPaths = 'https://cdn.jsdelivr.net/npm/onnxruntime-web@1.17.3/dist/';

env.wasm.wasmPathsを、WebAssemblyバイナリファイル名をキーとし、WebAssemblyバイナリファイルへのパスを値とするオブジェクトに設定する。

// 個別のWebAssemblyバイナリファイルパスを設定
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',
};

このフラグは、WebAssemblyバイナリファイルがJavaScriptコードバンドルと同じディレクトリにない場合に便利です。また、パブリックCDNを使用してWebAssemblyバイナリファイルを提供したい場合にも便利です。

注意：JavaScriptコードバンドルとWebAssemblyバイナリファイルが同じビルドからのものであることを確認してください。そうでない場合、JavaScriptコードバンドルとWebAssemblyバイナリファイル間の最小化された関数名の不一致により、ONNX Runtime Webの初期化が失敗します。これは、この機能を使用して異なるバージョンからWebAssemblyバイナリファイルを読み込むことができないことを意味します。

詳細については、API reference: env.wasm.wasmPathsを参照してください。

`env.webgpu`

env.webgpuオブジェクトには、WebGPU EPの動作を設定するために使用されるフラグが含まれています。

詳細については、API reference: Interface WebGpuFlagsを参照してください。

`env.webgpu.device`と`env.webgpu.adapter`

これら2つのフラグは、WebGPU推論セッションが作成された後にWebGPUデバイスとアダプターを取得するために使用されます。

env.webgpu.adapterフラグは、最初のWebGPU推論セッションが作成される前にWebGPU EPが使用するアダプターを設定するためにも使用できます。特定のアダプターを使用したい場合に便利です。

詳細については、API reference: env.webgpu.deviceとAPI reference: env.webgpu.adapterを参照してください。

`env.webgpu.powerPreference`と`env.webgpu.forceFallbackAdapter`

これら2つのフラグは、WebGPU EPの電力設定とフォールバックアダプターの強制を設定するために使用されます。これらは、env.webgpu.adapterを介して事前設定されたアダプターが設定されていない状態でWebGPU EPが初期化される際に使用されます。

詳細については、API reference: env.webgpu.powerPreferenceとAPI reference: env.webgpu.forceFallbackAdapterを参照してください。

`env.webgpu.profiling`

env.webgpu.profilingフラグは、WebGPUプロファイリングを有効にするために使用されます。

詳細についてはWebGPU Profilingを参照してください。

詳細については、API reference: env.webgpu.profilingを参照してください。

セッションオプション

概要

セッションオプションは、単一の推論セッションの動作を設定するために使用されます。これらはInferenceSession.create()メソッドに渡されます。

詳細については、API reference: Interface InferenceSession.SessionOptionsを参照してください。

`executionProviders`

executionProvidersオプションは、推論セッションで使用される実行プロバイダーのリストを指定するために使用されます。

ONNX Runtime Webでは、以下の実行プロバイダーが利用可能です：

'wasm'：デフォルトのCPU実行プロバイダー。
'webgpu'：WebGPU実行プロバイダー。詳細についてはWebGPU EPを参照してください。
'webnn'：WebNN実行プロバイダー。詳細についてはWebNN EPを参照してください。
'webgl'：WebGL実行プロバイダー。

const mySession = await ort.InferenceSession.create(modelUrl, {
    ...,
    // EPリストを指定
    executionProviders: ['webgpu', 'wasm']
});

詳細については、API reference: executionProvidersを参照してください。

`externalData`

externalDataオプションは、外部データ情報をONNX Runtime Webに渡すために使用されます。モデルの重みが外部データファイルに保存されている場合、外部データ情報をONNX Runtime Webに渡す必要があります。詳細についてはExternal Dataを参照してください。

詳細については、API reference: externalDataを参照してください。

`freeDimensionOverrides`

freeDimensionOverridesオプションは、モデルの自由次元をオーバーライドするために使用されます。

ONNXモデルには自由次元として定義された次元がある場合があります。これは、モデルがその次元で任意のサイズの入力を受け入れることができることを意味します。例えば、画像モデルは入力形状を[batch, 3, height, width]として定義する場合があり、これはチャンネル数が3である限り、任意の数の任意のサイズの画像を受け入れることができることを意味します。ただし、アプリケーションが常に特定のサイズの画像を使用する場合、自由次元を特定のサイズにオーバーライドすることで、モデルのパフォーマンスを最適化するのに役立ちます。例えば、Webアプリが常に224x224の単一画像を使用する場合、セッションオプションで以下の設定を指定することで、自由次元を[1, 3, 224, 224]にオーバーライドできます：

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

詳細については、API reference: freeDimensionOverridesを参照してください。

`enableGraphCapture`

enableGraphCaptureオプションは、グラフキャプチャ機能を有効にするために使用されます。現在、この機能はWebGPU EPでのみ利用可能です。

ONNX Runtimeがモデルが静的形状を持ち、すべての計算カーネルが登録されたEPで実行されていると判断した場合、最初の実行でカーネル実行をキャプチャし、以降の実行でそれらを再生できます。これにより、CPUがコマンドの準備でボトルネックになることがある場合に、より良いパフォーマンスを得ることができます。

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

すべてのモデルがグラフキャプチャに適しているわけではありません。動的入力形状を持つ一部のモデルは、自由次元オーバーライドと組み合わせてこの機能を使用できます。一部のモデルは、この機能では単純に動作しません。試してみて、モデルで動作するかどうかを確認できます。動作しない場合、モデルの初期化が失敗し、このモデルに対してこの機能を無効にできます。

詳細についてはAPI reference: enableGraphCaptureを参照してください。

`optimizedModelFilePath`

optimizedModelFilePathオプションは、最適化されたモデルのファイルパスを指定するために使用されます。ブラウザでは、このオプションの値は無視されます。代わりに、最適化されたモデルの内容をblobとして含む新しいタブが開かれ、ユーザーが最適化されたモデルをダウンロードして保存できるようになります。

const mySessionOptions = {
  ...,
  // 最適化されたモデルのダウンロードを許可するためにこのオプションを指定
  optimizedModelFilePath: 'optimized_model.onnx'
};

注意：この機能はデフォルトでは利用できません。--cmake_extra_defines onnxruntime_ENABLE_WEBASSEMBLY_OUTPUT_OPTIMIZED_MODEL=1コマンドラインオプションでONNX Runtime Webを再ビルドする必要があります。

詳細については、API reference: optimizedModelFilePathを参照してください。

`preferredOutputLocation`

preferredOutputLocationオプションは、出力データの優先場所を指定するために使用されます。さらなる処理のために出力データをGPU上に保持するために使用できます。詳細についてはKeep tensor data on GPU (IO binding)を参照してください。

詳細については、API reference: preferredOutputLocationを参照してください。

envフラグとセッションオプション

envフラグとセッションオプション

目次

環境フラグ（‘env’）

概要

env.debug

env.logLevel

env.wasm

env.wasm.numThreads

env.wasm.proxy

env.wasm.wasmPaths

env.webgpu

env.webgpu.deviceとenv.webgpu.adapter

env.webgpu.powerPreferenceとenv.webgpu.forceFallbackAdapter

env.webgpu.profiling

セッションオプション

概要

executionProviders

externalData

freeDimensionOverrides

enableGraphCapture

optimizedModelFilePath

preferredOutputLocation

`env.debug`

`env.logLevel`

`env.wasm`

`env.wasm.numThreads`

`env.wasm.proxy`

`env.wasm.wasmPaths`

`env.webgpu`

`env.webgpu.device`と`env.webgpu.adapter`

`env.webgpu.powerPreference`と`env.webgpu.forceFallbackAdapter`

`env.webgpu.profiling`

`executionProviders`

`externalData`

`freeDimensionOverrides`

`enableGraphCapture`

`optimizedModelFilePath`

`preferredOutputLocation`