Skip to content

Commit e76dc97

Browse files
ibelemibelem
authored
Merge pull request #30 from ibelem/installation-ihv-flags
Add debug page
2 parents c6572ab + 0bb69a2 commit e76dc97

File tree

9 files changed

+470
-85
lines changed

9 files changed

+470
-85
lines changed

‎app/style.css‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -980,4 +980,13 @@ article.nextra-body-typesetting-article a:hover {
980980

981981
.shell-font-small code {
982982
font-size: 0.75rem;
983+
}
984+
985+
.ort-ep pre {
986+
text-wrap: pretty;
987+
margin: 1rem;
988+
}
989+
990+
.ort-ep pre code.nextra-code {
991+
font-size: .75rem !important;
983992
}

‎content/en/api-reference/browser-compatibility/chrome-flags.mdx‎

Lines changed: 77 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ Visit via `about://flags/`
2121
| Name | Windows ML / ONNX Runtime backend for WebNN |
2222
| :--: | :-------- |
2323
| 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 |
24+
| Expiry Milestone | 146 |
2425
| Command Line Usage | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --enable-features=WebMachineLearningNeuralNetwork,WebNNOnnxRuntime` |
2526

2627

@@ -37,7 +38,14 @@ Visit via `about://flags/`
3738

3839
| Name | Core ML backend for WebNN |
3940
| :--: | :-------- |
40-
| Description | Enables using Core ML for GPU and NPU inference with the WebNN API. Disabling this flag enables a fallback to TFLite. |
41+
| Description | Enables using Core ML for GPU and NPU inference with the WebNN API |
42+
| Expiry Milestone | 146 |
43+
44+
### `#webnn-coreml-explicit-gpu-or-npu`
45+
46+
| Name | Core ML backend (explicit GPU or NPU) for WebNN |
47+
| :--: | :-------- |
48+
| Description | Enables using Core ML for explicit GPU and NPU inference with the WebNN API |
4149
| Expiry Milestone | 146 |
4250

4351
### `#webnn-directml`
@@ -49,87 +57,124 @@ Visit via `about://flags/`
4957

5058
## Switches (Command Line Flags)
5159

52-
### `--use-redist-ort`
53-
54-
| Name | Use redistributable ONNX Runtime |
55-
| :--: | :-------- |
56-
| Description | Try to use a redistributable onnxruntime.dll. |
57-
58-
### `--webnn-use-ort`
59-
60-
| Name | WebNN Use ONNX Runtime |
61-
| :--: | :-------- |
62-
| Description | Introduces `webnn_use_ort` build flag and enable it for Windows. Replaces the DirectML backend with the ONNX Runtime backend. |
63-
64-
### `--webnn-ort-use-openvino`
65-
66-
| Name | WebNN ONNX Runtime Use OpenVINO |
67-
| :--: | :-------- |
68-
| Description | Enables the OpenVINO Execution Provider, OpenVINO EP will be
69-
used for GPU and NPU devices. ONNX Runtime will run with the CPU EP by default. |
70-
| Usage (No Sandbox) | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --no-sandbox --webnn-use-ort --webnn-ort-use-openvino --use-redist-ort` |
71-
| Usage (Within Sandbox) | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --allow-third-party-modules --webnn-use-ort --webnn-ort-use-openvino` |
72-
7360
### `--use-redist-dml`
7461

7562
| Name | Use redistributable DirectML |
7663
| :--: | :-------- |
77-
| 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.|
64+
| 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).|
65+
| Note | DirectML was officially deprecated during Microsoft Build 2025. WebNN will leverage Windows ML to access OpenVINO and other EPs to get hardware acceleration. |
7866
| Usage | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --use-redist-dml` |
7967

8068
### `--disable_dml_meta_commands_for_gpu`
8169

8270
| Name | Disable DirectML Metacommands for GPU |
8371
| :--: | :-------- |
8472
| Description | Run with DirectML fallback shaders if disabling Metacommands |
73+
| Note | DirectML was officially deprecated during Microsoft Build 2025. WebNN will leverage Windows ML to access OpenVINO and other EPs to get hardware acceleration.|
8574
| Usage (true) | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --disable_dml_meta_commands_for_gpu=1` |
8675
| Usage (false) | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --disable_dml_meta_commands_for_gpu=0` |
8776

8877
### `--disable_webnn_for_gpu`
8978

9079
| Name | Disable WebNN for GPU |
9180
| :--: | :-------- |
92-
| 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. |
81+
| 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. |
9382
| Usage (true) | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --disable_webnn_for_gpu=1` |
9483

9584
### `--disable_webnn_for_npu`
9685

9786
| Name | Disable WebNN for NPU |
9887
| :--: | :-------- |
99-
| Description | |
88+
| Description | If there is a NPU device, check the `--disable_webnn_for_npu` workaround |
10089
| Usage (true) | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --disable_webnn_for_npu=1` |
10190
| Usage (false) | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --disable_webnn_for_npu=0` |
10291

10392
### `--webnn-coreml-dump-model`
10493

10594
| Name | WebNN Core ML Dump Model |
10695
| :--: | :-------- |
107-
| Description | Copy the generated Core ML model to the folder specified by `--webnn-coreml-dump-model`. |
108-
| Note | The folder needs to be accessible from the GPU sandbox or use `--no-sandbox`. |
96+
| Description | Copy the generated Core ML model |
97+
| Note | The folder needs to be accessible from the GPU sandbox or use `--no-sandbox` |
10998
| Usage | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --no-sandbox --webnn-coreml-dump-model=/tmp/CoreMLModels` |
11099

111100
### `--webnn-tflite-dump-model`
112101

113102
| Name | WebNN TFLite Dump Model |
114103
| :--: | :-------- |
115-
| Description | Save the generated TFLite model file to the folder specified by `--webnn-tflite-dump-model`. |
116-
| Note | The folder needs to be accessible from the GPU process sandbox or `--no-sandbox` must be used. |
104+
| Description | Save the generated TFLite model file |
105+
| Note | The folder needs to be accessible from the GPU process sandbox or `--no-sandbox` must be used |
117106
| Usage | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --no-sandbox --webnn-tflite-dump-model=/tmp/tflite_models` |
118107

108+
### `--webnn-ort-logging-level`
109+
110+
| Name | WebNN ONNX Runtime Logging Level |
111+
| :--: | :-------- |
112+
| Description | Configure the logging severity level of ONNX Runtime |
113+
| Note | "VERBOSE", other severity levels could be "INFO", "WARNING", "ERROR" (default), and "FATAL"|
114+
| Usage | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --webnn-ort-logging-level=VERBOSE` |
115+
116+
### `--webnn-ort-dump-model`
117+
118+
| Name | WebNN Windows ML Dump Model |
119+
| :--: | :-------- |
120+
| Description | To save optimized ONNX model after graph level transformations |
121+
| Usage | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --no-sandbox --webnn-ort-dump-model=/tmp/ort_models` |
122+
123+
### `--webnn-ort-library-path-for-testing`
124+
125+
| Name | WebNN ONNX Runtime Library Path For Testing |
126+
| :--: | :-------- |
127+
| Description | Force `onnxruntime.dll` to be loaded from a location specified by the switch for testing development ORT build. |
128+
| Note |This switch is not to be used in shipping scenarios and is ignored by default|
129+
| Usage | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --webnn-ort-library-path-for-testing="C:\Program Files\ONNXRuntime" --allow-third-party-modules` |
130+
131+
### `--webnn-ort-ep-library-path-for-testing`
132+
133+
| Name | WebNN ONNX Runtime Execution Provider Library Path For Testing |
134+
| :--: | :-------- |
135+
| 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 `<ep_name>?<ep_library_path>`. |
136+
| Note |This switch is not to be used in shipping scenarios and is ignored by default |
137+
| 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` |
138+
139+
### `--webnn-ort-graph-optimization-level`
140+
141+
| Name | WebNN ONNX Runtime Graph Optimization Level |
142+
| :--: | :-------- |
143+
| Description | Configure the graph optimization level of ONNX Runtime |
144+
| Note | Levels could be "DISABLE_ALL", "BASIC", "EXTENDED" and "ALL" |
145+
| Usage | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --webnn-ort-graph-optimization-level=DISABLE_ALL` |
146+
147+
### `--webnn-ort-enable-profiling`
148+
149+
| Name | WebNN ONNX Runtime Enable Profiling |
150+
| :--: | :-------- |
151+
| 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`.|
152+
| Note | The prefix can be provided by user or use `WebNNOrtProfile` as default |
153+
| Usage | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --no-sandbox --webnn-ort-enable-profiling="WebNNOrtOvCpuProfile"` |
154+
119155
## Other Switches
120156

157+
### `--disable-gpu-sandbox`
158+
159+
| Name | Disable GPU Sandbox |
160+
| :--: | :-------- |
161+
| 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. |
162+
| Note | This is an insecure configuration. After performing the test, you should quit Chrome and re-launch normally. |
163+
| Usage | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --disable-gpu-sandbox` |
164+
121165
### `--no-sandbox`
122166

123167
| Name | No Sandbox |
124168
| :--: | :-------- |
125-
| 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. |
126-
| Note | Running with `--no-sandbox` is an insecure configuration. After performing the test, you should quit Chrome and re-launch normally. |
169+
| 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. |
170+
| Note | This is an insecure configuration. After performing the test, you should quit Chrome and re-launch normally. |
127171
| Usage | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --no-sandbox` |
128172

173+
129174
### `--allow-third-party-modules`
130175
| Name | Allow Third-party Modules |
131176
| :--: | :-------- |
132-
| Description | The `--allow-third-party-modules` flag permits third-party software to inject DLLs or modules into Chrome's processes. |
177+
| Description | Permits third-party software to inject DLLs or modules into Chrome's processes |
133178
| Note | While useful for legitimate software like antivirus or accessibility tools, it can pose security risks by allowing potentially malicious code injection. |
134179
| Usage | `"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --allow-third-party-modules` |
135180

‎content/en/learn/get-started/_meta.js‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,4 +11,7 @@ export default {
1111
'testing': {
1212
title: "🧪 Testing"
1313
},
14+
'debug': {
15+
title: "🧪 Debug"
16+
},
1417
};

‎content/en/learn/get-started/debug.mdx‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
import { Steps } from 'nextra/components'
2+
import InfoIcon from '../../../../app/_components/icons/info.jsx'
3+
import AppleIcon from '../../../../app/_components/icons/ihv/apple.jsx'
4+
import AMDIcon from '../../../../app/_components/icons/ihv/amd.jsx'
5+
import IntelIcon from '../../../../app/_components/icons/ihv/intel.jsx'
6+
import QualcommIcon from '../../../../app/_components/icons/ihv/qualcomm.jsx'
7+
import NvidiaIcon from '../../../../app/_components/icons/ihv/nvidia.jsx'
8+
9+
# Debugging
10+
11+
## Use Custom Build of ONNX Runtime
12+
13+
1. Follow the [WebNN Installation Guide](installation) to enable WebNN API and switch to Windows ML / ONNX Runtime backend
14+
2. Put the ONNX Runtime dynamic link librares into a folder under `C:\Program Files\`, e.g. `C:\Program Files\ONNXRuntime`
15+
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)
16+
17+
<div className="ort-ep">
18+
```shell
19+
"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --webnn-ort-library-path-for-testing="C:\Program Files\ONNXRuntime" --allow-third-party-modules
20+
```
21+
</div>
22+
23+
<div className="ort-ep">
24+
```shell
25+
"%LOCALAPPDATA%\Microsoft\Edge SxS\Application\msedge.exe" --webnn-ort-library-path-for-testing="C:\Program Files\ONNXRuntime" --allow-third-party-modules
26+
```
27+
</div>
28+
29+
## Use Custom Build of Execution Providers
30+
31+
If you are running WebNN on AMD, Intel, Nvidia, or Qualcomm devices and need to debug WebNN using specific Execution Provider of ONNX Runtime:
32+
33+
1. Follow the [WebNN Installation Guide](installation) to enable WebNN API and switch to Windows ML / ONNX Runtime backend
34+
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`
35+
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)
36+
37+
### Execution Provider Mapping Table for Independent Hardware Vendors
38+
39+
<div className="table-center">
40+
| IHVs | Execution Provider | DLL |
41+
| --- | --- | -- |
42+
| <IntelIcon /> | OpenVINOExecutionProvider | onnxruntime_providers_openvino_plugin.dll |
43+
| <AMDIcon /> | TBD | TBD |
44+
| <NvidiaIcon /> | NvTensorRTRTXExecutionProvider | onnxruntime_providers_nv_tensorrt_rtx.dll |
45+
| <QualcommIcon /> | QNNExecutionProvider | onnxruntime_providers_qnn.dll |
46+
</div>
47+
48+
### Intel OpenVINO Execution Provider
49+
50+
The following examples show how to specify the locations of `ONNX Runtime` and `Intel OpenVINO Execution Provider` libraries:
51+
52+
<div className="ort-ep">
53+
```shell
54+
"%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"
55+
```
56+
</div>
57+
58+
<div className="ort-ep">
59+
```shell
60+
"%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"
61+
```
62+
</div>
63+
64+
### Other IHVs
65+
66+
#### AMD (TBD)
67+
68+
TBD
69+
70+
#### Nvidia Nv Tensor RT RTX Execution Provider
71+
72+
<div className="ort-ep">
73+
```shell
74+
"%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"
75+
```
76+
</div>
77+
78+
<div className="ort-ep">
79+
```shell
80+
"%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"
81+
```
82+
</div>
83+
84+
#### Qualcomm QNN Execution Provider
85+
86+
<div className="ort-ep">
87+
```shell
88+
"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --webnn-ort-ep-library-path-for-testing=QNNExecutionProvider?"C:\Program Files\ONNXRuntime-EP\onnxruntime_providers_qnn.dll"
89+
```
90+
</div>
91+
92+
<div className="ort-ep">
93+
```shell
94+
"%LOCALAPPDATA%\Microsoft\Edge SxS\Application\msedge.exe" --webnn-ort-ep-library-path-for-testing=QNNExecutionProvider?"C:\Program Files\ONNXRuntime-EP\onnxruntime_providers_qnn.dll"
95+
```
96+
</div>
97+
98+
## Use Custom Build of GPU or NPU Drivers
99+
100+
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.
101+
102+
<div className="ort-ep">
103+
```shell
104+
"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --allow-third-party-modules
105+
```
106+
</div>
107+
108+
<div className="ort-ep">
109+
```shell
110+
"%LOCALAPPDATA%\Microsoft\Edge SxS\Application\msedge.exe" --allow-third-party-modules
111+
```
112+
</div>
113+
114+
## Debug Sandbox Issues
115+
116+
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.
117+
118+
<div className="ort-ep">
119+
```shell
120+
"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --disable-gpu-sandbox
121+
```
122+
</div>
123+
124+
<div className="ort-ep">
125+
```shell
126+
"%LOCALAPPDATA%\Microsoft\Edge SxS\Application\msedge.exe" --disable-gpu-sandbox
127+
```
128+
</div>
129+
130+
## Inspect the Verbose Logging
131+
132+
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".
133+
134+
<div className="ort-ep">
135+
```shell
136+
"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --webnn-ort-logging-level=VERBOSE
137+
```
138+
</div>
139+
140+
<div className="ort-ep">
141+
```shell
142+
"%LOCALAPPDATA%\Microsoft\Edge SxS\Application\msedge.exe" --webnn-ort-logging-level=VERBOSE
143+
```
144+
</div>
145+
146+
## Additional Resources
147+
148+
- [WebNN Flags and Switches in Chromium](../../api-reference/browser-compatibility/chrome-flags)

‎content/en/learn/get-started/installation.mdx‎

Lines changed: 2 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ import NvidiaIcon from '../../../../app/_components/icons/ihv/nvidia.jsx'
5252
```shell
5353
C:\Users\webnn\Downloads>ExecutionProviderCatalog.exe
5454
```
55-
It will display the following similar logs:
55+
The Execution Providers (EPs) to be installed depend on your computer’s hardware configuration. It will display the following similar logs:
5656

5757
<div className="shell-font-small">
5858
```shell
@@ -72,15 +72,7 @@ Provider 1:
7272
```
7373
</div>
7474

75-
> <InfoIcon /> The installation time may vary depending on your network speed. The Execution Providers (EPs) to be installed depend on your computer's hardware configuration.
76-
77-
78-
<div className="table-center">
79-
| IHVs | Execution Provider | IHVs | Execution Provider |
80-
| --- | --- | --- | --- |
81-
| <IntelIcon /> | Intel OpenVINO EP | <AMDIcon /> | TBD |
82-
| <NvidiaIcon /> | TBD | <QualcommIcon /> | TBD |
83-
</div>
75+
> <InfoIcon /> The installation time may vary depending on your network speed
8476
8577
### Navigate to `about://flags` in browser address bar
8678
### Search for `ONNX Runtime backend for WebNN` and change it to `Enabled`

0 commit comments

Comments
 (0)