最近帮同事解决一个前端工具的需求用户上传文档浏览器本地跑一个 LLM 做摘要不上传服务器。听起来不算复杂但他卡住的地方不是模型选型也不是提示词调优而是浏览器控制台里那一行冷冰冰的报错WebGPU is not available。这个现象很典型。很多人会把“浏览器跑 LLM”理解成“把模型文件丢进页面里”然后注意力全部放在量化、显存、推理速度上。但实际上整个方案成立的前提是先拿到一条浏览器访问 GPU 的通道。WebGPU 验证不是跑通之前的准备工作它本身就是方案的第一道门槛。没有它后面所有关于模型、量化、上下文的讨论都没有落点。这篇文章我想把“在浏览器里本地跑 LLM”这条链路拆开讲清楚核心线索是先验证 WebGPU再选模型然后跑通一条最小链路最后处理工程化和排查问题。为了不被各种花哨的 demo 带偏我会把适用边界也一起说清楚。1. 先想清楚浏览器本地推理到底解决什么问题1.1 一个常见误解浏览器跑 LLM 是为了替代服务器很多开发者第一次接触浏览器推理时会把它当成“本地替代云端 API”的方案觉得只要浏览器能跑模型就不需要后端了。这个判断至少在当前阶段是不太成立的。浏览器推理受 GPU 显存、浏览器内存、模型体积和 WebGPU 支持程度的限制能跑起来的模型规模和上下文窗口都远远小于服务器方案。把 7B 以上、长上下文的业务场景全部塞进浏览器既不现实也没有必要。服务器的价值在于算力规模、并发能力、模型更新速度和集中式运维这些在短时间内不会因为浏览器推理而消失。所以首先要建立的认知是浏览器本地推理不是要替代服务器推理它解决的是另一类问题。1.2 真正适合浏览器推理的场景从实际落地角度看浏览器本地推理更合适这几类需求隐私敏感的一次性处理比如本地文档摘要、简历分析、敏感数据整理。数据不出浏览器自然也就不存在服务器留存问题。零安装的边缘工具不需要用户装 Python、配 CUDA、下载模型文件打开网页就能用。对非技术用户尤其友好。弱网或内网环境在没有稳定外网访问的内部工具里云端 API 可能不可用本地推理反而更稳。离线演示和原型验证快速给团队或客户演示一个“模型在本地跑”的产品概念不需要申请服务器资源。这些场景有一个共同点单用户、低并发、任务可控。浏览器推理更适合“一个人对着自己的数据跑一个模型”而不是“十万人同时用一个模型”。1.3 浏览器推理的代价我建议所有想尝试的人在动手前先接受这些代价模型规模受限通常跑 0.5B 到 3B 级别的量化模型比较舒适更大模型容易把显存和内存吃满。首次加载要下载模型文件几十 MB 到几个 GB 不等网络成本并没有消失只是从“服务器下载”变成了“浏览器下载”。推理速度受 GPU 型号影响极大同一模型在不同机器上的体感差异可能是几倍。没有统一的后端日志和监控出了问题只能在浏览器控制台里看。模型更新很麻烦用户端如果缓存了旧文件你可能需要版本号或缓存策略来强制更新。一句话浏览器推理换来的是“数据不出端、部署零成本”代价是“能力边界更强、工程控制更弱”。它不是更高级的部署方式只是另一种权衡。2. 万事第一步验证 WebGPU 是否可用2.1 为什么 WebGPU 是关键门槛在浏览器里跑 LLM可选的底层执行路径大致有三条纯 JavaScript 计算、WebAssembly 计算、WebGPU 计算。纯 JS 和 WASM 都跑在 CPU 上能跑通但速度通常不够看。真正能让推理速度达到可用级别的是让模型的计算图跑在 GPU 上而目前浏览器里访问 GPU 的主要现代接口就是 WebGPU。这里不要把 WebGPU 和 WebGL 搞混。WebGL 是为图形渲染设计的虽然也能做一些通用计算但设计目标、计算模型和缓冲区能力都更适合渲染管线。LLM 推理涉及大量矩阵运算、张量内存分配和并行计算WebGPU 的 compute shader 模型更合适。另一个常见的误判是Chrome 支持 WebGPU所以所有环境都支持。实际上 WebGPU 要求浏览器本身支持并默认开启页面运行在安全上下文HTTPS 或 localhost里操作系统和 GPU 驱动能创建可用的图形/计算接口GPU 设备没有被浏览器列入 blocklist。所以验证 WebGPU 不是一次性的“环境检查”它直接决定了你的模型能不能在目标用户机器上跑起来。2.2 最小验证代码不要一上来就加载模型。先写一段最基础的 WebGPU 探测代码把环境信息打印出来。async function checkWebGPU() { if (!navigator.gpu) { return { supported: false, reason: navigator.gpu 不存在 }; } const adapter await navigator.gpu.requestAdapter(); if (!adapter) { return { supported: false, reason: requestAdapter 返回 null }; } try { const device await adapter.requestDevice(); if (!device) { return { supported: false, reason: requestDevice 失败 }; } const info adapter.info || {}; const limits adapter.limits || {}; return { supported: true, vendor: info.vendor, architecture: info.architecture, device: info.device, maxStorageBufferBindingSize: limits.maxStorageBufferBindingSize, maxBufferSize: limits.maxBufferSize }; } catch (err) { return { supported: false, reason: err.message }; } } const result await checkWebGPU(); console.log(result);这段代码的价值不只是告诉你“支不支持”而是帮你获得三样关键信息vendor和architecture用来判断用户是不是核显、是不是 Apple Silicon、是不是老架构。maxStorageBufferBindingSize这个值决定了模型权重能不能一次性绑定到 buffer 里。如果模型层参数超过该限制就需要拆分或换更小的模型。device.lost事件后续推理过程中如果 GPU 设备掉了你需要它来做恢复。建议把这段探测代码放在页面加载后立即执行并在 UI 上给用户一个明确的状态显示而不是等到模型加载失败才暴露问题。2.3 前置条件安全上下文、浏览器与系统如果navigator.gpu是 undefined先从下面几个维度排查页面是不是localhost或 HTTPS。http://192.168.x.x这种局域网地址在一些浏览器里不是安全上下文。浏览器是不是最新稳定版。Chrome 和 Edge 在桌面端默认支持 WebGPUSafari 在较新版本中可用Firefox 通常需要手动开启实验 flag。具体支持矩阵要结合你实际的目标用户浏览器来决定。系统层面是否禁用了硬件加速或者远程桌面、虚拟机环境里没有可用的 GPU。显卡驱动是否过旧。WebGPU 依赖系统图形接口驱动问题会导致 adapter 请求失败。2.4 拿到 adapter 之后还要看 limits很多教程只验证到requestAdapter()有返回值就结束了这是不够的。adapter.limits里有几个字段对 LLM 推理影响很大maxStorageBufferBindingSize一次 GPU 存储缓冲区能绑定的最大字节数。模型每层权重通常要放进 storage buffer如果限制过小模型加载或计算时会报 buffer 越界。maxBufferSize单个缓冲区最大字节数影响权重预分配策略。maxComputeWorkgroupStorageSize影响 kernel 内的共享内存使用。maxComputeInvocationsPerWorkgroup影响 kernel 设计。在真实项目里我一般会做一个“WebGPU 能力清单”把这几个字段和模型文件大小比对一下提前判断模型能不能跑而不是等用户点按钮之后才报错。注意WebGPU 探测通过只代表 GPU 通道可用不代表推理一定能成功。模型文件下载、内存分配、kernel 编译都可能在后面失败。3. 模型选型量化、参数量与上下文窗口的选择逻辑3.1 参数量不是唯一指标显存才是硬约束浏览器能跑多大模型最终由两个资源决定GPU 显存和浏览器可用的内存空间。模型权重占用的空间大约等于“参数量 × 每参数字节数”。以 7B 模型为例如果用 4 比特量化近似计算是7B × 0.5 字节 ≈ 3.5 GB这个体积对浏览器来说已经很重了。还要算上 KV Cache、中间激活和计算缓冲实际占用往往是权重的 1.2 到 1.5 倍。所以 7B 在浏览器里不是不能跑而是大多数用户机器跑起来会比较吃力。更稳妥的选择是 0.5B 到 3B 的量化模型。比如 3B 模型用 4 比特量化权重大约 1.5 GB 左右加上运行时开销在 8 GB 显存或大内存机器上体验会更可控。3.2 上下文窗口是隐形内存杀手很多人只关注参数量忽略了上下文长度对内存的线性影响。推理时 KV Cache 会随 token 数增长。上下文越长KV Cache 越大GPU 内存压力也越大。假设一个模型支持 4K 上下文但你只给它 2K内存占用会小很多如果开到最大长度内存会明显上涨。从工程经验看做短文本摘要、分类、改写256 到 1024 token 的输出通常够用。做多轮对话至少要留 2048 到 4096 token 的上下文。长文档分析在浏览器里非常吃内存建议先切分成块而不是一次性塞给模型。不要因为模型卡上写着“支持 128K 上下文”就觉得浏览器里也能跑满。大部分消费级 GPU 和浏览器环境跑不满这个长度强行拉长很容易把 device 搞崩溃。3.3 实际可参考的档位这里给一个经验档位具体数字会因为 GPU 和量化格式不同有浮动模型规模量化方式权重体积约适合场景成本评估0.5Bq4约 300 MB简单分类、摘要、指令跟随很轻适合低配机器1Bq4约 600 MB中等难度的生成任务较均衡推荐优先尝试3Bq4约 1.5 GB更复杂推理、多轮对话对显存要求较高7Bq4约 3.5 GB高质量生成只建议高端 GPU 尝试这个表格不是官方数据而是常见量化格式下的估算真实体积以实际模型卡为准。我的建议是先从 0.5B 或 1B 开始跑通流程确认 WebGPU 和内存都稳定再逐步升级到 3B。3.4 量化格式也要看运行时支持不同推理框架支持的量化格式不一样。有的支持q4、q8有的支持fp16、int8。在浏览器方案里通常会选择一种“前端友好”的 ONNX 或 GGUF 量化格式但最终能加载什么格式由你用的推理库决定。不要假设一个 GGUF 文件在任何框架里都能直接读。很多浏览器推理库需要专门转换过的 ONNX 模型。如果从 Hugging Face 下载模型优先选带onnx或quantized标识的仓库否则本地转换过程会非常折腾。4. 从零跑通一条最小推理链路4.1 先定技术路线目前浏览器里跑 LLM 的常见路线主要有transformers.jsHugging Face 团队维护的浏览器端 transformers 实现封装了 WebGPU、WASM 和 ONNX Runtime WebAPI 接近 Python Transformers。web-llm面向 WebGPU 的 LLM 推理方案支持流式输出和多项优化。llama.cpp的 WASM/WebGPU 移植版本适合跑 GGUF 模型但配置相对更底层。这些方案各有侧重我不做绝对推荐。如果你希望 API 简单、社区资料多、方便做原型transformers.js是更快的路径。它的核心逻辑是“把模型转成 ONNX 或量化格式通过 ONNX Runtime Web 在浏览器里执行”。下面以 transformers.js 为主线给出最小可运行的链路。4.2 安装依赖先初始化一个前端项目并安装依赖npm install huggingface/transformers如果你需要把模型文件放在本地静态资源里还要关心env配置。先以远程加载模型开始因为本地文件路径的处理会更复杂适合在远程跑通之后再考虑。4.3 加载模型并做一次单轮推理下面是一段非常基础但能跑通整个链路的示例import { pipeline, env } from huggingface/transformers; // 先关掉本地模型加载避免它去当前域名的根路径找模型 env.allowLocalModels false; async function createGenerator() { const generator await pipeline(text-generation, onnx-community/Qwen2.5-0.5B-Instruct, { device: webgpu, dtype: q4, progress_callback: (progress) { console.log(加载进度: ${progress.percent}%); } }); return generator; } const generator await createGenerator(); const result await generator(用一句话解释 WebGPU 对浏览器本地推理的价值。, { max_new_tokens: 128, do_sample: true, temperature: 0.7 }); console.log(result[0].generated_text);这里有几个需要注意的点model字段要替换成你实际使用的模型仓库 ID。示例里的模型只是一个常见写法模型是否存在于远端、是否支持webgpu和q4要以你的实际运行环境为准。device: webgpu表示优先用 GPU 推理。如果浏览器不支持 WebGPU部分库会自动降级到 WASM但速度会明显下降。dtype: q4是量化格式选择。不是所有模型都支持所有 dtype遇到加载失败时先看模型卡的说明。4.4 从单次生成到流式输出上面的示例是一次性等完整结果。用户体验更好的是流式输出也就是生成一个 token 就渲染一个 token。不同版本的 API 略有差异常见写法是通过streamer或回调函数接收增量 tokenconst result await generator(请写一段关于本地推理的介绍。, { max_new_tokens: 512, streamer: (token) { process.stdout.write(token); // 如果是浏览器 UI就在这里把 token 追加到页面上 // appendToOutput(token); } });流式输出的价值不只是体验好还有一个实际好处它能让你更早发现生成异常。如果前几个 token 就已经是乱码或重复内容可以及时中断而不是等几十秒拿到一段没有意义的完整输出。4.5 观察性能与内存跑通之后不要急着欢呼先看几个指标首 token 时间从点击生成到第一个 token 出现的时间。这个时间受模型加载、kernel 编译影响很大。每秒生成 token 数可以粗略评估“这个模型在这个 GPU 上是否可用”。页面内存占用Chrome 里可以看performance.memory虽然不是官方标准但能反映大致压力。if (performance.memory) { const usedMB performance.memory.usedJSHeapSize / 1024 / 1024; console.log(当前 JS 堆内存: ${usedMB.toFixed(0)} MB); }如果内存持续上涨说明可能存在内存没有及时释放的问题。之后把多次推理独立封装保证每次调用不会把上一次的中间结果一直留在内存里。5. 跑通之后真正要处理的工程化问题5.1 首次加载慢不只是下载问题第一次推理慢原因有两层一是模型文件需要下载二是 GPU 需要编译 shader。模型文件下载的问题可以通过进度条 UI 解决但 kernel 编译问题经常被忽略。WebGPU 在首次执行计算时需要把 shader 编译成当前 GPU 的机器码这个过程可能持续几秒甚至更久。你可能会看到“页面卡住一会儿然后突然开始输出”。应对方式在页面加载完成后就执行一次非常小的 WebGPU 计算提前触发 kernel 编译。把模型加载和预热过程放在 worker 线程或空闲时间执行避免阻塞 UI。在 UI 上明确提示“首次运行需要初始化 GPU请稍候”。5.2 显存不足和设备丢失浏览器推理里最让人头疼的问题是 GPU device lost。现象通常是跑着跑着推理中断页面提示 GPU 设备丢失或者控制台出现WebGPU device lost。这类问题的常见诱因包括GPU 显存被其他程序占用。上下文或 batch size 设置过大。操作系统触发 GPU 驱动重置。浏览器同时打开太多 GPU 标签页。工程上能做的是在device.lost回调里记录日志提示用户刷新或降低参数量。推理前做一次显存估算超过阈值时直接拒绝任务而不是等崩溃。把max_new_tokens和上下文长度做可配置项给用户提供“低内存模式”。换句话说不能假设每个用户的 GPU 都足够强壮。设计时要把“推理可能失败”当成正常状态而不是异常状态。5.3 降级策略没有 WebGPU 时怎么办如果检测到用户机器不支持 WebGPU你有几个选择降级到 WASM / CPU 推理。体验慢但功能可以用。提示用户换一个支持 WebGPU 的浏览器。直接提供“云端推理”按钮把请求转发到服务器。具体怎么做取决于你的产品定位。如果是隐私敏感工具云端转发可能违背“数据不出端”的承诺如果只是内部演示降级到 CPU 反而更简单。我的建议是把 WebGPU、WASM、云端三条路线做成一个可切换的配置而不是硬编码。这样既能覆盖更多用户又能为未来发展留出空间。5.4 从单次调用到可复用模块跑通 demo 之后代码很快会变得复杂起来模型加载状态、进度回调、流式输出、中断处理、错误恢复、结果缓存这些逻辑如果全部堆在 React 组件里项目会很难维护。可以把推理封装成一个单独的模块对外只暴露几个方法class LocalInferenceEngine { async init(options) { /* 探测 GPU、加载模型 */ } async generate(input, options) { /* 单次生成 */ } async generateStream(input, options) { /* 流式生成 */ } cancel() { /* 中断当前生成 */ } getStatus() { /* 返回模型状态和资源占用 */ } }这样一个模块可以同时服务于不同页面也可以被单元测试覆盖。封装的边界要清楚模块内部处理模型加载、GPU device 生命周期、错误恢复页面只处理用户输入和渲染结果。6. 排查链路从报错到定位问题6.1 先按现象分类浏览器推理问题现象无非这几类模型根本不加载。模型加载了推理报错。推理能跑但速度极慢。生成到一半中断。输出质量差或乱码。不同现象指向不同层级不要第一个反应就是“换模型”。6.2 排查顺序我一般按下面这个顺序排查先看环境是不是 HTTPS 或 localhostnavigator.gpu是否存在adapter 是否拿到了。再看模型文件模型仓库是否存在量化格式是否被库支持中转地址能否下载。再看依赖版本transformers.js 版本、ONNX Runtime Web 版本不同版本对 WebGPU 支持差异很大。再看参数max_new_tokens是否过大dtype是否超出模型支持上下文长度是否撑爆内存。最后看日志与边界打开浏览器控制台看 WebGPU 的 warning 和 error判断是算力不足还是模型本身不支持。这个顺序看起来基础但大多数问题都出在前两层。很多人直接跳过环境检查去调推理参数最后绕了一圈回到原点。6.3 常见问题表现象可能原因处理思路navigator.gpu为 undefined浏览器不支持 WebGPU页面不在安全上下文换 Chrome/Edge 最新版用 localhost 或 HTTPSrequestAdapter返回 nullGPU 被禁用或驱动异常虚拟机环境检查系统硬件加速更新驱动换物理机模型加载进度卡住文件下载被 CORS 拦截域名不可访问检查模型仓库地址配置正确的远端域名推理报buffer相关错误权重超maxStorageBufferBindingSize换更小模型换量化精度拆分 buffer推理中断且报 device lost显存不足或 GPU 驱动重置减小上下文长度降低max_new_tokens加错误恢复首 token 很慢shader 编译模型文件从远端磁盘加载提前预热 GPU缓存模型文件加加载提示输出乱码或重复模型与 tokenizer 不匹配采样参数不当检查模型卡和 tokenizer调低 temperature遇到不确定的报错先把 WebGPU device lost 回调、console.error、浏览器版本、GPU 型号四样东西记录下来再去查具体框架的 issue。信息越完整定位越快。注意WebGPU 是快速演进的接口不同浏览器的实现细节和限制都有差异。如果你的项目要覆盖多浏览器建议在 CI 里加一个“WebGPU 能力矩阵”测试而不是只在一台 Mac 上验证。7. 适用边界与我的建议7.1 适合什么人浏览器本地推理目前最适合这几类人前端开发者想做本地优先的 AI 工具不希望引入复杂后端。独立开发者或小团队要做原型用于验证产品和用户体验。隐私敏感场景的工程负责人希望数据完全不出设备。学习者想理解 WebGPU 和模型推理的底层关系。这类人群的共同特点是可以接受模型能力弱一点、环境兼容性差一点但一定要快速看到效果。7.2 不适合什么人如果你的情况符合下面任意一条我建议谨慎需要大规模并发、面向全网用户的 SaaS 产品。浏览器推理不能替代服务器只会把不稳定的 GPU 环境抛给每个用户。需要高强度长文档分析上下文超过 8K 甚至 16K。浏览器内存压力会非常大。用户集中在老旧浏览器或受限企业环境。WebGPU 兼容性会成为最大阻碍。需要对生成内容做集中审计、日志记录、模型版本管理。这些能力在浏览器端非常难做。7.3 长期价值判断我的判断是浏览器本地推理不会取代服务器推理但它的价值会随着 WebGPU 普及和设备算力提升而持续增加。这类方案真正的长期价值不在于“把大模型塞进浏览器”这个行为本身而在于它重新划定了隐私和部署的边界。数据不出端、零安装、即开即用这三个特性在很多垂直场景里有不可替代的意义。所以我的建议是如果你正好有一个单用户、隐私敏感、快速原型类的需求现在就可以开始尝试。但请把第一优先级放在 WebGPU 验证和内存管理上而不是花大量时间调提示词。让流程先可控再谈效果。整个方案能不能成立往往在你加载第一个模型之前就已经决定了。