Environment:Mlc ai Mlc llm WebGPU Browser Environment

Knowledge Sources	MLC-LLM WebGPU
Domains	Infrastructure, Web, GPU_Acceleration
Last Updated	2026-02-09 19:00 GMT

Overview

WebGPU and WebAssembly environment for running LLM inference directly in web browsers, compiled to `.wasm` system libraries with Emscripten.

Description

This environment enables in-browser LLM inference using the WebGPU API for GPU acceleration and WebAssembly for the runtime. Models are compiled to `.wasm` files using the TVM WebGPU backend with a WASM host target. The build process requires the `mlc_wasm_runtime.bc` pre-compiled bitcode file (generated by `web/prep_emcc_deps.sh`) and uses Emscripten for the final linking step. The WebGPU target has a thread warp size of 1 and 32KB max shared memory.

Usage

Use this environment when deploying LLM models to web browsers via WebGPU. It requires a WebGPU-capable browser (Chrome 113+, Edge 113+, or Firefox Nightly with WebGPU flag).

System Requirements

Category	Requirement	Notes
Browser	WebGPU-capable	Chrome 113+, Edge 113+, Firefox Nightly
Toolchain	Emscripten	Required for WASM compilation
Host OS	Linux or macOS	For cross-compilation

Dependencies

System Packages (Host)

• Emscripten SDK (`emsdk`)
• `cmake` < 4.0
• `git`

Pre-built Assets

• `mlc_wasm_runtime.bc` — Pre-compiled WASM runtime bitcode (generated by `web/prep_emcc_deps.sh`)

Credentials

The following environment variables are used:

• `MLC_LLM_SOURCE_DIR`: Path to MLC-LLM source root, used to locate `mlc_wasm_runtime.bc`.

Quick Install

# Prepare Emscripten dependencies
cd web && ./prep_emcc_deps.sh

# Set source directory for build
export MLC_LLM_SOURCE_DIR=/path/to/mlc-llm

# Compile model for WebGPU
python -m mlc_llm compile model_path --device webgpu --output model.wasm

Code Evidence

WebGPU target preset from `auto_target.py:463-472`:

"webgpu:generic": {
    "target": {
        "kind": "webgpu",
        "host": {
            "kind": "llvm",
            "mtriple": "wasm32-unknown-unknown-wasm",
        },
    },
    "build": _build_webgpu,
},

WASM runtime bitcode location from `auto_target.py:237-256`:

bc_candidates = ["web/dist/wasm/mlc_wasm_runtime.bc"]
if os.environ.get("MLC_LLM_SOURCE_DIR", None):
    mlc_source_home_dir = os.environ["MLC_LLM_SOURCE_DIR"]
    bc_candidates.append(
        os.path.join(mlc_source_home_dir, "web", "dist", "wasm", "mlc_wasm_runtime.bc")
    )
error_info = (
    "Cannot find library: mlc_wasm_runtime.bc\n"
    + "Make sure you have run `./web/prep_emcc_deps.sh` and "
    + "`export MLC_LLM_SOURCE_DIR=/path/to/mlc-llm`"
)

Common Errors

Error Message	Cause	Solution
`Cannot find library: mlc_wasm_runtime.bc`	Emscripten dependencies not prepared	Run `./web/prep_emcc_deps.sh` and set `MLC_LLM_SOURCE_DIR`
WebGPU not available	Browser does not support WebGPU	Use Chrome 113+ or Edge 113+

Compatibility Notes

• Browser Support: WebGPU is available in Chrome 113+, Edge 113+. Firefox requires enabling the WebGPU flag in Nightly.
• WASM Limitations: WebAssembly has memory constraints; large models may not fit. Quantized models (INT4) are recommended.
• No Streaming: Browser-side streaming behavior depends on the JavaScript runtime integration.

Related Pages

• Implementation:Mlc_ai_Mlc_llm_Compile