在实际前端项目中LLM 并不总是需要部署在 GPU 服务器上。当需求变成“在浏览器里直接运行一个模型”时真正要解决的核心问题就变成了三件事浏览器有没有可用的 GPU 计算能力、模型能不能在当前设备上跑得动、整个推理过程能不能被一套稳定的工程链路兜住。WebGPU 的逐渐普及让这种端侧方案从一个“未来特性”变成了可以实际验证的技术方向。这篇文章会围绕 Running an LLM in the Browser 这条主线先说明为什么选择 WebGPU再给出从 WebGPU 环境验证、框架选型到本地推理的完整示例并整理实际落地时最容易踩的坑。1. 浏览器端跑 LLM这不是猎奇而是隐私与成本问题的答案1.1 为什么要把 LLM 放进浏览器传统使用 LLM 的方式是把请求发送到服务端模型在 GPU 服务器上推理再把结果返回给前端。这种架构成熟、稳定但有两个典型问题一是用户上传的文档、聊天内容会离开本地设备隐私敏感场景难以接受二是 GPU 服务器成本高按 Token 计费低频但需要长期在线的功能很容易浪费资源。把 LLM 放到浏览器本地推理核心收益有四个数据不出设备隐私边界清晰。不需要为推理预留服务器前端天然零部署。模型下载完成后可以离线使用不依赖服务端可用性。对个人工具和小团队项目来说省去了 GPU 资源的管理成本。但代价同样明显。浏览器能拿到的计算资源受限于当前设备可运行的模型规模通常只能覆盖 0.5B 到 8B 量级生成速度也远达不到高端 GPU 服务器的水平。因此“在浏览器里跑 LLM”并不是替代服务端推理而是解决一类特定问题的方案数据敏感、请求量不大、模型规模可控、用户愿意接受端侧速度。1.2 四条技术路线WebGL、WebGPU、WASM 与远程 API浏览器推理的技术路线选择决定了模型能跑多大、能跑多快、能支持哪些算子。下面这张表可以直接用于选型对比。路线核心能力适合场景主要限制WebGL浏览器最普及的 GPU 接口主要面向图形渲染部分老代码、简单图像类模型推理通用计算能力弱矩阵运算效率低LLM 容易出现算子缺失WebGPU新一代浏览器 GPU 接口支持 Compute Shader 通用计算中等规模 LLM、扩散模型、图像/视频推理需要新版浏览器部分设备驱动不完整WASMCPU 上执行跨平台兼容性好没有 GPU 时的兜底方案、小模型推理无法充分利用 GPULLM 生成速度通常不够理想远程 API调用服务端模型接口对隐私要求不高、需要大模型的场景不是本地推理依赖网络与服务器成本在 LLM 推理这个具体场景里WebGPU 是当前最值得优先验证的路线。它把 GPU 的通用计算能力暴露给浏览器框架层可以在 GPU 上执行大矩阵乘法、注意力计算和量化算子这正是 Transformer 模型推理最核心的计算负载。1.3 三个常用浏览器推理框架浏览器端推理框架已经不算稀少但要能实际加载 LLM 并运行文本生成需要关注三个方向WebLLMMLC LLM 的浏览器版本专门针对 LLM 做了编译和算子优化支持 WebGPU、异步加载、多种量化格式。做 LLM 本地推理时最直接。Transformers.jsHugging Face 生态在浏览器端的移植覆盖的任务类型更广可以用比较接近 Transformers 的 API 加载模型也提供 WebGPU 支持。ONNX Runtime Web把 ONNX 模型导入浏览器执行有 WebAssembly 和 WebGPU 后端适合已有 ONNX 模型、需要多框架兼容的项目。从“先跑通一个 LLM”的目标来看WebLLM 的集成路径最短。它把权重下载、量化、GPU buffer 分配、Token 解码这些细节封装在引擎层开发者只需要关注模型 ID、加载进度和生成参数。2. WebGPU 到底解决了什么问题才会成为本地 LLM 的关键2.1 WebGPU 的通俗定位WebGPU 是浏览器提供的现代 GPU 接口类似桌面图形 API 的 Web 版本。它允许 JavaScript 代码创建 GPU 管线、分配 GPU 显存、提交计算任务并读取结果。和 WebGL 最大的不同在于WebGPU 支持 Compute Shader也就是通用计算。换个更通俗的说法WebGPU 让浏览器里的 JavaScript 第一次可以把“矩阵乘法”这种计算密集型任务真正交给 GPU 并行执行。之前 WebGL 也能做类似的事但要把计算伪装成像素着色既绕路又脆弱。2.2 从矩阵乘法看 LLM 为什么需要 GPULLM 推理过程的核心可以简化成反复执行大量矩阵乘法。输入向量与权重矩阵相乘Gate 矩阵与 Up 矩阵相乘注意力机制的 Q 与 K、注意力分数与 V 相乘每一层都在重复这个模式。单个矩阵乘法在 CPU 上也能算但 LLM 推理需要连续执行上百甚至上千层而且每一步都要处理大量参数。例如一个 1.5B 参数的模型即使使用 4bit 量化也有大约 0.75GB 的权重需要反复读取并参与计算。GPU 的优势在于大规模并行一个 4096 乘 4096 的矩阵乘法在 GPU 上可以被拆分成成千上万个并行计算单元同时执行这正是浏览器推理框架愿意选择 WebGPU 的根本原因。2.3 WebGPU 在推理框架中的实际作用以 WebLLM 这类框架为例WebGPU 承担了四件事把量化后的模型权重上传到 GPU 显存。为每个模型算子创建 Compute Shader 管线并在推理时调度执行。在推理过程中分配和管理中间 buffer包括 KV Cache。把最终 logits 回传到 CPU再由 JavaScript 完成采样和 Token 解码。看到这里可以明白一个判断标准如果浏览器不支持 WebGPU或者设备没有可用的 GPU就不要指望 LLM 推理速度能让人满意。WASM 兜底可以保证“能跑”但体验往往只适合 0.5B 以下的小模型。注意WebGPU 支持并不等于 WebGPU 可用。浏览器版本、操作系统、显卡驱动、浏览器开关都可能影响最终结果验证时不能只看 HTTP 层面是否加载成功。3. 三步验证当前设备是否具备 WebGPU 推理条件3.1 先明确验证目标在动手写推理代码之前必须先验证三件事浏览器是否支持 WebGPU API。设备是否提供了可用的 GPU Adapter。当前设备上的 Adapter 能力是否满足模型推理要求。排查顺序建议先稳后快先确认 API 存在再请求 Adapter再检查 feature 和 limits。不要一上来就加载 2B 模型那样无法判断问题到底出在浏览器、驱动、网络还是显存。3.2 检查浏览器基础状态不同浏览器的 WebGPU 支持状态有明显差异而且这些状态会随版本更新而变化。团队立项时应统一一个最小浏览器版本基线而不是直接信任某一次测试结果。浏览器状态开发建议Chrome / Edge较新版本默认开启 WebGPU支持较完整优先使用作为开发主验证环境Safari已支持 WebGPU但能力集与 Chrome 存在差异做兼容性验证注意 feature 差异Firefox实验阶段需要手动开启相关标志不建议作为主环境可作为兜底观察3.3 一行代码确认 API 是否存在最简单的验证是判断navigator.gpu是否存在。如果这个对象不存在说明浏览器内核没有开启 WebGPU后续所有 WebGPU 推理代码都无法运行。if (navigator.gpu) { console.log(WebGPU API is supported); } else { console.error(WebGPU API is not supported in this browser); }这段代码的关键点在于navigator.gpu存在只代表 API 已暴露不代表 GPU 一定可用。某些安全模式下API 存在但requestAdapter会返回null。3.4 获取 GPU Adapter 并检查能力接下来请求 Adapter并读取设备能力信息。这是判断能否实际运行 LLM 的最重要一步。async function checkWebGPU() { if (!navigator.gpu) { return { supported: false, reason: WebGPU API not found }; } const adapter await navigator.gpu.requestAdapter(); if (!adapter) { return { supported: false, reason: No GPU adapter available }; } const device await adapter.requestDevice(); const info { supported: true, adapterInfo: adapter.info ? { vendor: adapter.info.vendor, architecture: adapter.info.architecture, device: adapter.info.device, } : adapter.info not exposed, features: Array.from(adapter.features), maxBufferSize: adapter.limits.maxBufferSize, maxComputeWorkgroupStorageSize: adapter.limits.maxComputeWorkgroupStorageSize, }; console.log(WebGPU adapter info:, info); // 检查对半精度浮点数的支持LLM 常用 f16 量化 const shaderF16 adapter.features.has(shader-f16); console.warn(shader-f16:, shaderF16 ? supported : not supported); device.destroy(); return info; } checkWebGPU().then((result) { console.log(Check result:, result); });这段代码对实际项目有三个作用第一确认requestAdapter没有返回null第二把 Adapter 的厂商、架构和 feature 列表打印出来方便后续对照模型要求第三检查shader-f16特性因为不少 WebGPU 推理路线依赖半精度浮点支持。3.5 能力检查页面的可复用结构在团队项目中建议把能力检查封装成一个独立函数页面启动后先执行检查再决定进入 GPU 推理、WASM 兜底还是提示升级浏览器。这样能避免用户在白屏页面等待很久才发现模型加载不了。export async function getRuntimeStatus() { if (!navigator.gpu) { return { mode: fallback-wasm, reason: webgpu-missing }; } const adapter await navigator.gpu.requestAdapter(); if (!adapter) { return { mode: fallback-wasm, reason: adapter-unavailable }; } return { mode: webgpu, reason: ok }; }这一步通过后再进入框架选型和模型加载。不要跳过检查因为在部分远程桌面、虚拟机或老驱动环境中WebGPU API 存在但计算能力并不足以运行大模型。4. 最小可运行示例用 WebLLM 完成一次本地推理4.1 为什么用 WebLLM 做示例选择 WebLLM 的原因有三个它原生支持 WebGPU 后端它针对 LLM 推理做了编译优化不需要开发者手写算子它的 API 封装程度高适合在浏览器端快速验证完整链路。下面的示例会完成一个最小闭环加载模型 - 输入一段文字 - 得到模型回复。4.2 项目结构与依赖引入创建一个最简单的静态页面目录webgpu-llm-demo/ ├── index.html └── app.js由于现代浏览器推理普遍使用 ES Module可以通过 Import Map 在浏览器中直接引入依赖。示例中使用 CDN 引入 WebLLM实际项目可以改为构建工具打包并用本地静态资源部署。!DOCTYPE html html langzh-CN head meta charsetUTF-8 / meta nameviewport contentwidthdevice-width, initial-scale1.0 / titleBrowser LLM Demo/title style body { font-family: system-ui, sans-serif; margin: 2rem; } #status { margin-bottom: 1rem; color: #333; } #output { white-space: pre-wrap; border: 1px solid #ddd; padding: 1rem; min-height: 8rem; } /style /head body h1Local LLM with WebGPU/h1 pre idstatusinitializing.../pre div idoutput/div script typeimportmap { imports: { mlc-ai/web-llm: https://cdn.jsdelivr.net/npm/mlc-ai/web-llm0.2.79/esm } } /script script typemodule src./app.js/script /body /html这里要注意不同版本的 WebLLM API 命名有差异例如导出名可能是CreateMLCEngine也可能是createMLCEngine。使用 CDN 时建议锁定版本号并去对应版本的 README 或 TypeScript 声明中确认 API 名称。4.3 初始化引擎并执行生成编写app.js实现模型加载、进度反馈和文本生成。import { CreateMLCEngine } from mlc-ai/web-llm; const statusEl document.getElementById(status); const outputEl document.getElementById(output); // 模型 ID 需要根据当前 WebLLM 支持的模型列表确认 const MODEL_ID Qwen2.5-1.5B-Instruct-q4f16_1-MLC; const engine await CreateMLCEngine(MODEL_ID, { initProgressCallback: (progress) { const text progress.text || ; statusEl.textContent Loading model: ${text}; }, }); statusEl.textContent Model ready; const messages [ { role: user, content: 用三句话介绍 WebGPU 对浏览器端推理的意义。 }, ]; const reply await engine.chat.completions.create({ messages, temperature: 0.7, max_tokens: 256, }); outputEl.textContent reply.choices[0].message.content;这段代码的核心是CreateMLCEngine(MODEL_ID)。框架会执行这样一组动作检查 WebGPU 可用性。从模型托管地址下载权重。在 GPU 上初始化推理引擎。把 quantized 模型权重加载到显存。生成时chat.completions.create的调用方式和 OpenAI 协议类似因此前端团队迁移成本较低。4.4 增加错误处理避免页面静默失败浏览器推理链路比服务端多很多变量模型下载失败、GPU 显存不足、量化文件缺失都可能发生。示例至少要捕获初始化阶段错误并输出到页面。try { const engine await CreateMLCEngine(MODEL_ID, { initProgressCallback: (progress) { statusEl.textContent Loading model: ${progress.text || }; }, }); statusEl.textContent Model ready; const reply await engine.chat.completions.create({ messages: [{ role: user, content: 你好请介绍一下你自己。 }], max_tokens: 128, }); outputEl.textContent reply.choices[0].message.content; } catch (err) { statusEl.textContent Failed; outputEl.textContent err?.message || String(err); }这里需要重点提示模型权重默认可能从外部 CDN 下载。如果用户网络无法访问该域名模型加载会失败。生产环境必须把权重文件部署到自己可控的静态服务器并在代码中指定模型 URL。4.5 Transformers.js 作为备选路线如果团队已经重度使用 Hugging Face 生态可以参考 Transformers.js 的方式。它能用更通用的 API 跑文本生成但不同模型的 WebGPU 算子覆盖和性能表现差异很大原型验证时不要假设所有模型都能在 WebGPU 下正常推理。import { pipeline } from huggingface/transformers; const generator await pipeline(text-generation, onnx-community/Qwen2.5-0.5B-Instruct, { device: webgpu, dtype: q4f16, }); const result await generator(Hello, what is WebGPU?, { max_new_tokens: 64, });如果 WebGPU 路径不稳定可以先把device改成wasm确认模型与业务逻辑没有其他问题再回到 WebGPU 上优化性能。这种先跑通、再加速的思路能显著降低排查复杂度。5. 关键参数与量化调整把选型和调优讲清楚5.1 device 参数决定计算后端以 Transformers.js 之类的框架为例device参数的可选值直接影响模型加载路径和执行速度。device计算位置优点缺点cpuCPU 上通过 JS 执行兼容性最好速度最慢只适合极小模型wasmCPU 上通过 WebAssembly 执行比纯 JS 稳定跨浏览器一致无法利用 GPU 并行能力webgpuGPU 上执行推理速度最快支持较大模型对浏览器和驱动有要求在 WebLLM 中WebGPU 是主路径接入时只需要确保初始化前已经完成 WebGPU 验证即可。不要把device参数直接暴露给最终用户应该由项目根据能力检查结果自动选择。5.2 量化精度决定了模型体积与速度量化是浏览器端 LLM 能否跑通的关键。模型权重从 fp16 压缩到 int4 后体积减少到原来的四分之一左右传输时间、显存占用和带宽压力都会明显下降代价是生成质量可能略有下降。量化格式含义适用场景注意事项q4f164bit 量化权重计算时转为 f16浏览器端最常见选择平衡体积与质量需要 GPU 支持 f16 运算q8f168bit 量化权重计算时转为 f16质量敏感、设备内存充足时体积比 q4 大加载更慢fp16半精度权重强 GPU 设备追求更高精度模型体积大容易爆显存fp32全精度权重桌面端测试对比不建议浏览器端使用体积非常大估算模型体积时有这样一个简化公式模型权重大致等于参数数量乘每参数的比特数再除以 8。例如 1.5B 参数模型使用 4bit 量化权重约 0.75GB实际运行时再加上 KV Cache 和临时 buffer内存占用通常会超过 1GB。5.3 生成参数如何影响内存与速度max_tokens、max_new_tokens和上下文长度会直接影响 KV Cache 占用。不要把生成上限设置得比模型实际支持范围更大否则要么报错要么推理到后面内存紧张。实际项目里推荐这样处理把用户可见的生成长度限制在 256 到 512 Token 以内。上下文窗口值根据设备和模型量化确定不要盲目拉满。temperature只影响采样随机性不影响模型加载和显存占用。5.4 模型缓存与资源托管浏览器端推理有一个容易被忽略的问题模型权重会重复下载。首次加载 1B 模型的量化权重可能需要下载数百 MB 文件如果每次刷新都重新下载体验会非常差。合理的做法是使用支持 Cache API 的加载链路让浏览器缓存模型分片。在生产环境把模型权重放到与业务应用同域的静态资源服务器并配置正确的 CORS 响应头。使用版本化模型目录避免缓存污染。不要依赖默认 CDN 上的模型地址长期不变。模型文件更新、CDN 策略调整、网络隔离策略变化都可能让生产环境突然加载失败。注意模型文件可能很大开发阶段建议先用 0.5B 到 1.5B 的小模型验证链路确认业务逻辑没问题后再切换到更大的模型。6. 运行验证确认推理真的用上了 GPU6.1 从浏览器内部确认 GPU 是否参与计算代码能跑通只是第一步。判断 WebGPU 推理链路是否真正生效需要从浏览器工具中确认。在 Chrome 中打开chrome://gpu页面可以查看 WebGPU 状态和图形设备信息确认独立显卡或集成显卡是否被浏览器识别。另一个更直接的方法是看推理过程的性能表现同一个模型在 WebGPU 路径和 WASM 路径下的生成速度差异会非常明显如果 WebGPU 路径没有明显更快很可能是没有真正用到 GPU或者框架落回了 CPU 执行。6.2 用计时函数验证生成速度不要用“看起来快不快”来判断性能建议用代码记录关键时间点。const startTime performance.now(); const reply await engine.chat.completions.create({ messages: [{ role: user, content: Hello! }], max_tokens: 64, }); const endTime performance.now(); const elapsedSec (endTime - startTime) / 1000; const usage reply.usage; const tokensPerSecond usage usage.completion_tokens ? usage.completion_tokens / elapsedSec : 0; console.log(Time: ${elapsedSec.toFixed(2)}s); console.log(Tokens/s: ${tokensPerSecond.toFixed(2)});这个测试要反复多次第一次生成包含权重初始化等固定开销后面的生成更能反映稳定速度。记录时也要关注首 Token 耗时和整体耗时不要只用一个平均值掩盖冷启动问题。6.3 学习环境与生产环境的验证差异验证项学习环境生产环境浏览器版本使用当前最新版本即可固定版本基线并测试次新版本设备类型开发者本机独立显卡覆盖集显、独显、低内存设备模型权重直接使用示例模型 ID部署到自建静态服务器网络异常重试一次即可需要断网、弱网、域名隔离测试性能指标关注能否生成文字关注首 Token 延迟、Tokens/s、内存占用监控无需要采集初始化成功率、推理失败率、平均耗时学习环境跑通后至少要再做一次“禁用 WebGPU”的降级测试确保用户没有 GPU 时不会白屏。7. 常见报错与排查链路7.1 先看这张排查总表问题现象常见原因检查方式处理建议navigator.gpu为 undefined浏览器版本过旧或 WebGPU 未开启查看浏览器版本打开chrome://gpu升级浏览器或使用支持 WebGPU 的稳定版本requestAdapter()返回 nullGPU 不可用、虚拟机环境或驱动问题在另一台设备测试查看chrome://gpu降级到 WASM 路径提示用户设备不满足要求模型加载很久不完成权重文件太大、网络慢或 CDN 不通查看 Network 面板关注模型分片请求自建模型托管提供加载进度和失败重试CORS 报错模型文件所在服务器不支持跨域访问查看浏览器控制台 CORS 错误配置正确的Access-Control-Allow-Origin页面在生成时崩溃显存或内存不足上下文设置过长使用任务管理器观察内存占用换更小模型、降低量化精度、减小上下文生成结果乱码模型 ID 与权重不匹配或采样参数异常检查模型 ID 是否属于同一系列重新确认模型权重文件和模型 ID 一致性速度远慢于预期框架落回了 WASM 或 CPU 路径检查初始化日志中的 device 信息修复 WebGPU 初始化条件或更换驱动7.2 navigator.gpu 为 undefined 或 requestAdapter 返回 null这是最常见的起步问题。如果页面运行在远程办公虚拟机、云桌面这类环境中浏览器可能无法访问物理 GPUrequestAdapter就会返回null。排查顺序是在 Chrome 中访问chrome://gpu查看 WebGPU 是否列出。换一台本机独立显卡设备对比。检查浏览器是否被公司安全策略禁用了 GPU 相关能力。解决方案不是让用户换电脑而是降级到 WASM 或直接展示提示页。7.3 模型加载失败与 CORS 问题模型加载失败时先看 Network 面板是 404、超时还是 CORS。404 意味着模型 ID 不存在或者 URL 拼写错误超时可能是指定的模型托管域名不可达CORS 则说明服务器没有允许当前站点跨域读取模型文件。生产环境必须提前把模型权重放在同源或已配置 CORS 的静态服务器上并在代码中通过模型 URL 配置项指定位置。不要等到上线后才发现用户无法访问默认模型源。7.4 页面崩溃与内存占用过高浏览器标签页的可用内存有限。大模型权重、KV Cache、中间计算 buffer 全部叠加后低端设备很容易崩溃。此时可以按优先级调整切换到更小的模型例如 0.5B。使用q4f16更低比特的量化。缩短上下文长度和max_tokens。在初始化前检查设备内存内存不足时提前降级。浏览器崩溃通常不会留下可交互的错误提示因此建议在页面内加入全局错误捕获把崩溃前的最后状态输出到日志服务。7.5 推理结果不符合预期推理能跑通但内容错乱、重复或乱码通常不是 WebGPU 的问题而是模型权重与模型 ID 不匹配或者生成参数设置不当。先固定temperature 0和较小上下文做对照测试再逐步调整采样参数。8. 发布前检查清单与扩展方向8.1 发布前检查清单下面的清单可以直接用于评审浏览器版本基线是否明确是否覆盖 Chrome、Edge、Safari。是否在页面启动时执行 WebGPU 能力检查并实现 WASM 降级。模型权重是否部署到自建静态服务器CORS 响应是否正确。首次加载是否有进度条失败是否有重试入口。是否限制生成长度避免用户一次请求过大导致崩溃。是否做过低内存设备测试。是否记录并上报初始化成功率、模型加载耗时、Tokens/s 等核心指标。是否明确隐私说明告知用户数据只在本地处理。是否考虑模型缓存策略避免重复下载大文件。是否准备好模型版本升级时的缓存清理方案。8.2 生产环境还需要补齐的工程能力浏览器端推理不等于零运维。模型文件版本需要管理权重分发需要 CDN 或多域名容灾客户端异常需要日志采集。除此之外还需要考虑回滚方案如果新模型量化后质量下降需要能快速切回上一版本。如果应用是面向公网用户的要特别控制可选模型数量。每次多提供一个模型就多一套下载和兼容性风险。优先只开放一个经过充分测试的模型组合再根据用户设备数据逐步放开。8.3 扩展方向与练习建议这条技术路线的下一步扩展方向很明确多模态模型在浏览器端同时处理图片和文本。服务端与端侧混合路由根据设备能力自动选择本地推理或服务端推理。端侧定制把公司内部知识库压缩成小型模型或使用检索增强方式在浏览器内提供私域问答。离线 PWA 化结合 Service Worker 把模型权重和页面资源一起缓存实现真正离线使用。对刚接触这个方向的开发者建议按顺序完成三个练习第一步用能力检查脚本输出本机 WebGPU 信息第二步用 0.5B 量化模型跑通一次对话生成第三步把模型权重切换到自建服务器并加入失败降级路径。三步做完基本就掌握了浏览器端 LLM 推理从环境验证到工程落地的完整链路。浏览器端本地推理仍然受限于设备算力但它让“隐私敏感的 AI 功能直接运行在用户设备上”这件事变得可落地。真正重要的是把能力检查、模型选型、降级策略和性能监控当成一套工程系统来建设而不是只关心模型能不能出文字。
浏览器端运行LLM：WebGPU环境验证与WebLLM推理实战
在实际前端项目中LLM 并不总是需要部署在 GPU 服务器上。当需求变成“在浏览器里直接运行一个模型”时真正要解决的核心问题就变成了三件事浏览器有没有可用的 GPU 计算能力、模型能不能在当前设备上跑得动、整个推理过程能不能被一套稳定的工程链路兜住。WebGPU 的逐渐普及让这种端侧方案从一个“未来特性”变成了可以实际验证的技术方向。这篇文章会围绕 Running an LLM in the Browser 这条主线先说明为什么选择 WebGPU再给出从 WebGPU 环境验证、框架选型到本地推理的完整示例并整理实际落地时最容易踩的坑。1. 浏览器端跑 LLM这不是猎奇而是隐私与成本问题的答案1.1 为什么要把 LLM 放进浏览器传统使用 LLM 的方式是把请求发送到服务端模型在 GPU 服务器上推理再把结果返回给前端。这种架构成熟、稳定但有两个典型问题一是用户上传的文档、聊天内容会离开本地设备隐私敏感场景难以接受二是 GPU 服务器成本高按 Token 计费低频但需要长期在线的功能很容易浪费资源。把 LLM 放到浏览器本地推理核心收益有四个数据不出设备隐私边界清晰。不需要为推理预留服务器前端天然零部署。模型下载完成后可以离线使用不依赖服务端可用性。对个人工具和小团队项目来说省去了 GPU 资源的管理成本。但代价同样明显。浏览器能拿到的计算资源受限于当前设备可运行的模型规模通常只能覆盖 0.5B 到 8B 量级生成速度也远达不到高端 GPU 服务器的水平。因此“在浏览器里跑 LLM”并不是替代服务端推理而是解决一类特定问题的方案数据敏感、请求量不大、模型规模可控、用户愿意接受端侧速度。1.2 四条技术路线WebGL、WebGPU、WASM 与远程 API浏览器推理的技术路线选择决定了模型能跑多大、能跑多快、能支持哪些算子。下面这张表可以直接用于选型对比。路线核心能力适合场景主要限制WebGL浏览器最普及的 GPU 接口主要面向图形渲染部分老代码、简单图像类模型推理通用计算能力弱矩阵运算效率低LLM 容易出现算子缺失WebGPU新一代浏览器 GPU 接口支持 Compute Shader 通用计算中等规模 LLM、扩散模型、图像/视频推理需要新版浏览器部分设备驱动不完整WASMCPU 上执行跨平台兼容性好没有 GPU 时的兜底方案、小模型推理无法充分利用 GPULLM 生成速度通常不够理想远程 API调用服务端模型接口对隐私要求不高、需要大模型的场景不是本地推理依赖网络与服务器成本在 LLM 推理这个具体场景里WebGPU 是当前最值得优先验证的路线。它把 GPU 的通用计算能力暴露给浏览器框架层可以在 GPU 上执行大矩阵乘法、注意力计算和量化算子这正是 Transformer 模型推理最核心的计算负载。1.3 三个常用浏览器推理框架浏览器端推理框架已经不算稀少但要能实际加载 LLM 并运行文本生成需要关注三个方向WebLLMMLC LLM 的浏览器版本专门针对 LLM 做了编译和算子优化支持 WebGPU、异步加载、多种量化格式。做 LLM 本地推理时最直接。Transformers.jsHugging Face 生态在浏览器端的移植覆盖的任务类型更广可以用比较接近 Transformers 的 API 加载模型也提供 WebGPU 支持。ONNX Runtime Web把 ONNX 模型导入浏览器执行有 WebAssembly 和 WebGPU 后端适合已有 ONNX 模型、需要多框架兼容的项目。从“先跑通一个 LLM”的目标来看WebLLM 的集成路径最短。它把权重下载、量化、GPU buffer 分配、Token 解码这些细节封装在引擎层开发者只需要关注模型 ID、加载进度和生成参数。2. WebGPU 到底解决了什么问题才会成为本地 LLM 的关键2.1 WebGPU 的通俗定位WebGPU 是浏览器提供的现代 GPU 接口类似桌面图形 API 的 Web 版本。它允许 JavaScript 代码创建 GPU 管线、分配 GPU 显存、提交计算任务并读取结果。和 WebGL 最大的不同在于WebGPU 支持 Compute Shader也就是通用计算。换个更通俗的说法WebGPU 让浏览器里的 JavaScript 第一次可以把“矩阵乘法”这种计算密集型任务真正交给 GPU 并行执行。之前 WebGL 也能做类似的事但要把计算伪装成像素着色既绕路又脆弱。2.2 从矩阵乘法看 LLM 为什么需要 GPULLM 推理过程的核心可以简化成反复执行大量矩阵乘法。输入向量与权重矩阵相乘Gate 矩阵与 Up 矩阵相乘注意力机制的 Q 与 K、注意力分数与 V 相乘每一层都在重复这个模式。单个矩阵乘法在 CPU 上也能算但 LLM 推理需要连续执行上百甚至上千层而且每一步都要处理大量参数。例如一个 1.5B 参数的模型即使使用 4bit 量化也有大约 0.75GB 的权重需要反复读取并参与计算。GPU 的优势在于大规模并行一个 4096 乘 4096 的矩阵乘法在 GPU 上可以被拆分成成千上万个并行计算单元同时执行这正是浏览器推理框架愿意选择 WebGPU 的根本原因。2.3 WebGPU 在推理框架中的实际作用以 WebLLM 这类框架为例WebGPU 承担了四件事把量化后的模型权重上传到 GPU 显存。为每个模型算子创建 Compute Shader 管线并在推理时调度执行。在推理过程中分配和管理中间 buffer包括 KV Cache。把最终 logits 回传到 CPU再由 JavaScript 完成采样和 Token 解码。看到这里可以明白一个判断标准如果浏览器不支持 WebGPU或者设备没有可用的 GPU就不要指望 LLM 推理速度能让人满意。WASM 兜底可以保证“能跑”但体验往往只适合 0.5B 以下的小模型。注意WebGPU 支持并不等于 WebGPU 可用。浏览器版本、操作系统、显卡驱动、浏览器开关都可能影响最终结果验证时不能只看 HTTP 层面是否加载成功。3. 三步验证当前设备是否具备 WebGPU 推理条件3.1 先明确验证目标在动手写推理代码之前必须先验证三件事浏览器是否支持 WebGPU API。设备是否提供了可用的 GPU Adapter。当前设备上的 Adapter 能力是否满足模型推理要求。排查顺序建议先稳后快先确认 API 存在再请求 Adapter再检查 feature 和 limits。不要一上来就加载 2B 模型那样无法判断问题到底出在浏览器、驱动、网络还是显存。3.2 检查浏览器基础状态不同浏览器的 WebGPU 支持状态有明显差异而且这些状态会随版本更新而变化。团队立项时应统一一个最小浏览器版本基线而不是直接信任某一次测试结果。浏览器状态开发建议Chrome / Edge较新版本默认开启 WebGPU支持较完整优先使用作为开发主验证环境Safari已支持 WebGPU但能力集与 Chrome 存在差异做兼容性验证注意 feature 差异Firefox实验阶段需要手动开启相关标志不建议作为主环境可作为兜底观察3.3 一行代码确认 API 是否存在最简单的验证是判断navigator.gpu是否存在。如果这个对象不存在说明浏览器内核没有开启 WebGPU后续所有 WebGPU 推理代码都无法运行。if (navigator.gpu) { console.log(WebGPU API is supported); } else { console.error(WebGPU API is not supported in this browser); }这段代码的关键点在于navigator.gpu存在只代表 API 已暴露不代表 GPU 一定可用。某些安全模式下API 存在但requestAdapter会返回null。3.4 获取 GPU Adapter 并检查能力接下来请求 Adapter并读取设备能力信息。这是判断能否实际运行 LLM 的最重要一步。async function checkWebGPU() { if (!navigator.gpu) { return { supported: false, reason: WebGPU API not found }; } const adapter await navigator.gpu.requestAdapter(); if (!adapter) { return { supported: false, reason: No GPU adapter available }; } const device await adapter.requestDevice(); const info { supported: true, adapterInfo: adapter.info ? { vendor: adapter.info.vendor, architecture: adapter.info.architecture, device: adapter.info.device, } : adapter.info not exposed, features: Array.from(adapter.features), maxBufferSize: adapter.limits.maxBufferSize, maxComputeWorkgroupStorageSize: adapter.limits.maxComputeWorkgroupStorageSize, }; console.log(WebGPU adapter info:, info); // 检查对半精度浮点数的支持LLM 常用 f16 量化 const shaderF16 adapter.features.has(shader-f16); console.warn(shader-f16:, shaderF16 ? supported : not supported); device.destroy(); return info; } checkWebGPU().then((result) { console.log(Check result:, result); });这段代码对实际项目有三个作用第一确认requestAdapter没有返回null第二把 Adapter 的厂商、架构和 feature 列表打印出来方便后续对照模型要求第三检查shader-f16特性因为不少 WebGPU 推理路线依赖半精度浮点支持。3.5 能力检查页面的可复用结构在团队项目中建议把能力检查封装成一个独立函数页面启动后先执行检查再决定进入 GPU 推理、WASM 兜底还是提示升级浏览器。这样能避免用户在白屏页面等待很久才发现模型加载不了。export async function getRuntimeStatus() { if (!navigator.gpu) { return { mode: fallback-wasm, reason: webgpu-missing }; } const adapter await navigator.gpu.requestAdapter(); if (!adapter) { return { mode: fallback-wasm, reason: adapter-unavailable }; } return { mode: webgpu, reason: ok }; }这一步通过后再进入框架选型和模型加载。不要跳过检查因为在部分远程桌面、虚拟机或老驱动环境中WebGPU API 存在但计算能力并不足以运行大模型。4. 最小可运行示例用 WebLLM 完成一次本地推理4.1 为什么用 WebLLM 做示例选择 WebLLM 的原因有三个它原生支持 WebGPU 后端它针对 LLM 推理做了编译优化不需要开发者手写算子它的 API 封装程度高适合在浏览器端快速验证完整链路。下面的示例会完成一个最小闭环加载模型 - 输入一段文字 - 得到模型回复。4.2 项目结构与依赖引入创建一个最简单的静态页面目录webgpu-llm-demo/ ├── index.html └── app.js由于现代浏览器推理普遍使用 ES Module可以通过 Import Map 在浏览器中直接引入依赖。示例中使用 CDN 引入 WebLLM实际项目可以改为构建工具打包并用本地静态资源部署。!DOCTYPE html html langzh-CN head meta charsetUTF-8 / meta nameviewport contentwidthdevice-width, initial-scale1.0 / titleBrowser LLM Demo/title style body { font-family: system-ui, sans-serif; margin: 2rem; } #status { margin-bottom: 1rem; color: #333; } #output { white-space: pre-wrap; border: 1px solid #ddd; padding: 1rem; min-height: 8rem; } /style /head body h1Local LLM with WebGPU/h1 pre idstatusinitializing.../pre div idoutput/div script typeimportmap { imports: { mlc-ai/web-llm: https://cdn.jsdelivr.net/npm/mlc-ai/web-llm0.2.79/esm } } /script script typemodule src./app.js/script /body /html这里要注意不同版本的 WebLLM API 命名有差异例如导出名可能是CreateMLCEngine也可能是createMLCEngine。使用 CDN 时建议锁定版本号并去对应版本的 README 或 TypeScript 声明中确认 API 名称。4.3 初始化引擎并执行生成编写app.js实现模型加载、进度反馈和文本生成。import { CreateMLCEngine } from mlc-ai/web-llm; const statusEl document.getElementById(status); const outputEl document.getElementById(output); // 模型 ID 需要根据当前 WebLLM 支持的模型列表确认 const MODEL_ID Qwen2.5-1.5B-Instruct-q4f16_1-MLC; const engine await CreateMLCEngine(MODEL_ID, { initProgressCallback: (progress) { const text progress.text || ; statusEl.textContent Loading model: ${text}; }, }); statusEl.textContent Model ready; const messages [ { role: user, content: 用三句话介绍 WebGPU 对浏览器端推理的意义。 }, ]; const reply await engine.chat.completions.create({ messages, temperature: 0.7, max_tokens: 256, }); outputEl.textContent reply.choices[0].message.content;这段代码的核心是CreateMLCEngine(MODEL_ID)。框架会执行这样一组动作检查 WebGPU 可用性。从模型托管地址下载权重。在 GPU 上初始化推理引擎。把 quantized 模型权重加载到显存。生成时chat.completions.create的调用方式和 OpenAI 协议类似因此前端团队迁移成本较低。4.4 增加错误处理避免页面静默失败浏览器推理链路比服务端多很多变量模型下载失败、GPU 显存不足、量化文件缺失都可能发生。示例至少要捕获初始化阶段错误并输出到页面。try { const engine await CreateMLCEngine(MODEL_ID, { initProgressCallback: (progress) { statusEl.textContent Loading model: ${progress.text || }; }, }); statusEl.textContent Model ready; const reply await engine.chat.completions.create({ messages: [{ role: user, content: 你好请介绍一下你自己。 }], max_tokens: 128, }); outputEl.textContent reply.choices[0].message.content; } catch (err) { statusEl.textContent Failed; outputEl.textContent err?.message || String(err); }这里需要重点提示模型权重默认可能从外部 CDN 下载。如果用户网络无法访问该域名模型加载会失败。生产环境必须把权重文件部署到自己可控的静态服务器并在代码中指定模型 URL。4.5 Transformers.js 作为备选路线如果团队已经重度使用 Hugging Face 生态可以参考 Transformers.js 的方式。它能用更通用的 API 跑文本生成但不同模型的 WebGPU 算子覆盖和性能表现差异很大原型验证时不要假设所有模型都能在 WebGPU 下正常推理。import { pipeline } from huggingface/transformers; const generator await pipeline(text-generation, onnx-community/Qwen2.5-0.5B-Instruct, { device: webgpu, dtype: q4f16, }); const result await generator(Hello, what is WebGPU?, { max_new_tokens: 64, });如果 WebGPU 路径不稳定可以先把device改成wasm确认模型与业务逻辑没有其他问题再回到 WebGPU 上优化性能。这种先跑通、再加速的思路能显著降低排查复杂度。5. 关键参数与量化调整把选型和调优讲清楚5.1 device 参数决定计算后端以 Transformers.js 之类的框架为例device参数的可选值直接影响模型加载路径和执行速度。device计算位置优点缺点cpuCPU 上通过 JS 执行兼容性最好速度最慢只适合极小模型wasmCPU 上通过 WebAssembly 执行比纯 JS 稳定跨浏览器一致无法利用 GPU 并行能力webgpuGPU 上执行推理速度最快支持较大模型对浏览器和驱动有要求在 WebLLM 中WebGPU 是主路径接入时只需要确保初始化前已经完成 WebGPU 验证即可。不要把device参数直接暴露给最终用户应该由项目根据能力检查结果自动选择。5.2 量化精度决定了模型体积与速度量化是浏览器端 LLM 能否跑通的关键。模型权重从 fp16 压缩到 int4 后体积减少到原来的四分之一左右传输时间、显存占用和带宽压力都会明显下降代价是生成质量可能略有下降。量化格式含义适用场景注意事项q4f164bit 量化权重计算时转为 f16浏览器端最常见选择平衡体积与质量需要 GPU 支持 f16 运算q8f168bit 量化权重计算时转为 f16质量敏感、设备内存充足时体积比 q4 大加载更慢fp16半精度权重强 GPU 设备追求更高精度模型体积大容易爆显存fp32全精度权重桌面端测试对比不建议浏览器端使用体积非常大估算模型体积时有这样一个简化公式模型权重大致等于参数数量乘每参数的比特数再除以 8。例如 1.5B 参数模型使用 4bit 量化权重约 0.75GB实际运行时再加上 KV Cache 和临时 buffer内存占用通常会超过 1GB。5.3 生成参数如何影响内存与速度max_tokens、max_new_tokens和上下文长度会直接影响 KV Cache 占用。不要把生成上限设置得比模型实际支持范围更大否则要么报错要么推理到后面内存紧张。实际项目里推荐这样处理把用户可见的生成长度限制在 256 到 512 Token 以内。上下文窗口值根据设备和模型量化确定不要盲目拉满。temperature只影响采样随机性不影响模型加载和显存占用。5.4 模型缓存与资源托管浏览器端推理有一个容易被忽略的问题模型权重会重复下载。首次加载 1B 模型的量化权重可能需要下载数百 MB 文件如果每次刷新都重新下载体验会非常差。合理的做法是使用支持 Cache API 的加载链路让浏览器缓存模型分片。在生产环境把模型权重放到与业务应用同域的静态资源服务器并配置正确的 CORS 响应头。使用版本化模型目录避免缓存污染。不要依赖默认 CDN 上的模型地址长期不变。模型文件更新、CDN 策略调整、网络隔离策略变化都可能让生产环境突然加载失败。注意模型文件可能很大开发阶段建议先用 0.5B 到 1.5B 的小模型验证链路确认业务逻辑没问题后再切换到更大的模型。6. 运行验证确认推理真的用上了 GPU6.1 从浏览器内部确认 GPU 是否参与计算代码能跑通只是第一步。判断 WebGPU 推理链路是否真正生效需要从浏览器工具中确认。在 Chrome 中打开chrome://gpu页面可以查看 WebGPU 状态和图形设备信息确认独立显卡或集成显卡是否被浏览器识别。另一个更直接的方法是看推理过程的性能表现同一个模型在 WebGPU 路径和 WASM 路径下的生成速度差异会非常明显如果 WebGPU 路径没有明显更快很可能是没有真正用到 GPU或者框架落回了 CPU 执行。6.2 用计时函数验证生成速度不要用“看起来快不快”来判断性能建议用代码记录关键时间点。const startTime performance.now(); const reply await engine.chat.completions.create({ messages: [{ role: user, content: Hello! }], max_tokens: 64, }); const endTime performance.now(); const elapsedSec (endTime - startTime) / 1000; const usage reply.usage; const tokensPerSecond usage usage.completion_tokens ? usage.completion_tokens / elapsedSec : 0; console.log(Time: ${elapsedSec.toFixed(2)}s); console.log(Tokens/s: ${tokensPerSecond.toFixed(2)});这个测试要反复多次第一次生成包含权重初始化等固定开销后面的生成更能反映稳定速度。记录时也要关注首 Token 耗时和整体耗时不要只用一个平均值掩盖冷启动问题。6.3 学习环境与生产环境的验证差异验证项学习环境生产环境浏览器版本使用当前最新版本即可固定版本基线并测试次新版本设备类型开发者本机独立显卡覆盖集显、独显、低内存设备模型权重直接使用示例模型 ID部署到自建静态服务器网络异常重试一次即可需要断网、弱网、域名隔离测试性能指标关注能否生成文字关注首 Token 延迟、Tokens/s、内存占用监控无需要采集初始化成功率、推理失败率、平均耗时学习环境跑通后至少要再做一次“禁用 WebGPU”的降级测试确保用户没有 GPU 时不会白屏。7. 常见报错与排查链路7.1 先看这张排查总表问题现象常见原因检查方式处理建议navigator.gpu为 undefined浏览器版本过旧或 WebGPU 未开启查看浏览器版本打开chrome://gpu升级浏览器或使用支持 WebGPU 的稳定版本requestAdapter()返回 nullGPU 不可用、虚拟机环境或驱动问题在另一台设备测试查看chrome://gpu降级到 WASM 路径提示用户设备不满足要求模型加载很久不完成权重文件太大、网络慢或 CDN 不通查看 Network 面板关注模型分片请求自建模型托管提供加载进度和失败重试CORS 报错模型文件所在服务器不支持跨域访问查看浏览器控制台 CORS 错误配置正确的Access-Control-Allow-Origin页面在生成时崩溃显存或内存不足上下文设置过长使用任务管理器观察内存占用换更小模型、降低量化精度、减小上下文生成结果乱码模型 ID 与权重不匹配或采样参数异常检查模型 ID 是否属于同一系列重新确认模型权重文件和模型 ID 一致性速度远慢于预期框架落回了 WASM 或 CPU 路径检查初始化日志中的 device 信息修复 WebGPU 初始化条件或更换驱动7.2 navigator.gpu 为 undefined 或 requestAdapter 返回 null这是最常见的起步问题。如果页面运行在远程办公虚拟机、云桌面这类环境中浏览器可能无法访问物理 GPUrequestAdapter就会返回null。排查顺序是在 Chrome 中访问chrome://gpu查看 WebGPU 是否列出。换一台本机独立显卡设备对比。检查浏览器是否被公司安全策略禁用了 GPU 相关能力。解决方案不是让用户换电脑而是降级到 WASM 或直接展示提示页。7.3 模型加载失败与 CORS 问题模型加载失败时先看 Network 面板是 404、超时还是 CORS。404 意味着模型 ID 不存在或者 URL 拼写错误超时可能是指定的模型托管域名不可达CORS 则说明服务器没有允许当前站点跨域读取模型文件。生产环境必须提前把模型权重放在同源或已配置 CORS 的静态服务器上并在代码中通过模型 URL 配置项指定位置。不要等到上线后才发现用户无法访问默认模型源。7.4 页面崩溃与内存占用过高浏览器标签页的可用内存有限。大模型权重、KV Cache、中间计算 buffer 全部叠加后低端设备很容易崩溃。此时可以按优先级调整切换到更小的模型例如 0.5B。使用q4f16更低比特的量化。缩短上下文长度和max_tokens。在初始化前检查设备内存内存不足时提前降级。浏览器崩溃通常不会留下可交互的错误提示因此建议在页面内加入全局错误捕获把崩溃前的最后状态输出到日志服务。7.5 推理结果不符合预期推理能跑通但内容错乱、重复或乱码通常不是 WebGPU 的问题而是模型权重与模型 ID 不匹配或者生成参数设置不当。先固定temperature 0和较小上下文做对照测试再逐步调整采样参数。8. 发布前检查清单与扩展方向8.1 发布前检查清单下面的清单可以直接用于评审浏览器版本基线是否明确是否覆盖 Chrome、Edge、Safari。是否在页面启动时执行 WebGPU 能力检查并实现 WASM 降级。模型权重是否部署到自建静态服务器CORS 响应是否正确。首次加载是否有进度条失败是否有重试入口。是否限制生成长度避免用户一次请求过大导致崩溃。是否做过低内存设备测试。是否记录并上报初始化成功率、模型加载耗时、Tokens/s 等核心指标。是否明确隐私说明告知用户数据只在本地处理。是否考虑模型缓存策略避免重复下载大文件。是否准备好模型版本升级时的缓存清理方案。8.2 生产环境还需要补齐的工程能力浏览器端推理不等于零运维。模型文件版本需要管理权重分发需要 CDN 或多域名容灾客户端异常需要日志采集。除此之外还需要考虑回滚方案如果新模型量化后质量下降需要能快速切回上一版本。如果应用是面向公网用户的要特别控制可选模型数量。每次多提供一个模型就多一套下载和兼容性风险。优先只开放一个经过充分测试的模型组合再根据用户设备数据逐步放开。8.3 扩展方向与练习建议这条技术路线的下一步扩展方向很明确多模态模型在浏览器端同时处理图片和文本。服务端与端侧混合路由根据设备能力自动选择本地推理或服务端推理。端侧定制把公司内部知识库压缩成小型模型或使用检索增强方式在浏览器内提供私域问答。离线 PWA 化结合 Service Worker 把模型权重和页面资源一起缓存实现真正离线使用。对刚接触这个方向的开发者建议按顺序完成三个练习第一步用能力检查脚本输出本机 WebGPU 信息第二步用 0.5B 量化模型跑通一次对话生成第三步把模型权重切换到自建服务器并加入失败降级路径。三步做完基本就掌握了浏览器端 LLM 推理从环境验证到工程落地的完整链路。浏览器端本地推理仍然受限于设备算力但它让“隐私敏感的 AI 功能直接运行在用户设备上”这件事变得可落地。真正重要的是把能力检查、模型选型、降级策略和性能监控当成一套工程系统来建设而不是只关心模型能不能出文字。
