When Transformers.js runs on its WASM backend, what do env.backends.onnx.wasm numThreads, proxy and wasmPaths control, and when do you change each?
answer
- the runtime's flags, not the library's
- mutate fields before the first load
- zero threads lets the runtime decide
- proxy off by default, own worker instead
- object paths keep the binary cached
basics
~20 sONNX Runtime Web's WebAssembly flags: numThreads sizes the thread pool (0 lets the runtime decide), proxy runs inference in a runtime-managed worker (off by default), and wasmPaths sets where the runtime's .wasm and .mjs files are fetched.
solid answer
~50 s`env.backends.onnx.wasm` is ONNX Runtime Web's own `env.wasm` object, shared by reference, so you mutate its fields before the first model loads. `numThreads` defaults to `0`, letting the runtime choose, and only takes effect where WebAssembly multithreading is available, which in browsers requires a cross-origin-isolated page; `1` spawns no worker threads. `proxy` runs WASM inference in a worker ONNX Runtime manages; Transformers.js sets it to `false`, and you turn it on only when main-thread inference freezes the UI and you are not already in your own worker. `wasmPaths` locates the runtime files; Transformers.js 4.3 defaults it to jsDelivr URLs for the exact `onnxruntime-web` build it bundles, and you override it for a strict CSP or offline hosting, preferably as a `{ wasm, mjs }` object so `env.useWasmCache` can cache the binary. Under Node none of these apply.
code
javascript · 14 linesimport { env, pipeline } from '@huggingface/transformers';
// Configure ONNX Runtime Web before the first model loads.
const wasm = env.backends.onnx.wasm; // shared with ONNX Runtime: mutate, never replace
wasm.wasmPaths = {
mjs: new URL('/ort/ort-wasm-simd-threaded.asyncify.mjs', location.origin).href,
wasm: new URL('/ort/ort-wasm-simd-threaded.asyncify.wasm', location.origin).href,
};
wasm.numThreads = 2; // leave cores for the rest of the page
wasm.proxy = false; // this code already runs inside our own worker
const classifier = await pipeline('text-classification', 'your-org/your-model', {
device: 'wasm',
});go deeper
Recall that these are ONNX Runtime's WebAssembly settings reached through env.backends.onnx.wasm, and that they only matter when the model runs on 'wasm'.
Explain each flag's default, that numThreads needs WebAssembly multithreading, and why proxy stays off when the pipeline already runs in your own worker.
Show the operational traps: mutate before the first load, never replace the object, self-host wasmPaths as an object for caching, and use session_options in Node.
Weigh serving runtime binaries from a public CDN against self-hosting them, counting CSP, offline use, version pinning and who owns upgrades.
## Whose settings these are Transformers.js does not implement its own WebAssembly runtime. In a browser it loads **ONNX Runtime Web** (`onnxruntime-web`), and that runtime has its own configuration object. Transformers.js exposes it as **`env.backends.onnx`**, so `env.backends.onnx.wasm` holds ONNX Runtime's **WebAssembly flags**. Three of them matter in practice: `numThreads`, `proxy` and `wasmPaths`. One detail shapes how you set them. Transformers.js builds `env.backends.onnx` as a **shallow copy** of ONNX Runtime's environment object (`{ ...ortEnv, setLogLevel }`). The nested `wasm` object is therefore shared with ONNX Runtime, so **mutating its fields works**, but **assigning a new object** to `env.backends.onnx.wasm` replaces only the copy's property and never reaches the runtime. Set these flags **before the first model loads**: ONNX Runtime initialises each backend once, on the first session, and reuses that initialisation afterwards. ## numThreads - **What it is**: the size of the WebAssembly thread pool used for one inference. - **Default**: `0`, meaning "let the runtime decide from the system". `1` means no worker threads are spawned. - **Where it applies**: only where **WebAssembly multithreading** is available in the current context. Threads in WebAssembly rely on `SharedArrayBuffer`, which browsers expose only to cross-origin-isolated pages. On a page that is not isolated, the setting has nothing to act on and inference stays single-threaded, whatever value you set. - **When to change it**: lower it to leave cores for the rest of the page or for other workers; set `1` when you want predictable, contention-free behaviour. - **Not in Node**: `onnxruntime-node` runs native code, so threading there is set through `session_options` passed to `pipeline()`, using ONNX Runtime's `intraOpNumThreads`. ## proxy - **What it is**: whether ONNX Runtime moves WebAssembly execution off the calling thread into a worker that ONNX Runtime manages itself. - **Default in Transformers.js**: `false`. ONNX Runtime's own default is also `false`, and Transformers.js sets it explicitly with the comment that proxying is not necessary for WebGPU. - **When to turn it on**: a page that runs a WASM model on the main thread and freezes while it does. Proxying is ONNX Runtime's built-in way to keep the UI responsive without restructuring your code. - **When to leave it off**: when you already run the pipeline inside your own Web Worker, a common structure, and on WebGPU. Transformers.js also skips keeping generation outputs in GPU buffers when proxying is on. ## wasmPaths - **What it is**: where ONNX Runtime fetches its `.wasm` binary and the `.mjs` factory that loads it. It accepts a **URL prefix string** or an **object** `{ wasm, mjs }` of absolute URLs. - **Default in Transformers.js 4.3**: unless you set it first (and unless the code runs in a service worker), the library points it at jsDelivr, at the exact `onnxruntime-web` version it bundles, using the asyncify build: `ort-wasm-simd-threaded.asyncify.wasm` and `.mjs`. On Safari below 26 without WebGPU it picks the plain `ort-wasm-simd-threaded` files instead. - **When to change it**: a strict Content Security Policy that forbids third-party script and fetch origins, an air-gapped or intranet deployment, or a requirement that every byte is served from your own origin. Copy the files from the `onnxruntime-web` build your installed Transformers.js depends on, because the default URL is built from that exact version. - **Prefer the object form.** With `env.useWasmCache` on (the default where a cache is available), Transformers.js pre-loads the binary and factory and stores them in its cache, so the runtime survives offline reloads. That pre-load runs only when `wasmPaths` is an object with both `wasm` and `mjs` set; a prefix string skips it. ## Order of operations 1. **Import** `env` from `@huggingface/transformers`; the backend module fills `env.backends.onnx` as it loads. 2. **Mutate** the fields of `env.backends.onnx.wasm` you need: `wasmPaths`, `numThreads`, `proxy`. 3. **Create** the first pipeline, which creates the first session and initialises the runtime with those values. 4. **Verify** in the browser's network panel that the runtime files came from where you intended, and in a performance trace that threads were actually used. ## Summary table | Flag | Default under Transformers.js | Typical reason to change it | |---|---|---| | `numThreads` | `0` (runtime decides) | leave cores for the page; deterministic single thread | | `proxy` | `false` | main-thread WASM inference freezing the UI | | `wasmPaths` | jsDelivr URLs for the bundled ORT build | CSP, offline, self-hosted assets | A last caution: in web environments Transformers.js queues session creation and every inference call on one chain, so more threads speed up a single inference but never let two calls on the same page overlap.
- You set numThreads to 8 and inference is no faster. What do you check first?Whether the page can run WebAssembly threads at all. They need `SharedArrayBuffer`, which browsers expose only on cross-origin-isolated pages; elsewhere `numThreads` has nothing to act on and inference stays single-threaded. Then check that the value was set before the first session was created, since the backend initialises once.
- How do you limit threads for Transformers.js running in Node?Not with `env.backends.onnx.wasm`, which belongs to the WebAssembly runtime. Node uses `onnxruntime-node`, so pass `session_options` to `pipeline()` or `from_pretrained()` with ONNX Runtime's `intraOpNumThreads` (and `interOpNumThreads` if needed), which only the native binding honours.
- numThreads = 0 turns multithreading off.
- Setting numThreads gives you threads on any page, isolated or not.
- Assigning a fresh object to env.backends.onnx.wasm is the way to configure it.
- Transformers.js proxies WASM to a worker by default.
- The WASM binary ships inside the model repository on the Hub.
- env.backends.onnx.wasm also tunes onnxruntime-node in a server.
Assumes Transformers.js 4.3, which bundles an onnxruntime-web 1.31 dev build, defaults wasmPaths to that build's asyncify files on jsDelivr and pre-caches them through env.useWasmCache.