diff --git a/app/style.css b/app/style.css index 5f0e996..19b0499 100644 --- a/app/style.css +++ b/app/style.css @@ -980,4 +980,13 @@ article.nextra-body-typesetting-article a:hover { .shell-font-small code { font-size: 0.75rem; +} + +.ort-ep pre { + text-wrap: pretty; + margin: 1rem; +} + +.ort-ep pre code.nextra-code { + font-size: .75rem !important; } \ No newline at end of file diff --git a/content/en/api-reference/browser-compatibility/chrome-flags.mdx b/content/en/api-reference/browser-compatibility/chrome-flags.mdx index 7e05265..f397ac0 100644 --- a/content/en/api-reference/browser-compatibility/chrome-flags.mdx +++ b/content/en/api-reference/browser-compatibility/chrome-flags.mdx @@ -21,6 +21,7 @@ Visit via `about://flags/` | Name | Windows ML / ONNX Runtime backend for WebNN | | :--: | :-------- | | Description | Enables using ONNX Runtime for CPU, GPU and NPU inference with the WebNN API. Disabling this flag enables a fallback to DirectML or TFLite. – Windows | +| Expiry Milestone | 146 | | Command Line Usage | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --enable-features=WebMachineLearningNeuralNetwork,WebNNOnnxRuntime` | @@ -37,7 +38,14 @@ Visit via `about://flags/` | Name | Core ML backend for WebNN | | :--: | :-------- | -| Description | Enables using Core ML for GPU and NPU inference with the WebNN API. Disabling this flag enables a fallback to TFLite. | +| Description | Enables using Core ML for GPU and NPU inference with the WebNN API | +| Expiry Milestone | 146 | + +### `#webnn-coreml-explicit-gpu-or-npu` + +| Name | Core ML backend (explicit GPU or NPU) for WebNN | +| :--: | :-------- | +| Description | Enables using Core ML for explicit GPU and NPU inference with the WebNN API | | Expiry Milestone | 146 | ### `#webnn-directml` @@ -49,32 +57,12 @@ Visit via `about://flags/` ## Switches (Command Line Flags) -### `--use-redist-ort` - -| Name | Use redistributable ONNX Runtime | -| :--: | :-------- | -| Description | Try to use a redistributable onnxruntime.dll. | - -### `--webnn-use-ort` - -| Name | WebNN Use ONNX Runtime | -| :--: | :-------- | -| Description | Introduces `webnn_use_ort` build flag and enable it for Windows. Replaces the DirectML backend with the ONNX Runtime backend. | - -### `--webnn-ort-use-openvino` - -| Name | WebNN ONNX Runtime Use OpenVINO | -| :--: | :-------- | -| Description | Enables the OpenVINO Execution Provider, OpenVINO EP will be -used for GPU and NPU devices. ONNX Runtime will run with the CPU EP by default. | -| Usage (No Sandbox) | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --no-sandbox --webnn-use-ort --webnn-ort-use-openvino --use-redist-ort` | -| Usage (Within Sandbox) | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --allow-third-party-modules --webnn-use-ort --webnn-ort-use-openvino` | - ### `--use-redist-dml` | Name | Use redistributable DirectML | | :--: | :-------- | -| Description | Try to use a redistributable DirectML.dll. Used for testing WebNN against newer DirectML release before it is integrated into Windows OS. Please see more info about DirectML releases at: https://learn.microsoft.com/en-us/windows/ai/directml/dml-version-history.| +| Description | Try to use a redistributable DirectML.dll. Used for testing WebNN against newer DirectML release before it is integrated into Windows OS. Please see more info about [DirectML releases](https://learn.microsoft.com/en-us/windows/ai/directml/dml-version-history).| +| Note | DirectML was officially deprecated during Microsoft Build 2025. WebNN will leverage Windows ML to access OpenVINO and other EPs to get hardware acceleration. | | Usage | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --use-redist-dml` | ### `--disable_dml_meta_commands_for_gpu` @@ -82,6 +70,7 @@ used for GPU and NPU devices. ONNX Runtime will run with the CPU EP by default. | Name | Disable DirectML Metacommands for GPU | | :--: | :-------- | | Description | Run with DirectML fallback shaders if disabling Metacommands | +| Note | DirectML was officially deprecated during Microsoft Build 2025. WebNN will leverage Windows ML to access OpenVINO and other EPs to get hardware acceleration.| | Usage (true) | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --disable_dml_meta_commands_for_gpu=1` | | Usage (false) | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --disable_dml_meta_commands_for_gpu=0` | @@ -89,14 +78,14 @@ used for GPU and NPU devices. ONNX Runtime will run with the CPU EP by default. | Name | Disable WebNN for GPU | | :--: | :-------- | -| Description | If `--disable_webnn_for_gpu` workaround is enabled for the GPU device, we need to check to see if there is a NPU device available before setting the WebNN gpu feature status. If there is a NPU device, check the `--disable_webnn_for_npu` workaround. | +| Description | If `--disable_webnn_for_gpu` workaround is enabled for the GPU device, we need to check to see if there is a NPU device available before setting the WebNN gpu feature status. | | Usage (true) | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --disable_webnn_for_gpu=1` | ### `--disable_webnn_for_npu` | Name | Disable WebNN for NPU | | :--: | :-------- | -| Description | | +| Description | If there is a NPU device, check the `--disable_webnn_for_npu` workaround | | Usage (true) | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --disable_webnn_for_npu=1` | | Usage (false) | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --disable_webnn_for_npu=0` | @@ -104,32 +93,88 @@ used for GPU and NPU devices. ONNX Runtime will run with the CPU EP by default. | Name | WebNN Core ML Dump Model | | :--: | :-------- | -| Description | Copy the generated Core ML model to the folder specified by `--webnn-coreml-dump-model`. | -| Note | The folder needs to be accessible from the GPU sandbox or use `--no-sandbox`. | +| Description | Copy the generated Core ML model | +| Note | The folder needs to be accessible from the GPU sandbox or use `--no-sandbox` | | Usage | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --no-sandbox --webnn-coreml-dump-model=/tmp/CoreMLModels` | ### `--webnn-tflite-dump-model` | Name | WebNN TFLite Dump Model | | :--: | :-------- | -| Description | Save the generated TFLite model file to the folder specified by `--webnn-tflite-dump-model`. | -| Note | The folder needs to be accessible from the GPU process sandbox or `--no-sandbox` must be used. | +| Description | Save the generated TFLite model file | +| Note | The folder needs to be accessible from the GPU process sandbox or `--no-sandbox` must be used | | Usage | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --no-sandbox --webnn-tflite-dump-model=/tmp/tflite_models` | +### `--webnn-ort-logging-level` + +| Name | WebNN ONNX Runtime Logging Level | +| :--: | :-------- | +| Description | Configure the logging severity level of ONNX Runtime | +| Note | "VERBOSE", other severity levels could be "INFO", "WARNING", "ERROR" (default), and "FATAL"| +| Usage | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --webnn-ort-logging-level=VERBOSE` | + +### `--webnn-ort-dump-model` + +| Name | WebNN Windows ML Dump Model | +| :--: | :-------- | +| Description | To save optimized ONNX model after graph level transformations | +| Usage | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --no-sandbox --webnn-ort-dump-model=/tmp/ort_models` | + +### `--webnn-ort-library-path-for-testing` + +| Name | WebNN ONNX Runtime Library Path For Testing | +| :--: | :-------- | +| Description | Force `onnxruntime.dll` to be loaded from a location specified by the switch for testing development ORT build. | +| Note |This switch is not to be used in shipping scenarios and is ignored by default| +| Usage | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --webnn-ort-library-path-for-testing="C:\Program Files\ONNXRuntime" --allow-third-party-modules` | + +### `--webnn-ort-ep-library-path-for-testing` + +| Name | WebNN ONNX Runtime Execution Provider Library Path For Testing | +| :--: | :-------- | +| Description | Specify the ORT EP name and library path pair via this switch for testing development EP builds. Libraries of the ORT EP specified by the EP name are forced to be loaded from the specified path. The value should be in the format `?`. | +| Note |This switch is not to be used in shipping scenarios and is ignored by default | +| Usage | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --webnn-ort-ep-library-path-for-testing=OpenVINOExecutionProvider?"C:\Program Files\ONNXRuntime-EP\onnxruntime_providers_openvino_plugin.dll" --allow-third-party-modules` | + +### `--webnn-ort-graph-optimization-level` + +| Name | WebNN ONNX Runtime Graph Optimization Level | +| :--: | :-------- | +| Description | Configure the graph optimization level of ONNX Runtime | +| Note | Levels could be "DISABLE_ALL", "BASIC", "EXTENDED" and "ALL" | +| Usage | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --webnn-ort-graph-optimization-level=DISABLE_ALL` | + +### `--webnn-ort-enable-profiling` + +| Name | WebNN ONNX Runtime Enable Profiling | +| :--: | :-------- | +| Description | Collect ORT profile data for performance analysis. The profile data file is generated in Chrome's folder with a fixed naming format `prefix_date_time.json`.| +| Note | The prefix can be provided by user or use `WebNNOrtProfile` as default | +| Usage | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --no-sandbox --webnn-ort-enable-profiling="WebNNOrtOvCpuProfile"` | + ## Other Switches +### `--disable-gpu-sandbox` + +| Name | Disable GPU Sandbox | +| :--: | :-------- | +| Description | Often used to fix crashes related to the GPU process. Should only be used when necessary for development or troubleshooting, as it makes the application vulnerable to exploits. | +| Note | This is an insecure configuration. After performing the test, you should quit Chrome and re-launch normally. | +| Usage | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --disable-gpu-sandbox` | + ### `--no-sandbox` | Name | No Sandbox | | :--: | :-------- | -| Description | The `--no-sandbox` flag disables Chromium's security sandbox, which isolates browser processes to prevent malicious code execution. While sometimes used in development/testing environments, using this flag in regular browsing is dangerous as it removes essential security protections. | -| Note | Running with `--no-sandbox` is an insecure configuration. After performing the test, you should quit Chrome and re-launch normally. | +| Description | Disables Chromium's security sandbox, which isolates browser processes to prevent malicious code execution. While sometimes used in development/testing environments, using this flag in regular browsing is dangerous as it removes essential security protections. | +| Note | This is an insecure configuration. After performing the test, you should quit Chrome and re-launch normally. | | Usage | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --no-sandbox` | + ### `--allow-third-party-modules` | Name | Allow Third-party Modules | | :--: | :-------- | -| Description | The `--allow-third-party-modules` flag permits third-party software to inject DLLs or modules into Chrome's processes. | +| Description | Permits third-party software to inject DLLs or modules into Chrome's processes | | Note | While useful for legitimate software like antivirus or accessibility tools, it can pose security risks by allowing potentially malicious code injection. | | Usage | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --allow-third-party-modules` | diff --git a/content/en/learn/get-started/_meta.js b/content/en/learn/get-started/_meta.js index e0ebe7a..a753b0b 100644 --- a/content/en/learn/get-started/_meta.js +++ b/content/en/learn/get-started/_meta.js @@ -11,4 +11,7 @@ export default { 'testing': { title: "🧪 Testing" }, + 'debug': { + title: "🧪 Debug" + }, }; \ No newline at end of file diff --git a/content/en/learn/get-started/debug.mdx b/content/en/learn/get-started/debug.mdx new file mode 100644 index 0000000..874f12e --- /dev/null +++ b/content/en/learn/get-started/debug.mdx @@ -0,0 +1,148 @@ +import { Steps } from 'nextra/components' +import InfoIcon from '../../../../app/_components/icons/info.jsx' +import AppleIcon from '../../../../app/_components/icons/ihv/apple.jsx' +import AMDIcon from '../../../../app/_components/icons/ihv/amd.jsx' +import IntelIcon from '../../../../app/_components/icons/ihv/intel.jsx' +import QualcommIcon from '../../../../app/_components/icons/ihv/qualcomm.jsx' +import NvidiaIcon from '../../../../app/_components/icons/ihv/nvidia.jsx' + +# Debugging + +## Use Custom Build of ONNX Runtime + +1. Follow the [WebNN Installation Guide](installation) to enable WebNN API and switch to Windows ML / ONNX Runtime backend +2. Put the ONNX Runtime dynamic link librares into a folder under `C:\Program Files\`, e.g. `C:\Program Files\ONNXRuntime` +3. Launch your Chrome or Edge browser with switch [--webnn-ort-library-path-for-testing](../../api-reference/browser-compatibility/chrome-flags#--webnn-ort-library-path-for-testing) + +
+```shell +"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --webnn-ort-library-path-for-testing="C:\Program Files\ONNXRuntime" --allow-third-party-modules +``` +
+ +
+```shell +"%LOCALAPPDATA%\Microsoft\Edge SxS\Application\msedge.exe" --webnn-ort-library-path-for-testing="C:\Program Files\ONNXRuntime" --allow-third-party-modules +``` +
+ +## Use Custom Build of Execution Providers + +If you are running WebNN on AMD, Intel, Nvidia, or Qualcomm devices and need to debug WebNN using specific Execution Provider of ONNX Runtime: + +1. Follow the [WebNN Installation Guide](installation) to enable WebNN API and switch to Windows ML / ONNX Runtime backend +2. Put the ONNX Runtime and Execution Provider dynamic link librares into a folder under `C:\Program Files\`, e.g. `C:\Program Files\ONNXRuntime-EP` +3. Launch your Chrome or Edge browser with switch [--webnn-ort-ep-library-path-for-testing](../../api-reference/browser-compatibility/chrome-flags#--webnn-ort-ep-library-path-for-testing) + +### Execution Provider Mapping Table for Independent Hardware Vendors + +
+| IHVs | Execution Provider | DLL | +| --- | --- | -- | +| | OpenVINOExecutionProvider | onnxruntime_providers_openvino_plugin.dll | +| | TBD | TBD | +| | NvTensorRTRTXExecutionProvider | onnxruntime_providers_nv_tensorrt_rtx.dll | +| | QNNExecutionProvider | onnxruntime_providers_qnn.dll | +
+ +### Intel OpenVINO Execution Provider + +The following examples show how to specify the locations of `ONNX Runtime` and `Intel OpenVINO Execution Provider` libraries: + +
+```shell +"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --webnn-ort-ep-library-path-for-testing=OpenVINOExecutionProvider?"C:\Program Files\ONNXRuntime-EP\onnxruntime_providers_openvino_plugin.dll" +``` +
+ +
+```shell +"%LOCALAPPDATA%\Microsoft\Edge SxS\Application\msedge.exe" --webnn-ort-ep-library-path-for-testing=OpenVINOExecutionProvider?"C:\Program Files\ONNXRuntime-EP\onnxruntime_providers_openvino_plugin.dll" +``` +
+ +### Other IHVs + +#### AMD (TBD) + +TBD + +#### Nvidia Nv Tensor RT RTX Execution Provider + +
+```shell +"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --webnn-ort-ep-library-path-for-testing=NvTensorRTRTXExecutionProvider?"C:\Program Files\ONNXRuntime-EP\onnxruntime_providers_nv_tensorrt_rtx.dll" +``` +
+ +
+```shell +"%LOCALAPPDATA%\Microsoft\Edge SxS\Application\msedge.exe" --webnn-ort-ep-library-path-for-testing=NvTensorRTRTXExecutionProvider?"C:\Program Files\ONNXRuntime-EP\onnxruntime_providers_nv_tensorrt_rtx.dll" +``` +
+ +#### Qualcomm QNN Execution Provider + +
+```shell +"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --webnn-ort-ep-library-path-for-testing=QNNExecutionProvider?"C:\Program Files\ONNXRuntime-EP\onnxruntime_providers_qnn.dll" +``` +
+ +
+```shell +"%LOCALAPPDATA%\Microsoft\Edge SxS\Application\msedge.exe" --webnn-ort-ep-library-path-for-testing=QNNExecutionProvider?"C:\Program Files\ONNXRuntime-EP\onnxruntime_providers_qnn.dll" +``` +
+ +## Use Custom Build of GPU or NPU Drivers + +If you are testing with custom or internal GPU or NPU drivers, add the [--allow-third-party-modules](../../api-reference/browser-compatibility/chrome-flags#--allow-third-party-modules) switch when launching the browser. + +
+```shell +"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --allow-third-party-modules +``` +
+ +
+```shell +"%LOCALAPPDATA%\Microsoft\Edge SxS\Application\msedge.exe" --allow-third-party-modules +``` +
+ +## Debug Sandbox Issues + +In some cases, you may need to debug WebNN by disabling Chromium's security sandbox using the [--disable-gpu-sandbox](../../api-reference/browser-compatibility/chrome-flags#--disable-gpu-sandbox) switch. + +
+```shell +"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --disable-gpu-sandbox +``` +
+ +
+```shell +"%LOCALAPPDATA%\Microsoft\Edge SxS\Application\msedge.exe" --disable-gpu-sandbox +``` +
+ +## Inspect the Verbose Logging + +You can configure the logging severity level of ONNX Runtime using the switch [--webnn-ort-logging-level](../../api-reference/browser-compatibility/chrome-flags#--webnn-ort-logging-level). Other available severity levels include "INFO", "WARNING", "ERROR" (default), and "FATAL". + +
+```shell +"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --webnn-ort-logging-level=VERBOSE +``` +
+ +
+```shell +"%LOCALAPPDATA%\Microsoft\Edge SxS\Application\msedge.exe" --webnn-ort-logging-level=VERBOSE +``` +
+ +## Additional Resources + +- [WebNN Flags and Switches in Chromium](../../api-reference/browser-compatibility/chrome-flags) \ No newline at end of file diff --git a/content/en/learn/get-started/installation.mdx b/content/en/learn/get-started/installation.mdx index 2e9ba0e..e1951c5 100644 --- a/content/en/learn/get-started/installation.mdx +++ b/content/en/learn/get-started/installation.mdx @@ -52,7 +52,7 @@ import NvidiaIcon from '../../../../app/_components/icons/ihv/nvidia.jsx' ```shell C:\Users\webnn\Downloads>ExecutionProviderCatalog.exe ``` -It will display the following similar logs: +The Execution Providers (EPs) to be installed depend on your computer’s hardware configuration. It will display the following similar logs:
```shell @@ -72,15 +72,7 @@ Provider 1: ```
-> The installation time may vary depending on your network speed. The Execution Providers (EPs) to be installed depend on your computer's hardware configuration. - - -
-| IHVs | Execution Provider | IHVs | Execution Provider | -| --- | --- | --- | --- | -| | Intel OpenVINO EP | | TBD | -| | TBD | | TBD | -
+> The installation time may vary depending on your network speed ### Navigate to `about://flags` in browser address bar ### Search for `ONNX Runtime backend for WebNN` and change it to `Enabled` diff --git a/content/zh/api-reference/browser-compatibility/chrome-flags.mdx b/content/zh/api-reference/browser-compatibility/chrome-flags.mdx index 7e05265..f397ac0 100644 --- a/content/zh/api-reference/browser-compatibility/chrome-flags.mdx +++ b/content/zh/api-reference/browser-compatibility/chrome-flags.mdx @@ -21,6 +21,7 @@ Visit via `about://flags/` | Name | Windows ML / ONNX Runtime backend for WebNN | | :--: | :-------- | | Description | Enables using ONNX Runtime for CPU, GPU and NPU inference with the WebNN API. Disabling this flag enables a fallback to DirectML or TFLite. – Windows | +| Expiry Milestone | 146 | | Command Line Usage | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --enable-features=WebMachineLearningNeuralNetwork,WebNNOnnxRuntime` | @@ -37,7 +38,14 @@ Visit via `about://flags/` | Name | Core ML backend for WebNN | | :--: | :-------- | -| Description | Enables using Core ML for GPU and NPU inference with the WebNN API. Disabling this flag enables a fallback to TFLite. | +| Description | Enables using Core ML for GPU and NPU inference with the WebNN API | +| Expiry Milestone | 146 | + +### `#webnn-coreml-explicit-gpu-or-npu` + +| Name | Core ML backend (explicit GPU or NPU) for WebNN | +| :--: | :-------- | +| Description | Enables using Core ML for explicit GPU and NPU inference with the WebNN API | | Expiry Milestone | 146 | ### `#webnn-directml` @@ -49,32 +57,12 @@ Visit via `about://flags/` ## Switches (Command Line Flags) -### `--use-redist-ort` - -| Name | Use redistributable ONNX Runtime | -| :--: | :-------- | -| Description | Try to use a redistributable onnxruntime.dll. | - -### `--webnn-use-ort` - -| Name | WebNN Use ONNX Runtime | -| :--: | :-------- | -| Description | Introduces `webnn_use_ort` build flag and enable it for Windows. Replaces the DirectML backend with the ONNX Runtime backend. | - -### `--webnn-ort-use-openvino` - -| Name | WebNN ONNX Runtime Use OpenVINO | -| :--: | :-------- | -| Description | Enables the OpenVINO Execution Provider, OpenVINO EP will be -used for GPU and NPU devices. ONNX Runtime will run with the CPU EP by default. | -| Usage (No Sandbox) | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --no-sandbox --webnn-use-ort --webnn-ort-use-openvino --use-redist-ort` | -| Usage (Within Sandbox) | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --allow-third-party-modules --webnn-use-ort --webnn-ort-use-openvino` | - ### `--use-redist-dml` | Name | Use redistributable DirectML | | :--: | :-------- | -| Description | Try to use a redistributable DirectML.dll. Used for testing WebNN against newer DirectML release before it is integrated into Windows OS. Please see more info about DirectML releases at: https://learn.microsoft.com/en-us/windows/ai/directml/dml-version-history.| +| Description | Try to use a redistributable DirectML.dll. Used for testing WebNN against newer DirectML release before it is integrated into Windows OS. Please see more info about [DirectML releases](https://learn.microsoft.com/en-us/windows/ai/directml/dml-version-history).| +| Note | DirectML was officially deprecated during Microsoft Build 2025. WebNN will leverage Windows ML to access OpenVINO and other EPs to get hardware acceleration. | | Usage | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --use-redist-dml` | ### `--disable_dml_meta_commands_for_gpu` @@ -82,6 +70,7 @@ used for GPU and NPU devices. ONNX Runtime will run with the CPU EP by default. | Name | Disable DirectML Metacommands for GPU | | :--: | :-------- | | Description | Run with DirectML fallback shaders if disabling Metacommands | +| Note | DirectML was officially deprecated during Microsoft Build 2025. WebNN will leverage Windows ML to access OpenVINO and other EPs to get hardware acceleration.| | Usage (true) | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --disable_dml_meta_commands_for_gpu=1` | | Usage (false) | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --disable_dml_meta_commands_for_gpu=0` | @@ -89,14 +78,14 @@ used for GPU and NPU devices. ONNX Runtime will run with the CPU EP by default. | Name | Disable WebNN for GPU | | :--: | :-------- | -| Description | If `--disable_webnn_for_gpu` workaround is enabled for the GPU device, we need to check to see if there is a NPU device available before setting the WebNN gpu feature status. If there is a NPU device, check the `--disable_webnn_for_npu` workaround. | +| Description | If `--disable_webnn_for_gpu` workaround is enabled for the GPU device, we need to check to see if there is a NPU device available before setting the WebNN gpu feature status. | | Usage (true) | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --disable_webnn_for_gpu=1` | ### `--disable_webnn_for_npu` | Name | Disable WebNN for NPU | | :--: | :-------- | -| Description | | +| Description | If there is a NPU device, check the `--disable_webnn_for_npu` workaround | | Usage (true) | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --disable_webnn_for_npu=1` | | Usage (false) | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --disable_webnn_for_npu=0` | @@ -104,32 +93,88 @@ used for GPU and NPU devices. ONNX Runtime will run with the CPU EP by default. | Name | WebNN Core ML Dump Model | | :--: | :-------- | -| Description | Copy the generated Core ML model to the folder specified by `--webnn-coreml-dump-model`. | -| Note | The folder needs to be accessible from the GPU sandbox or use `--no-sandbox`. | +| Description | Copy the generated Core ML model | +| Note | The folder needs to be accessible from the GPU sandbox or use `--no-sandbox` | | Usage | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --no-sandbox --webnn-coreml-dump-model=/tmp/CoreMLModels` | ### `--webnn-tflite-dump-model` | Name | WebNN TFLite Dump Model | | :--: | :-------- | -| Description | Save the generated TFLite model file to the folder specified by `--webnn-tflite-dump-model`. | -| Note | The folder needs to be accessible from the GPU process sandbox or `--no-sandbox` must be used. | +| Description | Save the generated TFLite model file | +| Note | The folder needs to be accessible from the GPU process sandbox or `--no-sandbox` must be used | | Usage | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --no-sandbox --webnn-tflite-dump-model=/tmp/tflite_models` | +### `--webnn-ort-logging-level` + +| Name | WebNN ONNX Runtime Logging Level | +| :--: | :-------- | +| Description | Configure the logging severity level of ONNX Runtime | +| Note | "VERBOSE", other severity levels could be "INFO", "WARNING", "ERROR" (default), and "FATAL"| +| Usage | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --webnn-ort-logging-level=VERBOSE` | + +### `--webnn-ort-dump-model` + +| Name | WebNN Windows ML Dump Model | +| :--: | :-------- | +| Description | To save optimized ONNX model after graph level transformations | +| Usage | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --no-sandbox --webnn-ort-dump-model=/tmp/ort_models` | + +### `--webnn-ort-library-path-for-testing` + +| Name | WebNN ONNX Runtime Library Path For Testing | +| :--: | :-------- | +| Description | Force `onnxruntime.dll` to be loaded from a location specified by the switch for testing development ORT build. | +| Note |This switch is not to be used in shipping scenarios and is ignored by default| +| Usage | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --webnn-ort-library-path-for-testing="C:\Program Files\ONNXRuntime" --allow-third-party-modules` | + +### `--webnn-ort-ep-library-path-for-testing` + +| Name | WebNN ONNX Runtime Execution Provider Library Path For Testing | +| :--: | :-------- | +| Description | Specify the ORT EP name and library path pair via this switch for testing development EP builds. Libraries of the ORT EP specified by the EP name are forced to be loaded from the specified path. The value should be in the format `?`. | +| Note |This switch is not to be used in shipping scenarios and is ignored by default | +| Usage | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --webnn-ort-ep-library-path-for-testing=OpenVINOExecutionProvider?"C:\Program Files\ONNXRuntime-EP\onnxruntime_providers_openvino_plugin.dll" --allow-third-party-modules` | + +### `--webnn-ort-graph-optimization-level` + +| Name | WebNN ONNX Runtime Graph Optimization Level | +| :--: | :-------- | +| Description | Configure the graph optimization level of ONNX Runtime | +| Note | Levels could be "DISABLE_ALL", "BASIC", "EXTENDED" and "ALL" | +| Usage | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --webnn-ort-graph-optimization-level=DISABLE_ALL` | + +### `--webnn-ort-enable-profiling` + +| Name | WebNN ONNX Runtime Enable Profiling | +| :--: | :-------- | +| Description | Collect ORT profile data for performance analysis. The profile data file is generated in Chrome's folder with a fixed naming format `prefix_date_time.json`.| +| Note | The prefix can be provided by user or use `WebNNOrtProfile` as default | +| Usage | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --no-sandbox --webnn-ort-enable-profiling="WebNNOrtOvCpuProfile"` | + ## Other Switches +### `--disable-gpu-sandbox` + +| Name | Disable GPU Sandbox | +| :--: | :-------- | +| Description | Often used to fix crashes related to the GPU process. Should only be used when necessary for development or troubleshooting, as it makes the application vulnerable to exploits. | +| Note | This is an insecure configuration. After performing the test, you should quit Chrome and re-launch normally. | +| Usage | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --disable-gpu-sandbox` | + ### `--no-sandbox` | Name | No Sandbox | | :--: | :-------- | -| Description | The `--no-sandbox` flag disables Chromium's security sandbox, which isolates browser processes to prevent malicious code execution. While sometimes used in development/testing environments, using this flag in regular browsing is dangerous as it removes essential security protections. | -| Note | Running with `--no-sandbox` is an insecure configuration. After performing the test, you should quit Chrome and re-launch normally. | +| Description | Disables Chromium's security sandbox, which isolates browser processes to prevent malicious code execution. While sometimes used in development/testing environments, using this flag in regular browsing is dangerous as it removes essential security protections. | +| Note | This is an insecure configuration. After performing the test, you should quit Chrome and re-launch normally. | | Usage | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --no-sandbox` | + ### `--allow-third-party-modules` | Name | Allow Third-party Modules | | :--: | :-------- | -| Description | The `--allow-third-party-modules` flag permits third-party software to inject DLLs or modules into Chrome's processes. | +| Description | Permits third-party software to inject DLLs or modules into Chrome's processes | | Note | While useful for legitimate software like antivirus or accessibility tools, it can pose security risks by allowing potentially malicious code injection. | | Usage | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --allow-third-party-modules` | diff --git a/content/zh/learn/get-started/_meta.js b/content/zh/learn/get-started/_meta.js index e0ebe7a..a753b0b 100644 --- a/content/zh/learn/get-started/_meta.js +++ b/content/zh/learn/get-started/_meta.js @@ -11,4 +11,7 @@ export default { 'testing': { title: "🧪 Testing" }, + 'debug': { + title: "🧪 Debug" + }, }; \ No newline at end of file diff --git a/content/zh/learn/get-started/debug.mdx b/content/zh/learn/get-started/debug.mdx new file mode 100644 index 0000000..874f12e --- /dev/null +++ b/content/zh/learn/get-started/debug.mdx @@ -0,0 +1,148 @@ +import { Steps } from 'nextra/components' +import InfoIcon from '../../../../app/_components/icons/info.jsx' +import AppleIcon from '../../../../app/_components/icons/ihv/apple.jsx' +import AMDIcon from '../../../../app/_components/icons/ihv/amd.jsx' +import IntelIcon from '../../../../app/_components/icons/ihv/intel.jsx' +import QualcommIcon from '../../../../app/_components/icons/ihv/qualcomm.jsx' +import NvidiaIcon from '../../../../app/_components/icons/ihv/nvidia.jsx' + +# Debugging + +## Use Custom Build of ONNX Runtime + +1. Follow the [WebNN Installation Guide](installation) to enable WebNN API and switch to Windows ML / ONNX Runtime backend +2. Put the ONNX Runtime dynamic link librares into a folder under `C:\Program Files\`, e.g. `C:\Program Files\ONNXRuntime` +3. Launch your Chrome or Edge browser with switch [--webnn-ort-library-path-for-testing](../../api-reference/browser-compatibility/chrome-flags#--webnn-ort-library-path-for-testing) + +
+```shell +"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --webnn-ort-library-path-for-testing="C:\Program Files\ONNXRuntime" --allow-third-party-modules +``` +
+ +
+```shell +"%LOCALAPPDATA%\Microsoft\Edge SxS\Application\msedge.exe" --webnn-ort-library-path-for-testing="C:\Program Files\ONNXRuntime" --allow-third-party-modules +``` +
+ +## Use Custom Build of Execution Providers + +If you are running WebNN on AMD, Intel, Nvidia, or Qualcomm devices and need to debug WebNN using specific Execution Provider of ONNX Runtime: + +1. Follow the [WebNN Installation Guide](installation) to enable WebNN API and switch to Windows ML / ONNX Runtime backend +2. Put the ONNX Runtime and Execution Provider dynamic link librares into a folder under `C:\Program Files\`, e.g. `C:\Program Files\ONNXRuntime-EP` +3. Launch your Chrome or Edge browser with switch [--webnn-ort-ep-library-path-for-testing](../../api-reference/browser-compatibility/chrome-flags#--webnn-ort-ep-library-path-for-testing) + +### Execution Provider Mapping Table for Independent Hardware Vendors + +
+| IHVs | Execution Provider | DLL | +| --- | --- | -- | +| | OpenVINOExecutionProvider | onnxruntime_providers_openvino_plugin.dll | +| | TBD | TBD | +| | NvTensorRTRTXExecutionProvider | onnxruntime_providers_nv_tensorrt_rtx.dll | +| | QNNExecutionProvider | onnxruntime_providers_qnn.dll | +
+ +### Intel OpenVINO Execution Provider + +The following examples show how to specify the locations of `ONNX Runtime` and `Intel OpenVINO Execution Provider` libraries: + +
+```shell +"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --webnn-ort-ep-library-path-for-testing=OpenVINOExecutionProvider?"C:\Program Files\ONNXRuntime-EP\onnxruntime_providers_openvino_plugin.dll" +``` +
+ +
+```shell +"%LOCALAPPDATA%\Microsoft\Edge SxS\Application\msedge.exe" --webnn-ort-ep-library-path-for-testing=OpenVINOExecutionProvider?"C:\Program Files\ONNXRuntime-EP\onnxruntime_providers_openvino_plugin.dll" +``` +
+ +### Other IHVs + +#### AMD (TBD) + +TBD + +#### Nvidia Nv Tensor RT RTX Execution Provider + +
+```shell +"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --webnn-ort-ep-library-path-for-testing=NvTensorRTRTXExecutionProvider?"C:\Program Files\ONNXRuntime-EP\onnxruntime_providers_nv_tensorrt_rtx.dll" +``` +
+ +
+```shell +"%LOCALAPPDATA%\Microsoft\Edge SxS\Application\msedge.exe" --webnn-ort-ep-library-path-for-testing=NvTensorRTRTXExecutionProvider?"C:\Program Files\ONNXRuntime-EP\onnxruntime_providers_nv_tensorrt_rtx.dll" +``` +
+ +#### Qualcomm QNN Execution Provider + +
+```shell +"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --webnn-ort-ep-library-path-for-testing=QNNExecutionProvider?"C:\Program Files\ONNXRuntime-EP\onnxruntime_providers_qnn.dll" +``` +
+ +
+```shell +"%LOCALAPPDATA%\Microsoft\Edge SxS\Application\msedge.exe" --webnn-ort-ep-library-path-for-testing=QNNExecutionProvider?"C:\Program Files\ONNXRuntime-EP\onnxruntime_providers_qnn.dll" +``` +
+ +## Use Custom Build of GPU or NPU Drivers + +If you are testing with custom or internal GPU or NPU drivers, add the [--allow-third-party-modules](../../api-reference/browser-compatibility/chrome-flags#--allow-third-party-modules) switch when launching the browser. + +
+```shell +"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --allow-third-party-modules +``` +
+ +
+```shell +"%LOCALAPPDATA%\Microsoft\Edge SxS\Application\msedge.exe" --allow-third-party-modules +``` +
+ +## Debug Sandbox Issues + +In some cases, you may need to debug WebNN by disabling Chromium's security sandbox using the [--disable-gpu-sandbox](../../api-reference/browser-compatibility/chrome-flags#--disable-gpu-sandbox) switch. + +
+```shell +"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --disable-gpu-sandbox +``` +
+ +
+```shell +"%LOCALAPPDATA%\Microsoft\Edge SxS\Application\msedge.exe" --disable-gpu-sandbox +``` +
+ +## Inspect the Verbose Logging + +You can configure the logging severity level of ONNX Runtime using the switch [--webnn-ort-logging-level](../../api-reference/browser-compatibility/chrome-flags#--webnn-ort-logging-level). Other available severity levels include "INFO", "WARNING", "ERROR" (default), and "FATAL". + +
+```shell +"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --webnn-ort-logging-level=VERBOSE +``` +
+ +
+```shell +"%LOCALAPPDATA%\Microsoft\Edge SxS\Application\msedge.exe" --webnn-ort-logging-level=VERBOSE +``` +
+ +## Additional Resources + +- [WebNN Flags and Switches in Chromium](../../api-reference/browser-compatibility/chrome-flags) \ No newline at end of file diff --git a/content/zh/learn/get-started/installation.mdx b/content/zh/learn/get-started/installation.mdx index 5d3a815..e1951c5 100644 --- a/content/zh/learn/get-started/installation.mdx +++ b/content/zh/learn/get-started/installation.mdx @@ -47,12 +47,12 @@ import NvidiaIcon from '../../../../app/_components/icons/ihv/nvidia.jsx' 1. Visit [WebNN Execution Provider Catalog](https://github.com/ibelem/webnn-execution-provider-catalog/releases/tag/1.8_8wekyb3d8bbwe) 2. Download the [ExecutionProviderCatalog.exe](https://github.com/ibelem/webnn-execution-provider-catalog/releases/download/1.8_8wekyb3d8bbwe/ExecutionProviderCatalog.exe) -3. Run the executable file to install Execution Providers +3. Run the executable file to install Execution Providers ```shell C:\Users\webnn\Downloads>ExecutionProviderCatalog.exe ``` -It will display the following similar logs: +The Execution Providers (EPs) to be installed depend on your computer’s hardware configuration. It will display the following similar logs:
```shell @@ -72,15 +72,7 @@ Provider 1: ```
-> The installation time may vary depending on your network speed. The Execution Providers (EPs) to be installed depend on your computer's hardware configuration. - - -
-| IHVs | Execution Provider | IHVs | Execution Provider | -| --- | --- | --- | --- | -| | Intel OpenVINO EP | | TBD | -| | TBD | | TBD | -
+> The installation time may vary depending on your network speed ### Navigate to `about://flags` in browser address bar ### Search for `ONNX Runtime backend for WebNN` and change it to `Enabled`