Skip to content

Commit a358c0a

Browse files
edgchen1Copilot
andcommitted
Address PR 29716 review feedback on onnxruntime-web deprecation docs
- WebGPU coverage table (WebGL doc 4.1): switch from pinned MDN 'full support' versions to qualitative status, note WebGPU has shipped by default in Chrome/Edge since 113, keep Firefox as plain 'partial' (no roadmap claim), and link MDN api.GPU as the live source (per Copilot reviewer). - Migration guide (JSEP doc 11): add guidance to prefer onnxruntime-web/jspi on JSPI-capable browsers for a smaller WASM and lower per-call overhead, with Asyncify as the universal fallback (per qjia7). - int64 gap (JSEP doc 6): replace the misleading 'CPU-fallback cost' phrasing with the actual cost (CPU/WASM execution of int64-input ops plus partition-boundary copies; no GPU-to-CPU download of int64 data) (per qjia7). - Remove the Last updated field from both docs. Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
1 parent e3c889f commit a358c0a

2 files changed

Lines changed: 24 additions & 18 deletions

File tree

docs/design/onnxruntime_web_jsep_to_webgpu_ep_migration.md

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
# Design: Migrate onnxruntime-web WebGPU/WebNN from JSEP to the native WebGPU EP
22

3-
**Last updated:** 2026-07-14
43
**Scope:** `onnxruntime-web` JavaScript/TypeScript package — WebGPU and WebNN backends
54

65
**Related work:** [Remove the WebGL (onnxjs) backend from onnxruntime-web](onnxruntime_web_remove_webgl_backend.md)
@@ -149,14 +148,15 @@ kernel only guards int64 *inputs*), so "int64 off" narrows to int64 *inputs*, no
149148
**Why it's not a blocker.** int64 in real models carries indices/shapes/axes/token IDs, all `≪ 2³¹` (a tensor
150149
with `> 2³¹` elements can't fit in a `< 2GB` buffer), so JSEP (GPU-truncated) and native-int64-off (CPU-full)
151150
produce identical numeric results for realistic models — the difference is **performance only**. `transformers.js`
152-
already runs the native EP with int64 **off** at scale on int64-heavy token-ID models, confirming the
153-
CPU-fallback cost is acceptable.
151+
already runs the native EP with int64 **off** at scale on int64-heavy token-ID models, confirming the overhead of
152+
running those int64-input ops on CPU/WASM (plus the partition-boundary copies — int64 inputs typically originate on
153+
CPU, and results are uploaded back to the GPU) is acceptable.
154154

155155
**Decision.** Keep int64 **off by default** everywhere, with a uniform native-EP config across `.` and `/webgpu`.
156156
Migrating JSEP users (always-truncating) to native-int64-off is a correctness *upgrade*. Follow-ups (not
157157
blockers): (1) an **optional** typed `enableInt64?: boolean` on `WebGpuExecutionProviderOption` as sugar over the
158-
`extra` key that already works today; (2) benchmark an int64-heavy graph (tokenizer / LLM decode) to quantify the
159-
CPU-fallback cost.
158+
`extra` key that already works today; (2) benchmark an int64-heavy graph (tokenizer / LLM decode) to quantify that
159+
cost (CPU/WASM execution of the int64-input ops plus the partition-boundary copies).
160160

161161
**Graph-capture interaction (resolved).** Graph capture and int64 are coupled inside the EP
162162
(`enable_int64_{config.enable_graph_capture || config.enable_int64}` in `webgpu_execution_provider.cc`): capture
@@ -300,6 +300,10 @@ EP), so no consumer on the documented path hits an error. Communicated via relea
300300
- **Default import (`onnxruntime-web`):** no code change needed. The `webgpu` backend continues to work; the
301301
implementation swaps to the native EP in Phase 1 (this release).
302302
- **`onnxruntime-web/all`:** continues to work and converges to the native EP.
303+
- **Lower-overhead build (`onnxruntime-web/jspi`):** when you can target JSPI-capable browsers, prefer the `./jspi`
304+
bundle. It runs the **same native WebGPU EP** but bridges async via **JSPI** instead of Asyncify, giving a
305+
smaller WASM binary and lower per-call overhead. The default (Asyncify) build remains the universal fallback for
306+
browsers without JSPI.
303307
- **Need JSEP for one more release:** import `onnxruntime-web/jsep` (temporary, deprecated). Please file an issue
304308
if the native WebGPU EP does not work for your model so the gap can be fixed before JSEP is deleted.
305309
- **int64-heavy models needing JSEP-identical GPU behavior:** set

docs/design/onnxruntime_web_remove_webgl_backend.md

Lines changed: 15 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
# Design: Remove the WebGL (onnxjs) backend from onnxruntime-web
22

3-
**Last updated:** 2026-07-14
43
**Scope:** `onnxruntime-web` JavaScript/TypeScript package — WebGL backend
54

65
**Related work:**
@@ -70,20 +69,23 @@ nothing.
7069
### 4.1 WebGPU browser coverage
7170

7271
The historical reason to keep WebGL was "WebGPU isn't available on Safari / iOS / Firefox." As of 2026 that is
73-
**less true**, though per MDN's `api.GPU` browser-compat data gaps remain:
72+
**less true** — WebGPU has shipped enabled-by-default in Chrome/Edge since **113** (2023), in Safari (macOS/iOS),
73+
and in Chrome for Android; Firefox support is partial. Per MDN's
74+
[`api.GPU`](https://developer.mozilla.org/docs/Web/API/GPU#browser_compatibility) browser-compat data, gaps
75+
remain:
7476

75-
| Browser | WebGPU (per MDN BCD) |
77+
| Browser | WebGPU |
7678
|---|---|
77-
| Chrome / Edge (desktop) | Full from 144 (Linux: Intel Gen12+ only) |
78-
| Chrome Android | Full from 121 |
79-
| Safari (macOS / iOS) | Full from 26 |
80-
| Firefox (desktop) | Partial from 141 |
81-
| Firefox for Android ||
82-
83-
Safari/iOS and Chrome/Edge desktop are solid, but gaps remain (older versions, Firefox for Android, Firefox
84-
desktop still partial). Coverage is **broadening but not universal**, so the pool of users for whom WebGL is the
85-
*only* GPU path is shrinking, not gone. The design does **not** assume universal WebGPU — the actionable fallback
86-
for uncovered users is the WASM/CPU backend.
79+
| Chrome / Edge (desktop) | ✅ (default since 113; Linux support landed later) |
80+
| Chrome (Android) | |
81+
| Safari (macOS / iOS) | |
82+
| Firefox (desktop) | ⚠️ partial |
83+
| Firefox (Android) ||
84+
85+
Chrome/Edge and Safari/iOS are solid, but gaps remain (older versions, Firefox for Android, Firefox desktop still
86+
partial). Coverage is **broadening but not universal**, so the pool of users for whom WebGL is the *only* GPU path
87+
is shrinking, not gone. The design does **not** assume universal WebGPU — the actionable fallback for uncovered
88+
users is the WASM/CPU backend.
8789

8890
---
8991

0 commit comments

Comments
 (0)