之前调研前端智能化方案时有一个场景始终让我头疼很多用户希望在不注册账号、不下载 App、也不把业务数据上传到服务端的前提下直接在浏览器里体验大语言模型的对话和生成能力。这个需求听起来简单落地时却会碰到两个硬门槛一是传统 Web 技术栈跑不动大模型二是浏览器缺少高性能计算接口。直到 WebGPU 逐渐在主流浏览器中铺开后“浏览器本地运行 LLM”这扇门才真正被推开。这篇文章会围绕“在浏览器中运行 LLM”这个主题展开从 WebGPU 能力验证开始逐步带你完成一个可运行的本地推理示例再补充性能优化、常见报错排查和工程化建议。整个过程以可复现代码为主适合前端开发者、AI 应用开发者以及对浏览器端本地推理感兴趣的学习者。1. 为什么要把 LLM 放到浏览器里跑1.1 云端推理的痛点和本地推理的价值早期的 LLM 应用大多采用纯云端架构用户把文本通过 HTTP 请求发送到服务端服务端调用 GPU 集群或第三方大模型 API再把结果返回浏览器。这种架构很成熟但有几个问题让一部分业务场景很难接受数据隐私聊天内容、业务文档、用户输入一旦离开设备就需要考虑传输安全、存储安全、审计合规。很多企业数据根本不允许上传到外部接口。服务成本云端 GPU 实例和 Token 费用是持续性的用户量大之后成本压力很明显。网络依赖纯粹离线环境、弱网环境或者内网环境可能无法访问公网大模型服务。响应延迟一次 API 请求包含网络往返、排队、推理时间极端情况下会超过用户容忍范围。浏览器端本地推理的价值正好对应解决这些问题模型文件下载到浏览器本地后推理过程完全在设备上完成用户输入不需要离开浏览器。没有服务端 GPU 费用模型一次分发后续使用接近零边际成本。模型可以离线运行适合内网、飞机、施工现场等弱网场景。推理延迟不受公网影响加载完成后对话响应速度更稳定。1.2 浏览器端 LLM 的典型应用场景哪些产品形态适合把 LLM 塞进浏览器从目前的实践经验看主要有这几类网页智能助手在后台管理系统中嵌入一个本地小模型帮运营人员润色文案、抽取关键词、生成摘要。敏感数据环境下的知识库医疗、金融、政务等场景文档不出本机是最低要求浏览器本地推理可以在保证隐私的前提下提供智能问答。离线文档处理工具用户在浏览器中打开一个 HTML 文件就能对本地 Markdown、TXT、PDF 内容做摘要和翻译适合没有后端服务的小工具。教学与演示给初学者展示 LLM 的“最小可运行单元”不需要注册 API Key 就能看到模型输出。跨平台桌面应用基于 Electron、Tauri 等框架把浏览器推理能力打包进桌面产品。1.3 本地推理的能力边界这里需要提前说明浏览器端运行 LLM 并不是万能的浏览器能分配到的内存有限单页应用通常只能运行 0.5B 到 7B 参数规模的量化模型。推理速度取决于用户设备 GPU不同硬件差异很大一台集显笔记本和一台游戏本可能相差十倍以上。模型下载体积仍然有几百 MB 到几 GB首次加载等待时间不短。浏览器端更适合“单用户、轻交互、任务明确”的场景不适合高并发生产环境。2. WebGPU浏览器高性能计算的基础2.1 从 WebGL 到 WebGPU在 WebGPU 出现之前浏览器端能使用的图形 API 主要是 WebGL。WebGL 基于 OpenGL ES设计目标是光栅化渲染可以画三角形、跑着色器但它的计算模型和现代 GPU 的通用计算能力之间隔着一层“翻译层”。WebGPU 是一套更低层、更接近现代 GPU 架构的浏览器图形与计算 API。它提供了更灵活的内存布局控制。更高效的渲染管线状态管理。真正的通用计算着色器也就是 Compute Shader。可以在浏览器里直接做 GPU 并行计算例如矩阵乘法、卷积、归约操作。简单理解WebGL 的目标是“把图形画出来”而 WebGPU 的目标是“把 GPU 当成一个通用并行计算设备来使用”。2.2 GPU 在 LLM 推理中扮演什么角色大语言模型的推理过程本质上是一次次大规模矩阵运算。当你给模型输入一句话模型内部会把它拆成 Token然后经过多层 Transformer 结构。每一层都包含大量的乘法累加运算例如 Query、Key、Value 投影以及注意力分数的计算。这些运算非常适合 GPU 这种“几千个核心同时算”的架构。在浏览器里如果只用 JavaScript 做矩阵乘法即使经过 JIT 优化速度也远不够用。如果编译成 WebAssemblyWASM虽然比纯 JS 快但仍然是在 CPU 上跑瓶颈明显。WebGPU 能直接把计算任务发送到 GPU几千个线程并行处理矩阵运算推理速度可以有数量级提升。2.3 主流浏览器对 WebGPU 的支持情况WebGPU 已经从实验状态进入正式标准化轨道。目前主流浏览器的支持情况大致如下但具体版本可能会随浏览器迭代发生变化Chrome较新版本默认启用 WebGPU可以直接使用navigator.gpu。Edge由于与 Chromium 同源支持情况与 Chrome 基本一致。FirefoxWebGPU 支持一直在推进部分版本需要开启实验特性。Safari后续版本已逐步支持 WebGPU但功能覆盖与稳定性需以官方发布说明为准。如果你在生产环境使用浏览器端 LLM建议先做一个能力检测页面在用户浏览器上确认 WebGPU 是否可用再决定是否加载模型。这也是本文第 4 部分要做的事。3. 环境准备与技术选型3.1 运行时环境本文示例以常见开发环境为例不限制操作系统Windows、macOS、Linux 都可以。你需要准备浏览器推荐 Chrome 或 Edge并确保版本足够新确认可以访问chrome://gpu页面查看 GPU 相关状态。Node.js 和 npm后续部分会用到 npm 安装依赖建议使用 Node.js 18 以上版本。本地静态服务器因为浏览器安全策略限制直接双击 HTML 文件时部分 ES Module 和模型加载可能失败。推荐使用npx serve或其他静态服务器工具启动一个本地服务。文本编辑器VS Code 或任意你习惯的编辑器。如果你的项目版本和本文示例不同相关依赖版本需要根据实际情况调整重点理解配置思路和代码结构。3.2 三条主流浏览器端推理路线目前想在浏览器里跑 LLM比较成熟的技术路线有三条技术方案底层实现适用场景特点transformers.jsONNX Runtime Web / WASM / WebGPU文本生成、分类、摘要、embedding接口接近 Python transformers上手快WebLLMMLC LLM 编译引擎 WebGPU浏览器对话式模型针对 GPU 优化效果更接近原生推理llama.cpp WASMC 编译到 WebAssembly小型模型离线推理依赖少但缺少 WebGPU 加速时性能一般从工程实践角度看transformers.js 适合快速原型验证WebLLM 更适合追求 GPU 推理性能的对话产品。3.3 本文使用的示例环境本文的完整示例主要使用以下几个组件huggingface/transformersHugging Face 推出的浏览器端推理库用于第一个文本生成 demo。mlc-ai/web-llmWebLLM 的 npm 包用于第二个对话式推理 demo。浏览器原生navigator.gpuAPI用于验证 WebGPU 支持情况。代码中的模型名称、API 参数以官方仓库当前版本为准本文给出的代码侧重演示完整链路你在实际项目中需要按版本调整。4. 验证 WebGPU 是否可用4.1 为什么要先验证 WebGPU浏览器端 LLM 推理依赖 WebGPU 做加速。如果浏览器不支持或者虽然支持但用户设备没有可用的 GPU 适配器后续的模型加载和推理都会失败。在项目启动时先做一次能力检测可以让用户得到明确提示例如“当前浏览器不支持 WebGPU请升级 Chrome”或“没有检测到可用的 GPU 适配器”。这比运行到一半再报错友好得多。4.2 完整 WebGPU 检测页面下面是一个可以直接复制保存为 HTML 文件的检测页面打开后就能看到当前浏览器的 WebGPU 支持情况。!DOCTYPE html html langzh-CN head meta charsetUTF-8 / meta nameviewport contentwidthdevice-width, initial-scale1.0 / titleWebGPU 可用性检测/title /head body h1WebGPU 支持检测/h1 pre idoutput正在检测中.../pre script const output document.getElementById(output); async function checkWebGPU() { if (!navigator.gpu) { output.textContent 当前浏览器不支持 WebGPU。请升级到新版 Chrome 或 Edge并确认硬件加速已开启。; return; } const adapter await navigator.gpu.requestAdapter(); if (!adapter) { output.textContent 浏览器声明支持 WebGPU但没有找到可用的 GPU 适配器。请检查显卡驱动、浏览器硬件加速开关或尝试在独立显卡环境下运行。; return; } const device await adapter.requestDevice(); const info adapter.info || {}; output.textContent [ WebGPU 可用, , 适配器信息, - vendor: ${info.vendor || 未知}, - architecture: ${info.architecture || 未知}, - device: ${info.device || 未知}, - description: ${info.description || 未知}, , 设备对象已创建, - maxBufferSize: ${device.limits.maxBufferSize}, - maxTextureDimension2D: ${device.limits.maxTextureDimension2D}, ].join(\n); } checkWebGPU(); /script /body /html把这个文件保存为webgpu-check.html用浏览器直接打开即可。如果遇到模块加载问题也可以放到本地静态服务器目录下再访问。4.3 关键 API 说明下面对检测代码中的几个关键点做一个解释。navigator.gpu是浏览器暴露 WebGPU 入口的对象。如果它不存在说明当前浏览器不支持 WebGPU 或未开启对应特性。navigator.gpu.requestAdapter()用于获取 GPU 适配器。适配器相当于一个“显卡驱动实例”。它可能返回null表示没有可用的硬件适配器比如显卡驱动异常、远程桌面环境等场景都会出现这种问题。adapter.requestDevice()用于创建设备对象。设备是 WebGPU 中进行资源分配和命令提交的核心句柄。真正执行计算时需要 device。adapter.info可以返回供应商、架构和设备名称。不过在不同浏览器中这个对象的字段会有差异建议只在调试时使用不要把它当成稳定的业务数据源。4.4 预期输出在支持 WebGPU 的 Chrome 浏览器中页面会输出类似下面的信息WebGPU 可用 适配器信息 - vendor: 0x10de - architecture: sm_120 - device: 0x2783 - description: NVIDIA GeForce RTX 4070 设备对象已创建 - maxBufferSize: 2684354560 - maxTextureDimension2D: 16384其中vendor是显卡厂商 ID0x10de对应 NVIDIA0x1002对应 AMD0x8086对应 Intel。如果设备是集显description里一般会显示核显名称。5. 实战用 transformers.js 在浏览器中跑通文本生成5.1 安装与引入方式transformers.js 是 Hugging Face 团队推出的 JavaScript 推理库它能把 Hugging Face 上的大量模型转换成 ONNX 格式并在浏览器或 Node.js 中运行。推荐使用 npm 安装npm install huggingface/transformers如果你想快速验证一个单页 demo也可以从 CDN 引入 ESM 模块。下面的示例会使用 CDN 方式这样你不需要先搭建打包工具只要一个 HTML 文件就能跑起来。5.2 完整网页示例接下来创建一个transformers-llm-demo.html文件内容如下。!DOCTYPE html html langzh-CN head meta charsetUTF-8 / meta nameviewport contentwidthdevice-width, initial-scale1.0 / titletransformers.js 本地 LLM 推理/title /head body h1transformers.js 本地 LLM 推理/h1 textarea idinput rows3 placeholder输入一段文本例如人工智能的未来/textarea br / button idrunBtn生成/button pre idoutput等待模型加载.../pre script typemodule import { pipeline, env } from https://cdn.jsdelivr.net/npm/huggingface/transformers; // 禁止从本地文件加载模型统一走浏览器缓存或远端模型仓库 env.allowLocalModels false; const input document.getElementById(input); const output document.getElementById(output); const runBtn document.getElementById(runBtn); let generator null; async function init() { output.textContent 正在加载模型首次访问需要下载文件...; // 这里以文本生成任务为例模型名称可按实际需求替换 generator await pipeline(text-generation, Xenova/gpt2); output.textContent 模型加载完成请输入文本并点击生成。; } runBtn.addEventListener(click, async () { if (!generator) { output.textContent 模型还在加载中请稍候。; return; } const text input.value.trim(); if (!text) { output.textContent 请输入文本内容。; return; } output.textContent 正在生成...; try { const result await generator(text, { max_new_tokens: 50, do_sample: false, }); if (result result[0] result[0].generated_text) { output.textContent result[0].generated_text; } else { output.textContent 模型未返回有效内容。; } } catch (error) { output.textContent 推理出错 error.message; } }); init(); /script /body /html由于浏览器安全策略限制直接双击 HTML 文件可能无法正常加载 CDN 模块建议在当前目录启动一个静态服务器npx serve .然后访问http://localhost:3000/transformers-llm-demo.html。5.3 代码逻辑拆解pipeline是 transformers.js 的核心入口。第一个参数text-generation表示任务类型第二个参数是模型名称。Xenova/gpt2是一个适合初学的轻量模型但生成质量有限生产环境建议换成任务效果更好的模型。env.allowLocalModels false的作用是避免库尝试从本地目录加载模型。如果项目部署在公网 CDN建议显式设置模型存放路径或者使用镜像地址。生成参数中max_new_tokens控制新生成 token 的最大数量do_sample: false表示使用贪心解码。如果你希望输出更有随机性可以改成do_sample: true并设置temperature参数。推理过程放在按钮事件回调里并使用try-catch包裹。浏览器端模型推理涉及网络下载、内存分配、GPU 执行等多个环节异常信息需要展示给用户不能静默失败。5.4 运行与验证首次打开页面时浏览器会下载模型文件。gpt2 量化后的 ONNX 模型体积一般在 100 MB 左右首次加载需要一段时间。模型加载完成后输入示例文本人工智能的下一步发展是点击“生成”页面会输出模型续写的完整文本。由于 gpt2 是英文模型如果输入中文效果会很差。因此建议换成一个中文友好的小模型模型名称需要参考 transformers.js 官网的模型列表。需要注意transformers.js 在浏览器端默认可能走 WASM 或 WebGPU 后端库的版本不同默认执行设备也不同。实际开发时需要根据模型格式和推理性能选择设备类型。6. 进阶实战用 WebLLM 加载对话模型6.1 为什么选 WebLLMWebLLM 是 MLC LLM 团队推出的浏览器端推理方案。它在底层做了大量编译优化可以充分利用 WebGPU 的计算能力在浏览器里跑起对话式大模型。和 transformers.js 相比WebLLM 更专注于 LLM 对话场景API 设计也更接近 OpenAI 接口风格非常适合做聊天机器人类应用。6.2 初始化项目建议在正式项目中使用 npm 包并通过 Vite 等构建工具打包。mkdir webllm-demo cd webllm-demo npm init -y npm install mlc-ai/web-llm注意WebLLM 不同版本的模型列表和 API 名称会有差异安装前务必查看当前版本对应的官方文档。6.3 核心对话代码下面是一个使用 WebLLM 在浏览器里创建对话引擎的完整示例。// main.js import { CreateMLCEngine } from mlc-ai/web-llm; // 模型名称只是一个示例实际可用的模型列表以官方模型库为准 const MODEL_ID Llama-3.2-1B-Instruct-q4f32_1-MLC; async function main() { const statusEl document.getElementById(status); const outputEl document.getElementById(output); statusEl.textContent 正在创建引擎首次使用会下载模型...; const engine await CreateMLCEngine(MODEL_ID, { initProgressCallback: (progress) { const p progress.progress; statusEl.textContent 加载进度${Math.round(p * 100)}%; }, }); statusEl.textContent 引擎就绪开始对话。; const messages [ { role: system, content: 你是一个简洁的 AI 助手。 }, { role: user, content: 请用一句话介绍浏览器中的 WebGPU。 } ]; const reply await engine.chat.completions.create({ messages: messages, temperature: 0.7, max_tokens: 128, }); outputEl.textContent reply.choices[0].message.content; } main();配套的 HTML 文件如下!DOCTYPE html html langzh-CN head meta charsetUTF-8 / meta nameviewport contentwidthdevice-width, initial-scale1.0 / titleWebLLM 对话 Demo/title /head body h1WebLLM 浏览器对话/h1 div idstatus初始化中.../div pre idoutput/pre script typemodule src./main.js/script /body /html为了让这个示例跑起来还需要一个打包器。最简单的做法是安装 Vitenpm install -D vite npx vite然后访问 Vite 输出的本地地址。6.4 代码说明与注意事项CreateMLCEngine是 WebLLM 的入口方法它会完成模型下载、编译、初始化整个流程。模型 ID 决定了下载哪个模型也直接影响推理速度和质量。initProgressCallback用来展示加载进度。由于模型文件可能有几百 MB 甚至几 GB没有进度提示的话用户很容易以为页面卡死了。engine.chat.completions.create的接口风格与 OpenAI API 很像需要传入messages数组包含 system、user、assistant 角色。这种设计降低了从云端 API 切换到本地推理的改造成本。需要特别强调的是WebLLM 会从模型仓库下载文件如果你的网络无法访问对应域名需要在内网环境自建模型仓库或者提前把模型文件打包到静态资源目录。模型文件很大生产环境建议使用 CDN 分发和浏览器缓存。7. 性能、内存与工程化问题7.1 浏览器端推理的性能瓶颈浏览器端跑 LLM性能瓶颈主要集中在三个地方模型下载文件体积大首次加载耗时长。内存占用模型权重、KV Cache、中间激活都需要内存。手机端和低内存电脑容易崩溃。GPU 计算能力集显和低功耗设备推理速度慢但胜在离线可用。WebGPU 能把矩阵乘法交给 GPU但显存或统一内存不足时浏览器会直接崩溃或者 GPU 处理速度比 CPU 还慢。实际使用中需要使用“性能检测”工具监控帧率和内存变化。7.2 如何选择合适的模型和量化等级模型参数越大效果越好但内存和显存要求也越高。下面是几个常见的经验原则0.5B 到 1B 参数模型适合低配笔记本和手机浏览器内存占用可控。3B 到 7B 参数模型效果明显提升但需要 16 GB 以上内存或独立显卡否则推理很吃力。量化等级例如 q4f16、q4f32量化位数越低模型越小但精度损失也越大。选择模型时建议先在目标设备上跑一次完整评测记录加载耗时、首次 token 耗时、生成速度和内存峰值。不要只看模型参数量。7.3 用 Web Worker 避免阻塞 UI大模型推理是一次重计算过程如果直接放在主线程页面会卡住用户可能以为浏览器死了。推荐把推理逻辑放到 Web Worker 中。这样模型加载和生成都不会阻塞页面交互主线程可以渲染进度条和流式输出。在 transformer.js 和 WebLLM 文档中都有 Web Worker 的使用示例。如果你要开发一个正式产品这一步不是可选项而是必须项。7.4 流式输出与终止控制对话类应用应该使用流式输出让模型生成一个 token 就显示一个 token。这样用户能感受到“模型正在思考”而不是盯着一个空白页面等待。WebLLM 支持stream: true参数transformers.js 也有对应的流式回调。同时还要提供“停止生成”按钮。如果模型在无限循环或生成很慢用户能手动终止任务避免资源一直被占用。8. 常见问题与排查思路浏览器端 LLM 推理涉及浏览器版本、GPU 驱动、模型下载、内存分配等多个环节问题种类很多。下面整理了一份高频问题排查表。问题现象常见原因解决思路navigator.gpu为 undefined浏览器版本过低或不支持 WebGPU升级到新版 Chrome/Edge检查浏览器硬件加速开关requestAdapter()返回 null显卡驱动异常、远程桌面环境、浏览器策略限制更新显卡驱动检查chrome://gpu在本地物理机环境测试模型下载很慢或一直卡住模型文件过大或网络无法访问模型仓库使用 CDN 镜像提前把模型资源打包到静态目录显示下载进度页面加载后崩溃模型过大内存或显存不足换成更小模型降低量化精度使用 Web Worker 隔离推理线程生成速度很慢设备 GPU 能力弱或者模型较大调整模型尺寸使用 q4 低比特量化对比 CPU/WASM 与 GPU 后端耗时输出空白模型不适合该任务或输入格式错误查看浏览器控制台报错换个更合适的模型检查是否把中文输入传给了英文模型页面提示“script error”CDN 资源跨域或脚本加载失败改用 npm 本地打包检查浏览器网络请求是否被拦截点击生成后按钮无反应模型还没初始化完成在 UI 上显示初始化状态未就绪时禁用生成按钮生成结果存在明显幻觉模型过小或量化损失过大换成更大的模型使用更高质量的量化等级接入检索增强做约束8.1 页面崩溃或内存溢出怎么排查如果你遇到页面崩溃优先按以下顺序排查打开浏览器的任务管理器观察浏览器进程的内存占用。查看控制台是否有Out of memory或类似错误。把模型换成更小的版本例如从 3B 降到 1B。检查是否开了太多标签页关闭其他高内存页面后再测试。最终方案是微调模型量化精度或者改用云端推理。8.2 “加载进度卡在某个百分比”怎么处理模型加载卡住最常见原因是网络请求失败但页面没有正确提示。你可以打开浏览器开发者工具的 Network 面板查看是否有 4xx 或 5xx 状态的请求。如果有说明模型文件地址失效。尤其在模型迭代频繁的框架中旧的模型文件名可能会被清理。解决办法是确认模型名称和官方仓库中一致。在初始化回调中增加超时判断和重试逻辑。预留手动清除缓存的功能避免旧缓存干扰新模型加载。9. 最佳实践与工程建议9.1 能力渐进增强浏览器端 LLM 不能作为唯一方案它更像一个“能力增强层”。推荐的做法是页面启动时先检测 WebGPU 和模型资源是否就绪。如果本地推理可用优先使用本地模型数据不出设备。如果浏览器不支持 WebGPU或者用户设备太旧自动降级为云端 API。降级过程对用户透明并在 UI 上标明当前使用的是“本地模式”还是“云端模式”。这种渐进增强策略可以兼顾隐私、成本和体验。9.2 模型加载与缓存策略模型文件很大缓存策略直接影响用户留存。使用 CDN 分发模型文件并在响应头中配置Cache-Control。在 Service Worker 中做模型文件的持久化缓存避免每次刷新页面都重新下载。支持“预加载”模式用户进入页面后空闲时提前下载模型等真正使用时可以秒开。提供模型文件版本管理升级模型时能自动清理旧版本缓存。9.3 安全边界与隐私保护浏览器端推理的一个优势是数据不出设备但这不代表没有安全隐患模型文件本身可能被逆向不要在模型权重中嵌入敏感逻辑。如果网页中混有第三方脚本理论上前端页面能读取所有内存数据所以要确保页面依赖的 CDN 和脚本来源可信。涉及未成年人、医疗、金融等敏感场景时即使本地推理也必须做好页面级访问控制和操作审计。如果最终采用“本地模型 云端接口”混合架构传给云端的内容必须经过脱敏和最小化处理。9.4 日志与可观测性本地推理很难像服务端那样集中查看日志但这不代表不需要可观测性。建议在代码中埋点记录 WebGPU 检测结果和适配器信息。记录模型加载耗时、下载流量、首次 token 延迟。记录每次生成请求的输入长度、输出长度、平均 token 速度。把错误信息通过埋点 SDK 发送到服务端方便远程分析。这些数据会对模型选型和性能优化提供宝贵依据。否则你很难知道用户实际上跑在哪类设备、卡在哪个环节。10. 总结与学习路线这篇文章梳理了浏览器端运行 LLM 的核心链路。我建议你把以下四个步骤完整实践一遍先用 WebGPU 检测页面确认你的浏览器和设备是否能跑 GPU 推理。用 transformers.js 跑通一个最简单的文本生成 demo理解模型加载和生成参数。再用 WebLLM 接入一个对话式模型体验chat.completions接口的流式输出。最后把推理逻辑迁移到 Web Worker处理页面阻塞、进度展示和降级策略。如果你已经顺利跑通了基础的浏览器端推理下一步可以继续学习这些方向深入 WebGPU Compute Shader 原理理解矩阵乘法在 GPU 上如何被调度。对比不同量化方案的精度和速度差异例如 q4f16 与 q8f32。尝试把检索增强生成放到浏览器中让你的本地模型能回答私有文档内容。研究 transformer.js 和 WebLLM 在不同移动设备上的适配方案。浏览器端 LLM 仍在快速演进中可能会遇到各种怪问题但核心链路已经非常清晰WebGPU 负责算力模型量化负责瘦身前端工程负责体验。建议你在自己电脑上把第一个 demo 跑通后再往移动端和低配设备方向探索。