Skip to content

Latest commit

 

History

History
543 lines (398 loc) · 26.5 KB

README.en.md

File metadata and controls

543 lines (398 loc) · 26.5 KB

🌐 Canonical repository is on GitHub — codecloud-dev/moxwebgpu is the single source of truth: please file all issues and pull requests there. The Gitee mirror is a read-only copy synced hourly for faster access in mainland China.

moxwebgpu liquid glass logo

moxwebgpu

MoX Series: WebGPU 计算 WebGPU: GPGPU TypeScript: strict WGSL: 原生内核 zero: 依赖 0

CI npm: @codecloud-dev/moxwebgpu License Stars Last commit tests: 66 unit PRs welcome

English · 中文 · 📖 Docs · 🚀 Live demo

⭐ If moxwebgpu is useful to you, please give it a star — it helps more people run GPU compute in the browser!

🐛 Welcome to roast me

This is an early-stage project — bugs exist, and probably plenty of them. I'm not pretending it's perfect. Every pitfall you hit and every gripe you have is a chance to help make it better.

  • 💥 Crashed / black screen / won't run? → File a bug report
  • 💡 Want a feature? → Open a feature request
  • 🗯️ Just want to rant or nitpick? → Issues are welcome too, label it whatever 😄

I read every issue and fix what I can, fast. Let's grow this from "runs" to "delightful" 💪

moxwebgpu — browser GPU training animation: data flows into the GPU and the loss curve keeps dropping


📑 目录 · Contents

💡 What it is

Raw WebGPU compute is powerful but brutal: adapter/device boilerplate, WGSL pipelines, bind groups, manual buffer lifecycles, staging readbacks — and validation errors are silent (a broken shader just turns your dispatch into a no-op and your output into zeros).

moxwebgpu = MoX + WebGPU: a WebGPU general-purpose compute (GPGPU) framework. It wraps all of the boilerplate behind three layers:

Tensor   gpu.tensor([1,2,3]).add(1).relu().sum().item()   ← the only layer you touch
Lazy graph   topo-sorted, one submit, refcount-recycled buffers
Core     BufferPool (power-of-two buckets) · PipelineCache (WGSL hash) · raw Kernel
  • One unified API — reductions, broadcasting and elementwise ops share one calling convention
  • Lazy by default — a whole chain dispatches once on .item(); intermediates never leak
  • 30+ GPU ops — elementwise, two-phase tree reductions, argmax/argmin, 16×16-tiled matmul, fused softmax, strided slicing/concat, zero-copy reshape
  • Reverse-mode autodiff built in — .withGrad() / .backward() fill .grad lazily; train models entirely in the browser (since v1.0)
  • Silent-failure defense — shader compile errors surfaced with line/column via getCompilationInfo()
  • 99 passing tests — 66 unit tests (CPU-only, pnpm test) + 33 GPU e2e (value-compared against CPU references), green even on GPU-less machines via SwiftShader + xvfb
  • Zero runtime dependencies, ESM + CJS + IIFE + d.ts, ~30 KB browser bundle

💡 About this project

moxwebgpu is a standalone open-source library: rebuilding, properly, the WebGPU general-purpose compute capability that "should be simple" in the browser.

Project Status One-liner
moxwebgpu live (this repo) WebGPU GPGPU framework

📦 Install

✅ Published to npm: package name @codecloud-dev/moxwebgpu (current version: 1.1.4). OIDC token-less publish flow is wired up (.github/workflows/publish.yml). Install via npm below, or build from source.

Browser <script> (zero build):

<script src="https://unpkg.com/@codecloud-dev/moxwebgpu/dist/moxwebgpu.browser.js"></script>
<script>
  const gpu = await MoxWebGPU.mox.init();
  console.log(await gpu.tensor([1, 2, 3]).sum().item()); // 6
</script>

npm (Node / bundlers):

npm install @codecloud-dev/moxwebgpu        # pnpm add @codecloud-dev/moxwebgpu / yarn add @codecloud-dev/moxwebgpu
import { mox } from '@codecloud-dev/moxwebgpu';           // ESM
// const { mox } = require('moxwebgpu');   // CJS

From source:

git clone https://github.com/codecloud-dev/moxwebgpu.git
cd moxwebgpu && pnpm install && pnpm build

WebGPU requires a secure context: localhost or https. Chrome/Edge 113+ ship it by default.


🚀 Quick start

const gpu = await mox.init();

🔹 Chained & lazy

const r = await gpu.tensor([1, 2, 3, 4])
  .add(1).relu().mul(10).sum().item();   // 140 — dispatches once

🔹 Broadcasting (explicit, never silent)

const A = gpu.tensor([[1, 2, 3], [10, 20, 30]]);  // [2,3]
await A.add(gpu.tensor([1, 2, 3])).toArray();   // row broadcast
await A.mul(gpu.tensor([2, 3])).toArray();      // col broadcast
await A.add(gpu.tensor([1, 2]));                // ❌ throws — no implicit broadcasting

🔹 Matmul, reductions, softmax

await gpu.tensor([[1, 2], [3, 4]]).matmul(gpu.tensor([[5, 6], [7, 8]])).toArray();
// [19, 22, 43, 50] — 16×16 workgroup tiling

const x = gpu.tensor([[1, 2, 3, 4], [5, 6, 7, 8]]);
await x.sum().item();      // 36         global → [1]
await x.sum(-1).toArray(); // [10, 26]   last axis
await x.sum(0).toArray();  // [6, 8, 10, 12]   axis 0 → [4]
const t3 = gpu.tensor(Array.from({ length: 24 }, (_, i) => i), { shape: [2, 3, 4] });
await t3.sum(1).toArray(); // [12,15,18,21,48,51,54,57] — any axis of any rank; negative axes count from the end
await x.max().item();      // 8
await x.argmax().item();   // 7 (first occurrence wins)
await x.softmax().toArray(); // numerically stable, row sums = 1

🔢 Shapes & dtypes

await v.slice(2, 4).toArray();              // strided slice (≤4D)
await a.concat(b, 0).toArray();             // concat on any axis
const w = v.reshape([2, 5]);                // zero-copy view
await gpu.tensor([1.7, -3.9]).cast('i32').toArray(); // [1, -3] (trunc toward zero)

📚 One API for max/min

t.max()        // global reduce → [1]
t.max(-1)      // reduce along last axis (any axis works: t.max(0), t.sum(-2), …)
t.max(other)   // elementwise with another tensor
// unambiguous aliases: maxReduce / minReduce

🧠 Autodiff (reverse mode / training)

Since v1.0 moxwebgpu ships reverse-mode automatic differentiation layered directly on top of the lazy graph — an OpDef is pure metadata + codegen, each op carries a backward, and the reverse graph reuses the same ops. The GPU is touched only when you read a gradient.

import { mox } from '@codecloud-dev/moxwebgpu';

const gpu = await mox.init();
const x = gpu.tensor([1, 2, 3, 4]).withGrad();   // mark a differentiable leaf
const loss = x.mul(x).sum();                       // L = Σ x²

loss.backward();                                   // backprop
console.log(await x.grad.toArray());               // [2, 4, 6, 8] = dL/dx

Three things to know:

  • .withGrad(): marks a leaf as requiring gradients (other leaves are skipped by default).
  • .backward(): walks the scalar loss in reverse-topological order, filling .grad on every requiresGrad leaf. The whole pass only builds the lazy graph — it never touches the GPU until you await x.grad.toArray().
  • Broadcast-correct: binary-op gradients use sumTo to reduce back to the smaller operand's shape; sum/mean/softmax gradients broadcast back via expand.
// A minimal linear layer, forward + backward
const W = gpu.tensor([[0.1, 0.2], [0.3, 0.4]]).withGrad();
const inp = gpu.tensor([1, 1]);
const pred = W.matmul(inp);          // [2]
const loss = pred.mul(pred).sum();   // Σ pred²
loss.backward();
console.log(await W.grad.toArray());  // dL/dW, same shape as W

Ops with a registered backward: add/sub/mul/div (scalars and broadcast included), neg/abs/exp/log/sqrt/square/relu/sigmoid/tanh, matmul, sum/mean (global and any axis), softmax (last axis, numerically stable).

On the roadmap: layernorm / embedding / conv1d, pass fusion, Web Worker execution — planned for 1.0.x, not in this release.


🚀 Browser training walkthrough (no install — train a model in-page)

This is moxwebgpu's most underrated capability: it doesn't just do one-off GPGPU compute — it runs a full autodiff + gradient-descent training loop right in the browser. Data never leaves the page, no backend required; any laptop / phone / Raspberry Pi with WebGPU can train. Combined with the <script>-tag SDK above, any site can let a visitor's GPU train a small model on the spot.

The core logic below trains linear regression (least squares / MSE); the gradients really are computed on the GPU:

const gpu = await mox.init();
const X = gpu.tensor([[0], [1], [2], [3]]);
const Y = gpu.tensor([[1], [3], [5], [7]]);   // y ≈ 2x + 1
const lr = 0.05;
let W = gpu.tensor([[0]]).withGrad();          // differentiable parameters
let b = gpu.tensor([[0]]).withGrad();

for (let step = 0; step < 200; step++) {
  const pred = X.matmul(W).add(b);             // ŷ = X·W + b
  const diff = pred.sub(Y);
  const loss = diff.mul(diff).mean();          // MSE
  loss.backward();                             // gradients fill W.grad / b.grad (lazy, still on graph)

  // Hand-written SGD: read the updated values back, then rebuild differentiable leaves.
  W = gpu.tensor(await W.sub(W.grad.mul(lr)).toArray()).withGrad();
  b = gpu.tensor(await b.sub(b.grad.mul(lr)).toArray()).withGrad();
}
console.log('trained W, b =', await W.toArray(), await b.toArray()); // ≈ [[2]], [[1]]
  • Forward and backward stay on the lazy graph: backward() only builds the graph and fills .grad; nothing is dispatched until you await ...toArray() — no per-step CPU↔GPU round-trips.
  • No built-in optimizers yet: training hand-writes W = W - lr * W.grad as above. SGD / Adam are on the roadmap.
  • Trainable leaves need withGrad(): only marked leaves accumulate .grad, saving GPU memory.

🔥 Two-layer MLP (hidden layer + sigmoid)

Linear regression is one line; real models are multi-layer. The same hand-written SGD trains a two-layer MLP (input → hidden sigmoid → output):

const w1 = gpu.tensor([[0.1, -0.2], [0.3, 0.4]]).withGrad();
const b1 = gpu.tensor([0.0, 0.0]).withGrad();
const w2 = gpu.tensor([[0.2], [-0.1]]).withGrad();
const b2 = gpu.tensor([0.0]).withGrad();

const x = gpu.tensor([[1, 0], [0, 1]]);
const y = gpu.tensor([[1], [0]]);

for (let i = 0; i < 300; i++) {
  const h = x.matmul(w1).add(b1).sigmoid();
  const pred = h.matmul(w2).add(b2);
  const diff = pred.sub(y);
  diff.mul(diff).mean().backward();                 // autodiff handles matmul / bias / sigmoid / broadcast
  w1 = w1.sub(w1.grad.mul(lr)); b1 = b1.sub(b1.grad.mul(lr));
  w2 = w2.sub(w2.grad.mul(lr)); b2 = b2.sub(b2.grad.mul(lr));
}

Backprop handles matmul / bias add / sigmoid / broadcast automatically — you only write the forward pass, one backward(), and the parameter update.


⚙️ Raw kernel escape hatch

const k = gpu.kernel(`
  @group(0) @binding(0) var<storage, read> a: array<f32>;
  @group(0) @binding(1) var<storage, read_write> b: array<f32>;
  @compute @workgroup_size(64)
  fn main(@builtin(global_invocation_id) gid: vec3u) {
    b[gid.x] = a[gid.x] * 2.0 + 1.0;
  }`);
const a = gpu.tensor([1, 2, 3, 4, 5]);
const out = gpu.pool.acquire(5, 'f32');                 // GpuDataBuffer, elements = 5
// Pass the GpuDataBuffer (not .buffer): readback length follows buf.elements → exactly 5
const res = await k.run([a.data, out], { elements: 5 }); // → Float32Array(5) [3, 5, 7, 9, 11]

k.run() = dispatch + readback in one call; k.dispatch() dispatches only. Custom WGSL goes through the same pipeline cache and compile checks.

Readback length: run() prefers the GpuDataBuffer.elements count of pooled output buffers (the raw GPUBuffer is rounded up to a power-of-two bucket, so reading its full size would include padding). A bare GPUBuffer falls back to its raw size.


📚 Unified API

mox.init(options?) → Promise<MoxContext>

Option Type Notes
adapter GPUAdapter skip requestAdapter
powerPreference 'low-power' | 'high-performance'
requestAdapterOptions GPURequestAdapterOptions passthrough

🔹 MoxContext

Member Notes
tensor(data, opts?) nested arrays / TypedArray; opts.shape optional
kernel(code, opts?) workgroupSize / entryPoint / output / dtype
readback(buf) GPU buffer → CPU TypedArray
info() { vendor, architecture, device, description }
pool / pipelines / scheduler advanced
destroy() release everything

🔹 Tensor

Category Members
Props shape ndim dtype size
Shape reshape(...dims | number[]) zero-copy (-1 ok), transpose() (2D)
Binary add sub mul div pow (Tensor or scalar), rsub rdiv
Unary neg abs exp log sqrt sin cos tanh floor ceil relu sigmoid square sign
Reduce sum mean max min (no arg = global; -1/0 = axis; max(t) = elementwise), argmax argmin (→ u32)
Range clamp(lo, hi), slice(start, size) (≤4D), concat(other, axis?)
NN softmax()
Dtype cast('f32' | 'i32' | 'u32'), toFloat()
Readback await toArray() / await toBuffer() / await item()
Release destroy()

⚙️ Kernel / BufferPool

API Notes
k.run(buffers, { elements } | { workgroups }) dispatch + readback
k.dispatch(buffers, [wx, wy, wz]) dispatch only
pool.acquire(elements, dtype) / acquireUniform(bytes) strictly separate pools
pool.release / releaseUniform / live / pooled / clear() stats & teardown

🧮 Op reference

Family Ops GPU strategy
Elementwise add sub mul div pow min max clamp + rsub rdiv 1D / 2D row/col broadcast uniforms
Unary (14) neg abs exp log sqrt sin cos tanh floor ceil relu sigmoid square sign single pass
Global reduce sum mean max min argmax argmin two-phase tree (wg=64, chunk=8)
Axis reduce sum(-1), 2D sum(0) (via transpose) one workgroup per row
Matrix matmul 16×16 tile, workgroup-memory accumulation
Shape transpose (2D), slice (≤4D), concat, reshape (zero-copy) generic ND gather/copy (vec4 uniforms)
NN softmax fused 3-pass per row
Dtype cast f32↔i32↔u32 single pass, truncation
Autodiff .withGrad() / .backward() / .grad on differentiable leaves reverse graph reuses forward ops, broadcast-correct via sumTo/expand, GPU touched only on read

🔢 dtypes & uniform layout

dtype WGSL bytes readback
f32 f32 4 Float32Array
i32 i32 4 Int32Array
u32 u32 4 Uint32Array

All uniform blocks are 16-byte aligned; copy-family kernels use a 64-byte vec4-based block. Two hard-won lessons are baked into the design — see docs/ARCHITECTURE.md §8:

  1. ±Infinity is illegal in WGSL const-expressions → reduction identities ride in a uniform slot at runtime.
  2. Array strides in the uniform address space are inconsistently implemented across backends; vec4 member layout is not → copy kernels use vec4 dimensions (208 B → 64 B, too).

🐛 Error handling

WebGPU validation errors don't throw — objects go invalid, dispatches become no-ops. moxwebgpu's PipelineCache calls getCompilationInfo() after creating every ShaderModule and turns compile errors into readable line/column messages.

Error (excerpt) Meaning
moxwebgpu: WebGPU is not available here... no secure context / unsupported browser
moxwebgpu: no suitable GPU adapter adapter blocked; update drivers
moxwebgpu: broadcast failed ... shapes neither equal nor broadcastable
moxwebgpu: slice range [...] out of bounds slice OOB
moxwebgpu: axis ... reduce is not supported this op has no axis-reduce form (e.g. argmax); omit the argument for a global reduce
moxwebgpu: mean requires f32 input mean is f32-only; cast integers first (cast('f32'))

⚡ Benchmarks

pnpm bench, medians on SwiftShader (pure-CPU GPU emulation, same env as CI), full dispatch + readback path:

Workload Time Throughput
add 1M f32 (scalar) tens of ms —
matmul [512×512]·[512×512] ~890 ms ~0.3 GFLOP/s
sum 1M f32 (two-phase tree) ~69 ms —
add→relu→mul→sum 1M chain ~285 ms —

SwiftShader emulates a GPU on CPU — treat these as cross-regression numbers only. On real hardware the same code typically runs 10–100× faster.

Built-in performance design: lazy graph (one readback per chain), refcounted intermediates + power-of-two buckets (near-zero steady-state allocation), WGSL-hash pipeline cache.


🧪 Testing & quality

Suite Count Coverage
tests/unit/ 66 byte-level uniform encoders, WGSL codegen, topo sort, OpDef shapes, autograd, regression
tests/gpu/ 33 elementwise / broadcast / unary chains / lazy chains / matmul ×3 / all reductions / argmax / softmax / slice / concat / reshape views / deep pipelines / raw Kernel
tests/gpu/bench/ bench elementwise / matmul / reduce / chain (medians)

GPU cases are value-compared against CPU reference implementations — not "didn't crash" tests.

🔹 Real WebGPU on GPU-less machines (SwiftShader recipe)

# xvfb supplies a virtual display; Chrome's SwiftShader Vulkan ICD is the GPU

export VK_ICD_FILENAMES=/opt/google/chrome/vk_swiftshader_icd.json

# full Chromium (headless-shell has WebGPU stripped) + key flags
chromium --enable-unsafe-webgpu --enable-features=Vulkan --no-sandbox

# must load an https (or localhost) page for a secure context

tests/gpu/harness.ts automates all of it: detect Chrome + ICD → launch → open https page → inject dist/moxwebgpu.browser.js → run each case in-page and compare against CPU references. GitHub Actions runs the same recipe (.github/workflows/ci.yml).

Command What it does
pnpm build tsup → ESM / CJS / IIFE + d.ts
pnpm test 66 unit tests
pnpm test:gpu 33 GPU e2e (auto SwiftShader/xvfb)
pnpm test:all both
pnpm bench micro-benchmarks
pnpm demo build + serve the demo page (:5173)
pnpm exec tsc --noEmit type check

🌐 Browser demo

🌐 Try it live (no install):https://codecloud-dev.github.io/moxwebgpu/demo/ — your GPU, computing in front of you.

examples/browser/index.html is a self-contained liquid-glass demo — aurora ambient light, cursor-following glow, glass cards with backdrop filters. Four cards, all genuinely running on WebGPU: chained ops, 128² matmul, softmax with row-sum check, 1M-element reductions.

pnpm demo   # → http://localhost:5173

📦 Project structure

moxwebgpu/
├── src/
│   ├── index.ts                 # exports + installTensorOps + version
│   ├── core/                    # context · dtype · buffer(pool) · kernel
│   ├── graph/                   # lazy(DAG/OpDef) · pipelineCache · scheduler
│   └── tensor/                  # tensor.ts · codegen.ts · ops/{elementwise,reduce,matmul,shape,nn}
├── tests/
│   ├── unit/                     # unit tests (core / autograd / regression, 66 total)
│   └── gpu/                     # harness · ref(CPU) · 3 suites + bench/
├── scripts/run-gpu-tests.sh     # VK_ICD + xvfb wrapper
├── examples/browser/index.html  # liquid-glass demo
├── docs/ARCHITECTURE.md         # deep dive: uniforms, scheduler, post-mortems
├── assets/logo.svg              # liquid-glass logo
└── .github/workflows/ci.yml     # CI: typecheck + build + unit + SwiftShader e2e

Want to add an op? OpDef = pure metadata (shape inference + codegen) → two to five steps, see docs/ARCHITECTURE.md §5.

🗺️ Roadmap

  • v0.1 — three-layer architecture, 30+ ops, 33 real GPU e2e tests, liquid-glass demo
  • v0.2 — arbitrary-axis reductions (any rank / negative axes), integer reduction fixes, scheduler temp recycling
  • v1.0 — reverse-mode autodiff on the lazy graph, backward for matmul/softmax/sum/mean, token-free OIDC publishing to npm
  • npm first publish (@codecloud-dev/moxwebgpu, currently 1.1.4) + docs site live
  • More NN ops: layernorm / embedding / conv1d
  • Adjacent-elementwise op pass fusion (fewer dispatches)
  • Run inside a Web Worker / OffscreenCanvas
  • f16 / bf16 dtypes, SGD / Adam optimizers
  • tensor-core-friendly matmul (double buffering), ecosystem integrations

❓ FAQ

Q: My browser console says navigator.gpu is undefined?
A: WebGPU needs Chrome/Edge 113+ and a secure context (https or localhost). Opening via file:// won't work — use pnpm demo to start a local server.

Q: Results are all zeros / garbage?
A: 99% of the time it's a silent WGSL compile failure (no-op). moxwebgpu prints compile errors to the console with line/column numbers — fix the shader accordingly. Using the built-in ops avoids this entirely.

Q: How does this relate to TensorFlow.js / transformers.js?
A: They are model-centric — prebuilt models for inference. moxwebgpu is op-centric — NumPy-like raw compute power plus an escape hatch, exactly the general GPGPU foundation they don't provide.

Q: Does it support training (backprop)?
A: Yes. Since v1.0 reverse-mode autodiff is built in: call .withGrad() on leaves, build the forward graph, then .backward() fills .grad (lazily — GPU is touched only on read). See Autodiff.

Q: Why does pnpm test:gpu pass on my machine — I don't have an NVIDIA card?
A: SwiftShader — Chrome's pure-software Vulkan implementation. The GPU test recipe does not require a real GPU, and CI runs the same way.

Q: Do i32/u32 multiplies overflow?
A: They follow WGSL semantics (bitwise wrap-around). Reduction identities, encoders, and readback views all handle this per dtype.

🤝 Contributing

Issues and PRs welcome. Keep PRs focused; add tests for behavior changes. GPU-affecting changes should run pnpm test:gpu locally (SwiftShader works on any machine).

💖 Supporting

moxwebgpu is an independently developed, free and open-source project, and will keep being maintained. If it saves you time writing WebGPU boilerplate, a ⭐ star goes a long way — it is what helps others find the project.

If it is useful in your work, you can also support development:

Afdian sponsorship QR code

Stars, shares, or telling me where you use it are the best support. See FUNDING.yml for the channels.

📜 License

MIT © codecloud-dev. Designed by codecloud-dev; code co-written with AI, human-reviewed.