浏览器端跑 LLM 已经不是新鲜概念但真正想把“浏览器内本地推理”从 demo 变成可用的功能会撞上很多细节问题WebGPU 到底开没开、模型怎么加载、推理占多少显存、批量任务怎么排队、接口怎么暴露给上层应用。这篇文章就围绕Browser WebGPU Local Inference这条链路来展开先讲清楚最核心的几个判断这套方案能做什么、门槛在哪里、怎么验证 WebGPU、怎么部署一个最小可用的浏览器端本地推理环境。然后给出功能测试、接口调用、批量任务、性能观察和排错清单尽量让读者看完之后能自己动手跑通一遍。如果你正好在调研“要不要把 LLM 推理放到浏览器里”或者准备在本地做一个离线 AI 工具的原型这篇文章可以直接收藏。1. 核心能力速览先看整体能力矩阵。浏览器端 LLM 本地推理不是一个单一项目而是由 WebGPU 标准、推理框架、模型格式和前端集成方式共同组成的一类技术方案。能力项说明项目类型浏览器端 LLM 本地推理方案依赖 WebGPU 做 GPU 加速核心价值模型在浏览器本地运行文本数据不需要上传到服务端离线可用主要实现方案WebLLM、Transformers.js、llama.cpp Web 版、ONNX Runtime WebWebGPU 要求浏览器需支持 WebGPUChrome 113 默认启用Firefox / Safari 支持进度较慢本地推理门槛参数量越小的模型越容易跑通0.5B 到 1.5B 级别更适合浏览器端是否支持批量任务可以但需要配合 Web Worker 和任务队列自行实现接口 API浏览器内以 JavaScript API 为主可作为页面内模块或 Worker 服务显存占用取决于模型参数量、量化方式、上下文长度需按实际环境测试启动方式纯前端部署通常是静态页面 本地静态服务无需安装 Python 后端适合场景本地演示、隐私敏感推理、无服务器前端应用、边缘设备不适合场景服务端高并发、超长文本生成、大参数模型生产部署从材料来看这套技术路线的核心逻辑是WebGPU 把 GPU 能力暴露给浏览器推理框架把模型编译成浏览器可执行的格式最终在本地完成前向推理。理解了这条链路后面做验证和排错都会清晰很多。2. 适用场景与使用边界浏览器端本地推理最典型的优势是“数据不出设备”。这意味着对于聊天记录、企业文档、个人笔记这类隐私敏感的内容可以只在浏览器内做摘要、分类、检索增强生成不需要把内容送到远端模型接口。这种用法在内部工具和离线场景中很有价值。同时也要明确边界浏览器不是为大规模 LLM 推理设计的运行环境。页面有内存上限、GPU 资源要和渲染进程共享、模型体积受网络加载时长限制、推理速度无法和原生 CUDA 环境相比。更稳妥的判断是浏览器端适合轻量模型、短文本、交互式场景不适合追求极致吞吐或处理超长文档的生产级任务。使用边界还包括授权与合规。浏览器端在本地推理不意味着模型和数据没有约束模型权重有各自的开源许可证商用前要确认许可范围如果有用户输入数据被记录到日志或分析平台同样会涉及隐私合规。涉及人脸、声音、版权素材等内容的推理项目必须先获得合法授权。前端代码里的模型资源如果部署到公网还要考虑防盗链和访问控制避免被刷流量。3. 浏览器端 LLM 推理的技术原理要验证 WebGPU 和本地推理先要搞懂浏览器端 LLM 是从哪条链路跑起来的。3.1 WebGPU 是什么WebGPU 是 W3C “GPU for the Web” 社区组制定的 Web 图形和计算标准。它比 WebGL 更贴近现代 GPU 架构允许网页直接向 GPU 提交计算任务因此天然适合做矩阵乘法、Transformer 推理这类并行计算。对于 LLM 推理来说WebGPU 提供了两层能力一是把模型计算分配到 GPU 而不是 CPU二是使用 GPU 的并行能力加速矩阵运算。浏览器没有 WebGPU 时许多前端推理框架只能退回到 WebGL2 或 WASM而 WebGL2 主要面向图形渲染计算能力有限这也是为什么前面提到 “your browser does not support graphics api webgl 2” 这类提示时通常意味着环境没有达到推荐规格。3.2 模型怎么在浏览器里跑浏览器没法直接读取 PyTorch 权重需要先把模型转换为 Web 端可加载的格式。常见做法有两种转换为 ONNX 格式用 ONNX Runtime Web 或 Transformers.js 加载转换为 MLC 或 GGUF 格式用 WebLLM 或 llama.cpp Web 版加载。推理过程中框架会把模型参数按量化格式加载到内存再把部分计算放到 GPU。网页 UI 线程不能长时间阻塞所以真正的推理通常放在 Web Worker 中执行避免页面卡顿。3.3 本地推理的数据流一次完整的浏览器端本地推理大概是Web 页面 → 输入提示词 → Web Worker → 推理引擎 → WebGPU Compute Pipeline → 模型输出 → 回传页面整个链路不经过后端服务器。模型文件本身需要通过网络加载但一旦缓存到浏览器本地或部署在本地静态服务后续推理就不再依赖外部请求。4. 环境准备与前置条件在部署之前先检查一轮本机环境。和传统 Python 部署不同浏览器端方案对操作系统的依赖较小重点在浏览器版本、GPU 驱动、内存容量和网络加载方式。4.1 操作系统与浏览器Windows、macOS、Linux 都可以运行只要浏览器支持 WebGPU。更准确的支持矩阵建议以下面这些关键版本为参考浏览器WebGPU 支持情况Google Chrome 113较早就默认启用 WebGPU适合主力测试Microsoft Edge 113Chromium 内核WebGPU 支持情况和 Chrome 基本一致Mozilla Firefox支持进度相对滞后建议用正式版或预览版测试Apple Safari较新版本开始支持macOS 版本太低则不可用如果没有把握优先用最新版 Chrome / Edge 做验证兼容性最稳。4.2 GPU 与驱动WebGPU 需要一个能识别到的 GPU。NVIDIA、AMD、Intel 的现代集成显卡或独立显卡一般都可以但驱动版本太旧时浏览器可能无法正常创建 GPU 适配器。集成显卡跑小模型通常可行但推理速度会明显慢于独立显卡。4.3 内存与磁盘浏览器页签中的模型推理除了 GPU 显存还会占用系统内存。建议 8GB 以上内存模型文件越大内存占用越高。磁盘空间主要留给模型文件一个 1B 参数模型的量化版本可能在 500MB 到 1.5GB 之间加载时浏览器缓存还会占用额外空间。4.4 本地静态服务浏览器页面要加载本地模型文件直接用file://协议经常遇到跨域和资源加载问题。更好的做法是启动一个本地静态服务把页面和模型文件放到同一个目录下。# 在项目根目录启动静态服务端口可按需修改 python -m http.server 8080或者使用 Node 生态的静态服务工具# 需要先安装 node然后执行 npx serve .启动后访问http://localhost:8080即可打开页面。5. 验证浏览器 WebGPU 支持这次主题的关键动作就是“验证 WebGPU”。不要等到模型加载报错才检查先把 WebGPU 环境确认清楚。5.1 用一段代码判断创建一个index.html加入下面的检测脚本。它通过navigator.gpu判断浏览器是否暴露 WebGPU 接口再通过requestAdapter()确认能否拿到 GPU 适配器。!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 titleWebGPU 检测/title /head body h1WebGPU 检测/h1 pre idlog正在检测.../pre script async function checkWebGPU() { const logEl document.getElementById(log); if (!navigator.gpu) { logEl.textContent 当前浏览器不支持 WebGPU请使用较新版本的 Chrome / Edge。; return; } const adapter await navigator.gpu.requestAdapter(); if (!adapter) { logEl.textContent 浏览器支持 WebGPU但没有找到可用 GPU 适配器。; return; } const info adapter.info || {}; const vendor info.vendor || unknown; const architecture info.architecture || unknown; logEl.textContent WebGPU 可用适配器${vendor} / ${architecture}; } checkWebGPU(); /script /body /html在浏览器中打开这个页面。如果输出“WebGPU 可用”说明环境没问题如果提示不支持或没有适配器要回到第 4 节检查浏览器版本和驱动。5.2 通过浏览器内部页面确认Chromium 内核浏览器可以直接访问chrome://gpu在页面里搜索 “WebGPU” 或 “WebGL”查看对应状态。如果显示硬件加速已启用说明 GPU 可以被识别如果显示软件渲染说明驱动或系统环境有问题。5.3 判定标准检测结果结论页面显示 WebGPU 可用可以继续做模型推理测试页面显示 WebGL2 不支持浏览器或 GPU 环境不满足先升级浏览器和驱动页面显示无可用适配器GPU 被禁用或驱动过旧需要检查系统6. 主流浏览器端推理方案对比在同一个浏览器环境里可以选不同框架来跑本地推理。下面几个方案各有侧重。方案主要特点模型格式适合人群Transformers.jsHugging Face 生态任务类型丰富ONNX前端开发者快速集成WebLLMMLC.AI 维护专门针对 LLM 推理优化MLC需要完整聊天/生成流程llama.cpp Web 版复用 C 推理能力体积可控GGUF已有 GGUF 模型想转 Web 端ONNX Runtime Web通用推理运行时ONNX已有 ONNX 部署栈的团队从易用角度看Transformers.js 比较适合前端新手加载模型和调用 pipeline 都很直接。WebLLM 则更贴近 OpenAI 风格的 API适合做聊天应用。GGUF 方案适合已经熟悉 llama.cpp 生态、想快速把本地模型 Web 化的开发者。7. 本地部署与启动最小可运行 Demo下面给两个最小部署示例一个用 Transformers.js一个用 WebLLM。代码可以放在本地静态服务目录然后通过浏览器访问测试。7.1 使用 Transformers.js 运行文本生成Transformers.js 可以直接通过 CDN 或 npm 包引入。下面的示例使用 CDN 写法模型名需要根据模型库实际情况替换。!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 titleTransformers.js 浏览器推理测试/title /head body h1浏览器端 LLM 推理测试/h1 textarea idinput你好请用一句话介绍你自己。/textarea button idrun生成/button pre idoutput等待输入.../pre script typemodule import { pipeline } from https://cdn.jsdelivr.net/npm/huggingface/transformers2.17.2; const outputEl document.getElementById(output); const inputEl document.getElementById(input); const runBtn document.getElementById(run); // 模型名需要按模型库实际情况替换建议第一次使用较小模型 const generate await pipeline(text-generation, Xenova/qwen2.5-0.5b-instruct); runBtn.addEventListener(click, async () { const text inputEl.value.trim(); if (!text) return; outputEl.textContent 生成中...; const result await generate(text, { max_new_tokens: 100, temperature: 0.7 }); outputEl.textContent result[0]?.generated_text || JSON.stringify(result); }); /script /body /html启动本地静态服务后打开页面点击生成按钮。首次加载需要下载模型进度可以在浏览器 Network 面板观察模型缓存后后续加载会快很多。7.2 使用 WebLLM 运行聊天式推理WebLLM 的接口更接近 OpenAI SDK适合做聊天应用。下面的示例是一种常见调用方式实际模型名和初始化流程要以项目文档为准。import * as webllm from mlc-ai/web-llm; const initProgressCallback (report) { console.log(加载进度, report); }; const selectedModel Qwen2.5-1.5B-Instruct-q4f16_1-MLC; const engine new webllm.WebLLMEngine({ model: selectedModel, initProgressCallback }); const reply await engine.chat.completions.create({ messages: [ { role: user, content: 介绍一下 WebGPU 本地推理的优势 } ] }); console.log(reply.choices[0].message.content);WebLLM 在启动时会把模型权重加载到浏览器内存加载过程可能持续几十秒到几分钟取决于模型大小和网络。这里最容易碰到的问题就是模型名写错或模型文件不匹配所以建议先查阅官方模型列表。7.3 启动顺序建议先运行第 5 节的 WebGPU 检测确认环境启动本地静态服务打开 html 页面打开浏览器 DevTools 的 Console 和 Network首次加载模型时耐心等待观察是否有报错模型跑通后再开始功能测试。8. 功能测试与效果验证部署成功只是第一步。下面按测试维度加深验证确保模型不仅“能加载”而且“能稳定用”。8.1 单轮文本生成测试测试目的确认模型能根据输入提示词生成完整回复。操作步骤在页面输入框中输入短文本比如“写一句欢迎语”点击生成观察输出是否合理。判断标准生成结果与输入主题相关没有出现乱码或空输出输出长度接近max_new_tokens设置。常见失败原因模型未加载完成接口调用过早提示词格式不符合模型指令模板浏览器内存不足导致页面崩溃。8.2 多轮对话测试测试目的验证模型能否在多轮消息中保持上下文。如果使用 WebLLM可以通过连续调用chat.completions.create并传入历史消息数组实现。如果是 Transformers.js需要确认模型是否支持对话模板并按模板拼接历史消息。操作示例const messages [ { role: user, content: 你是一个助手 }, { role: assistant, content: 好的请问需要什么帮助 }, { role: user, content: 今天天气怎么样 } ];预期结果模型能理解前两轮对话并围绕天气问题作答。如果模型答非所问优先检查历史消息格式是否与模型指令模板一致。8.3 长文本与上下文长度测试测试目的确认模型在较长输入下是否仍然稳定。输入 500 字左右的文本让模型做摘要或提取要点。观察是否出现内存快速上升推理速度是否明显变慢是否输出截断或重复内容。判断标准模型能提取出关键信息不出现崩溃。如果内存压力过大降低输入长度或换更小模型。8.4 失败时的通用排查思路现象处理方向页面白屏查看 Console 是否有 JS 报错模型加载不出检查模型名、格式、CDN 或本地文件路径生成速度慢检查是否真的走了 WebGPU还是回退到 CPU/WASM输出乱码检查量化格式和模型模板是否匹配页面崩溃模型过大或浏览器内存不足换小模型9. 接口 API 与批量任务浏览器端推理的“接口”不是 HTTP 接口而是 JavaScript API。如果要做批量任务不能直接在主线程并发跑推理需要用 Web Worker 做隔离和排队。9.1 页面内 JS API在页面内直接调用推理函数适合交互式单次生成。async function generateText(prompt) { const result await generate(prompt, { max_new_tokens: 100 }); return result[0]?.generated_text || ; } const output await generateText(你好); console.log(output);9.2 通过 Web Worker 做批量任务批量任务时主线程要避免被推理阻塞。把推理代码放到worker.js主页面通过消息传递任务。先创建一个worker.js// 这里是伪代码示例实际实现要根据推理框架调整 self.onmessage async function (e) { const { prompts, taskId } e.data; const results []; for (let i 0; i prompts.length; i) { const output await runInference(prompts[i]); results.push({ prompt: prompts[i], output }); self.postMessage({ type: progress, taskId, done: i 1, total: prompts.length }); } self.postMessage({ type: done, taskId, results }); }; async function runInference(prompt) { // 在这里调用 Transformers.js / WebLLM 的推理函数 return 推理结果${prompt}; }主页面这样调用const worker new Worker(worker.js); const taskId Date.now(); worker.postMessage({ taskId, prompts: [提示词 1, 提示词 2, 提示词 3] }); worker.onmessage (e) { if (e.data.type progress) { console.log(进度 ${e.data.done}/${e.data.total}); } else if (e.data.type done) { console.log(全部完成, e.data.results); worker.terminate(); } };批量任务的常见问题多个任务并发导致内存激增应该串行或限定并发数没有任务日志时难以定位失败项建议每条任务记录进度和错误任务中断后没有重试机制建议增加失败重试和任务状态持久化。9.3 对接服务端或外部应用浏览器本身可以作为推理端也可以把推理结果通过 fetch 提交给应用服务端。如果想把浏览器端能力嵌入桌面应用可以考虑 Electron 或 WebView如果是纯前端项目直接通过模块导出函数给业务层调用即可。10. 资源占用与性能观察性能观察是本地推理方案里最需要亲自测试的部分。不同浏览器、不同 GPU、不同模型的差异很大本文不给出绝对数字只提供方法。10.1 怎么观察 GPU 占用在 Chrome 中打开 DevTools 的 Performance 面板录制一次推理过程可以看到主线程和 Worker 线程的活动。更直接的 GPU 级观察可以打开chrome://gpu查看硬件加速状态。系统自带的任务管理器也能看到浏览器进程的 GPU 和内存占用。10.2 影响性能的主要因素因素影响模型参数量参数越多推理越慢内存占用越高量化方式量化位数越低模型越小速度越快但精度可能下降上下文长度输入输出越长计算量越大是否走 WebGPU没走 GPU 时大概率回退到 WASM/CPU速度明显下降浏览器版本较旧的浏览器可能 WebGPU 支持不完整并发数多个推理任务同时跑会互相抢占资源10.3 如何降低占用优先选择 0.5B 到 1.5B 的量化模型设置max_new_tokens上限避免生成太长时间控制上下文长度分批处理长文档使用 Web Worker 隔离推理任务页面主线程保持响应关闭不用的浏览器标签页释放内存如果模型缓存过大在存储设置中清理站点数据。11. 常见问题与排查方法下面整理了一些浏览器端 LLM 本地推理最常见的报错和排查思路。问题现象可能原因排查方式解决方案页面提示不支持 WebGPU浏览器版本过旧或驱动不支持用navigator.gpu检测查看chrome://gpu升级浏览器更新显卡驱动报错 “WebGL2 is not supported”图形接口异常或驱动问题查看chrome://gpu的 WebGL 状态开启硬件加速更新浏览器和驱动模型下载失败或超时网络环境受限CDN 不稳定查看 Network 面板确认模型请求状态将模型文件部署到本地静态服务或更换稳定 CDN推理结果为空模型未加载完成提示词格式不对查看 Console 报错确认模型加载进度等待加载完成再调用检查模型模板页面卡死或崩溃模型过大内存/显存不足打开任务管理器观察浏览器进程占用换更小模型降低上下文长度首次加载很慢模型文件较大需要下载并缓存查看 Network 面板的模型文件大小提前下载模型到本地做好缓存批量任务卡住任务并发过高或没有重试机制查看 Worker 日志加队列限制并发数增加失败重试排查时建议统一流程先看 Console再看 Network最后用chrome://gpu确认环境。顺序不要反很多问题在 Console 阶段就能定位。12. 最佳实践与合规提醒浏览器端 LLM 推理项目能不能稳定落地往往不取决于模型选得多大而是工程细节是否到位。12.1 工程实践第一次测试先跑 0.5B 小模型确认 WebGPU 链路完全正常后再换大模型页面、模型文件、输出结果分目录管理避免模型和业务代码混在一起批量任务必须加日志记录每个任务的输入、输出、耗时和错误信息推理任务放到 Worker 里执行不要在 UI 线程直接跑长任务接口服务如果暴露给局域网或公网要加访问控制限制非法调用模型文件和页面资源如果放在线上考虑加防盗链或鉴权发布或商用前对输出结果做一轮人工复核。12.2 合规提醒浏览器本地推理可以在隐私方面带来优势但不代表完全无风险。首先模型许可必须确认商用场景要检查模型的开源协议是否允许。其次如果应用会记录用户输入或输出日志即便数据没有上传到服务端也要遵守相关隐私保护要求。涉及人脸、声音、版权内容的处理必须先获得授权。任何本地部署方案都不能成为规避法律合规要求的理由。13. 总结与下一步浏览器端 LLM 本地推理最值得尝试的点是把隐私敏感任务留在本地同时用 WebGPU 获得接近原生的计算加速。最需要最先验证的功能就是第 5 节的 WebGPU 检测以及一个最小模型的文本生成这两步通了后面的功能扩展才有基础。最容易踩的坑集中在三处浏览器版本不满足 WebGPU 要求、模型文件格式与推理框架不匹配、批量任务没有用 Worker 导致页面崩溃。建议先跑通 0.5B 模型再按实际需求切换模型、优化性能和接入业务层。下一步可以继续扩展的方向包括把浏览器端推理接到自身应用的搜索或摘要流程中用 Web Worker 构建一个可复用的推理服务模块对比不同量化模型的速度和效果在局域网内把浏览器端推理能力共享给多个前端页面使用。这篇文章不是浏览器端推理的终点只帮你把 WebGPU 验证和本地推理链路跑通。剩下的事情就是选一个具体的业务场景开始测试模型效果和运行稳定性。
浏览器端跑 LLM 已经不是新鲜概念但真正想把“浏览器内本地推理”从 demo 变成可用的功能会撞上很多细节问题WebGPU 到底开没开、模型怎么加载、推理占多少显存、批量任务怎么排队、接口怎么暴露给上层应用。这篇文章就围绕Browser WebGPU Local Inference这条链路来展开先讲清楚最核心的几个判断这套方案能做什么、门槛在哪里、怎么验证 WebGPU、怎么部署一个最小可用的浏览器端本地推理环境。然后给出功能测试、接口调用、批量任务、性能观察和排错清单尽量让读者看完之后能自己动手跑通一遍。如果你正好在调研“要不要把 LLM 推理放到浏览器里”或者准备在本地做一个离线 AI 工具的原型这篇文章可以直接收藏。1. 核心能力速览先看整体能力矩阵。浏览器端 LLM 本地推理不是一个单一项目而是由 WebGPU 标准、推理框架、模型格式和前端集成方式共同组成的一类技术方案。能力项说明项目类型浏览器端 LLM 本地推理方案依赖 WebGPU 做 GPU 加速核心价值模型在浏览器本地运行文本数据不需要上传到服务端离线可用主要实现方案WebLLM、Transformers.js、llama.cpp Web 版、ONNX Runtime WebWebGPU 要求浏览器需支持 WebGPUChrome 113 默认启用Firefox / Safari 支持进度较慢本地推理门槛参数量越小的模型越容易跑通0.5B 到 1.5B 级别更适合浏览器端是否支持批量任务可以但需要配合 Web Worker 和任务队列自行实现接口 API浏览器内以 JavaScript API 为主可作为页面内模块或 Worker 服务显存占用取决于模型参数量、量化方式、上下文长度需按实际环境测试启动方式纯前端部署通常是静态页面 本地静态服务无需安装 Python 后端适合场景本地演示、隐私敏感推理、无服务器前端应用、边缘设备不适合场景服务端高并发、超长文本生成、大参数模型生产部署从材料来看这套技术路线的核心逻辑是WebGPU 把 GPU 能力暴露给浏览器推理框架把模型编译成浏览器可执行的格式最终在本地完成前向推理。理解了这条链路后面做验证和排错都会清晰很多。2. 适用场景与使用边界浏览器端本地推理最典型的优势是“数据不出设备”。这意味着对于聊天记录、企业文档、个人笔记这类隐私敏感的内容可以只在浏览器内做摘要、分类、检索增强生成不需要把内容送到远端模型接口。这种用法在内部工具和离线场景中很有价值。同时也要明确边界浏览器不是为大规模 LLM 推理设计的运行环境。页面有内存上限、GPU 资源要和渲染进程共享、模型体积受网络加载时长限制、推理速度无法和原生 CUDA 环境相比。更稳妥的判断是浏览器端适合轻量模型、短文本、交互式场景不适合追求极致吞吐或处理超长文档的生产级任务。使用边界还包括授权与合规。浏览器端在本地推理不意味着模型和数据没有约束模型权重有各自的开源许可证商用前要确认许可范围如果有用户输入数据被记录到日志或分析平台同样会涉及隐私合规。涉及人脸、声音、版权素材等内容的推理项目必须先获得合法授权。前端代码里的模型资源如果部署到公网还要考虑防盗链和访问控制避免被刷流量。3. 浏览器端 LLM 推理的技术原理要验证 WebGPU 和本地推理先要搞懂浏览器端 LLM 是从哪条链路跑起来的。3.1 WebGPU 是什么WebGPU 是 W3C “GPU for the Web” 社区组制定的 Web 图形和计算标准。它比 WebGL 更贴近现代 GPU 架构允许网页直接向 GPU 提交计算任务因此天然适合做矩阵乘法、Transformer 推理这类并行计算。对于 LLM 推理来说WebGPU 提供了两层能力一是把模型计算分配到 GPU 而不是 CPU二是使用 GPU 的并行能力加速矩阵运算。浏览器没有 WebGPU 时许多前端推理框架只能退回到 WebGL2 或 WASM而 WebGL2 主要面向图形渲染计算能力有限这也是为什么前面提到 “your browser does not support graphics api webgl 2” 这类提示时通常意味着环境没有达到推荐规格。3.2 模型怎么在浏览器里跑浏览器没法直接读取 PyTorch 权重需要先把模型转换为 Web 端可加载的格式。常见做法有两种转换为 ONNX 格式用 ONNX Runtime Web 或 Transformers.js 加载转换为 MLC 或 GGUF 格式用 WebLLM 或 llama.cpp Web 版加载。推理过程中框架会把模型参数按量化格式加载到内存再把部分计算放到 GPU。网页 UI 线程不能长时间阻塞所以真正的推理通常放在 Web Worker 中执行避免页面卡顿。3.3 本地推理的数据流一次完整的浏览器端本地推理大概是Web 页面 → 输入提示词 → Web Worker → 推理引擎 → WebGPU Compute Pipeline → 模型输出 → 回传页面整个链路不经过后端服务器。模型文件本身需要通过网络加载但一旦缓存到浏览器本地或部署在本地静态服务后续推理就不再依赖外部请求。4. 环境准备与前置条件在部署之前先检查一轮本机环境。和传统 Python 部署不同浏览器端方案对操作系统的依赖较小重点在浏览器版本、GPU 驱动、内存容量和网络加载方式。4.1 操作系统与浏览器Windows、macOS、Linux 都可以运行只要浏览器支持 WebGPU。更准确的支持矩阵建议以下面这些关键版本为参考浏览器WebGPU 支持情况Google Chrome 113较早就默认启用 WebGPU适合主力测试Microsoft Edge 113Chromium 内核WebGPU 支持情况和 Chrome 基本一致Mozilla Firefox支持进度相对滞后建议用正式版或预览版测试Apple Safari较新版本开始支持macOS 版本太低则不可用如果没有把握优先用最新版 Chrome / Edge 做验证兼容性最稳。4.2 GPU 与驱动WebGPU 需要一个能识别到的 GPU。NVIDIA、AMD、Intel 的现代集成显卡或独立显卡一般都可以但驱动版本太旧时浏览器可能无法正常创建 GPU 适配器。集成显卡跑小模型通常可行但推理速度会明显慢于独立显卡。4.3 内存与磁盘浏览器页签中的模型推理除了 GPU 显存还会占用系统内存。建议 8GB 以上内存模型文件越大内存占用越高。磁盘空间主要留给模型文件一个 1B 参数模型的量化版本可能在 500MB 到 1.5GB 之间加载时浏览器缓存还会占用额外空间。4.4 本地静态服务浏览器页面要加载本地模型文件直接用file://协议经常遇到跨域和资源加载问题。更好的做法是启动一个本地静态服务把页面和模型文件放到同一个目录下。# 在项目根目录启动静态服务端口可按需修改 python -m http.server 8080或者使用 Node 生态的静态服务工具# 需要先安装 node然后执行 npx serve .启动后访问http://localhost:8080即可打开页面。5. 验证浏览器 WebGPU 支持这次主题的关键动作就是“验证 WebGPU”。不要等到模型加载报错才检查先把 WebGPU 环境确认清楚。5.1 用一段代码判断创建一个index.html加入下面的检测脚本。它通过navigator.gpu判断浏览器是否暴露 WebGPU 接口再通过requestAdapter()确认能否拿到 GPU 适配器。!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 titleWebGPU 检测/title /head body h1WebGPU 检测/h1 pre idlog正在检测.../pre script async function checkWebGPU() { const logEl document.getElementById(log); if (!navigator.gpu) { logEl.textContent 当前浏览器不支持 WebGPU请使用较新版本的 Chrome / Edge。; return; } const adapter await navigator.gpu.requestAdapter(); if (!adapter) { logEl.textContent 浏览器支持 WebGPU但没有找到可用 GPU 适配器。; return; } const info adapter.info || {}; const vendor info.vendor || unknown; const architecture info.architecture || unknown; logEl.textContent WebGPU 可用适配器${vendor} / ${architecture}; } checkWebGPU(); /script /body /html在浏览器中打开这个页面。如果输出“WebGPU 可用”说明环境没问题如果提示不支持或没有适配器要回到第 4 节检查浏览器版本和驱动。5.2 通过浏览器内部页面确认Chromium 内核浏览器可以直接访问chrome://gpu在页面里搜索 “WebGPU” 或 “WebGL”查看对应状态。如果显示硬件加速已启用说明 GPU 可以被识别如果显示软件渲染说明驱动或系统环境有问题。5.3 判定标准检测结果结论页面显示 WebGPU 可用可以继续做模型推理测试页面显示 WebGL2 不支持浏览器或 GPU 环境不满足先升级浏览器和驱动页面显示无可用适配器GPU 被禁用或驱动过旧需要检查系统6. 主流浏览器端推理方案对比在同一个浏览器环境里可以选不同框架来跑本地推理。下面几个方案各有侧重。方案主要特点模型格式适合人群Transformers.jsHugging Face 生态任务类型丰富ONNX前端开发者快速集成WebLLMMLC.AI 维护专门针对 LLM 推理优化MLC需要完整聊天/生成流程llama.cpp Web 版复用 C 推理能力体积可控GGUF已有 GGUF 模型想转 Web 端ONNX Runtime Web通用推理运行时ONNX已有 ONNX 部署栈的团队从易用角度看Transformers.js 比较适合前端新手加载模型和调用 pipeline 都很直接。WebLLM 则更贴近 OpenAI 风格的 API适合做聊天应用。GGUF 方案适合已经熟悉 llama.cpp 生态、想快速把本地模型 Web 化的开发者。7. 本地部署与启动最小可运行 Demo下面给两个最小部署示例一个用 Transformers.js一个用 WebLLM。代码可以放在本地静态服务目录然后通过浏览器访问测试。7.1 使用 Transformers.js 运行文本生成Transformers.js 可以直接通过 CDN 或 npm 包引入。下面的示例使用 CDN 写法模型名需要根据模型库实际情况替换。!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 titleTransformers.js 浏览器推理测试/title /head body h1浏览器端 LLM 推理测试/h1 textarea idinput你好请用一句话介绍你自己。/textarea button idrun生成/button pre idoutput等待输入.../pre script typemodule import { pipeline } from https://cdn.jsdelivr.net/npm/huggingface/transformers2.17.2; const outputEl document.getElementById(output); const inputEl document.getElementById(input); const runBtn document.getElementById(run); // 模型名需要按模型库实际情况替换建议第一次使用较小模型 const generate await pipeline(text-generation, Xenova/qwen2.5-0.5b-instruct); runBtn.addEventListener(click, async () { const text inputEl.value.trim(); if (!text) return; outputEl.textContent 生成中...; const result await generate(text, { max_new_tokens: 100, temperature: 0.7 }); outputEl.textContent result[0]?.generated_text || JSON.stringify(result); }); /script /body /html启动本地静态服务后打开页面点击生成按钮。首次加载需要下载模型进度可以在浏览器 Network 面板观察模型缓存后后续加载会快很多。7.2 使用 WebLLM 运行聊天式推理WebLLM 的接口更接近 OpenAI SDK适合做聊天应用。下面的示例是一种常见调用方式实际模型名和初始化流程要以项目文档为准。import * as webllm from mlc-ai/web-llm; const initProgressCallback (report) { console.log(加载进度, report); }; const selectedModel Qwen2.5-1.5B-Instruct-q4f16_1-MLC; const engine new webllm.WebLLMEngine({ model: selectedModel, initProgressCallback }); const reply await engine.chat.completions.create({ messages: [ { role: user, content: 介绍一下 WebGPU 本地推理的优势 } ] }); console.log(reply.choices[0].message.content);WebLLM 在启动时会把模型权重加载到浏览器内存加载过程可能持续几十秒到几分钟取决于模型大小和网络。这里最容易碰到的问题就是模型名写错或模型文件不匹配所以建议先查阅官方模型列表。7.3 启动顺序建议先运行第 5 节的 WebGPU 检测确认环境启动本地静态服务打开 html 页面打开浏览器 DevTools 的 Console 和 Network首次加载模型时耐心等待观察是否有报错模型跑通后再开始功能测试。8. 功能测试与效果验证部署成功只是第一步。下面按测试维度加深验证确保模型不仅“能加载”而且“能稳定用”。8.1 单轮文本生成测试测试目的确认模型能根据输入提示词生成完整回复。操作步骤在页面输入框中输入短文本比如“写一句欢迎语”点击生成观察输出是否合理。判断标准生成结果与输入主题相关没有出现乱码或空输出输出长度接近max_new_tokens设置。常见失败原因模型未加载完成接口调用过早提示词格式不符合模型指令模板浏览器内存不足导致页面崩溃。8.2 多轮对话测试测试目的验证模型能否在多轮消息中保持上下文。如果使用 WebLLM可以通过连续调用chat.completions.create并传入历史消息数组实现。如果是 Transformers.js需要确认模型是否支持对话模板并按模板拼接历史消息。操作示例const messages [ { role: user, content: 你是一个助手 }, { role: assistant, content: 好的请问需要什么帮助 }, { role: user, content: 今天天气怎么样 } ];预期结果模型能理解前两轮对话并围绕天气问题作答。如果模型答非所问优先检查历史消息格式是否与模型指令模板一致。8.3 长文本与上下文长度测试测试目的确认模型在较长输入下是否仍然稳定。输入 500 字左右的文本让模型做摘要或提取要点。观察是否出现内存快速上升推理速度是否明显变慢是否输出截断或重复内容。判断标准模型能提取出关键信息不出现崩溃。如果内存压力过大降低输入长度或换更小模型。8.4 失败时的通用排查思路现象处理方向页面白屏查看 Console 是否有 JS 报错模型加载不出检查模型名、格式、CDN 或本地文件路径生成速度慢检查是否真的走了 WebGPU还是回退到 CPU/WASM输出乱码检查量化格式和模型模板是否匹配页面崩溃模型过大或浏览器内存不足换小模型9. 接口 API 与批量任务浏览器端推理的“接口”不是 HTTP 接口而是 JavaScript API。如果要做批量任务不能直接在主线程并发跑推理需要用 Web Worker 做隔离和排队。9.1 页面内 JS API在页面内直接调用推理函数适合交互式单次生成。async function generateText(prompt) { const result await generate(prompt, { max_new_tokens: 100 }); return result[0]?.generated_text || ; } const output await generateText(你好); console.log(output);9.2 通过 Web Worker 做批量任务批量任务时主线程要避免被推理阻塞。把推理代码放到worker.js主页面通过消息传递任务。先创建一个worker.js// 这里是伪代码示例实际实现要根据推理框架调整 self.onmessage async function (e) { const { prompts, taskId } e.data; const results []; for (let i 0; i prompts.length; i) { const output await runInference(prompts[i]); results.push({ prompt: prompts[i], output }); self.postMessage({ type: progress, taskId, done: i 1, total: prompts.length }); } self.postMessage({ type: done, taskId, results }); }; async function runInference(prompt) { // 在这里调用 Transformers.js / WebLLM 的推理函数 return 推理结果${prompt}; }主页面这样调用const worker new Worker(worker.js); const taskId Date.now(); worker.postMessage({ taskId, prompts: [提示词 1, 提示词 2, 提示词 3] }); worker.onmessage (e) { if (e.data.type progress) { console.log(进度 ${e.data.done}/${e.data.total}); } else if (e.data.type done) { console.log(全部完成, e.data.results); worker.terminate(); } };批量任务的常见问题多个任务并发导致内存激增应该串行或限定并发数没有任务日志时难以定位失败项建议每条任务记录进度和错误任务中断后没有重试机制建议增加失败重试和任务状态持久化。9.3 对接服务端或外部应用浏览器本身可以作为推理端也可以把推理结果通过 fetch 提交给应用服务端。如果想把浏览器端能力嵌入桌面应用可以考虑 Electron 或 WebView如果是纯前端项目直接通过模块导出函数给业务层调用即可。10. 资源占用与性能观察性能观察是本地推理方案里最需要亲自测试的部分。不同浏览器、不同 GPU、不同模型的差异很大本文不给出绝对数字只提供方法。10.1 怎么观察 GPU 占用在 Chrome 中打开 DevTools 的 Performance 面板录制一次推理过程可以看到主线程和 Worker 线程的活动。更直接的 GPU 级观察可以打开chrome://gpu查看硬件加速状态。系统自带的任务管理器也能看到浏览器进程的 GPU 和内存占用。10.2 影响性能的主要因素因素影响模型参数量参数越多推理越慢内存占用越高量化方式量化位数越低模型越小速度越快但精度可能下降上下文长度输入输出越长计算量越大是否走 WebGPU没走 GPU 时大概率回退到 WASM/CPU速度明显下降浏览器版本较旧的浏览器可能 WebGPU 支持不完整并发数多个推理任务同时跑会互相抢占资源10.3 如何降低占用优先选择 0.5B 到 1.5B 的量化模型设置max_new_tokens上限避免生成太长时间控制上下文长度分批处理长文档使用 Web Worker 隔离推理任务页面主线程保持响应关闭不用的浏览器标签页释放内存如果模型缓存过大在存储设置中清理站点数据。11. 常见问题与排查方法下面整理了一些浏览器端 LLM 本地推理最常见的报错和排查思路。问题现象可能原因排查方式解决方案页面提示不支持 WebGPU浏览器版本过旧或驱动不支持用navigator.gpu检测查看chrome://gpu升级浏览器更新显卡驱动报错 “WebGL2 is not supported”图形接口异常或驱动问题查看chrome://gpu的 WebGL 状态开启硬件加速更新浏览器和驱动模型下载失败或超时网络环境受限CDN 不稳定查看 Network 面板确认模型请求状态将模型文件部署到本地静态服务或更换稳定 CDN推理结果为空模型未加载完成提示词格式不对查看 Console 报错确认模型加载进度等待加载完成再调用检查模型模板页面卡死或崩溃模型过大内存/显存不足打开任务管理器观察浏览器进程占用换更小模型降低上下文长度首次加载很慢模型文件较大需要下载并缓存查看 Network 面板的模型文件大小提前下载模型到本地做好缓存批量任务卡住任务并发过高或没有重试机制查看 Worker 日志加队列限制并发数增加失败重试排查时建议统一流程先看 Console再看 Network最后用chrome://gpu确认环境。顺序不要反很多问题在 Console 阶段就能定位。12. 最佳实践与合规提醒浏览器端 LLM 推理项目能不能稳定落地往往不取决于模型选得多大而是工程细节是否到位。12.1 工程实践第一次测试先跑 0.5B 小模型确认 WebGPU 链路完全正常后再换大模型页面、模型文件、输出结果分目录管理避免模型和业务代码混在一起批量任务必须加日志记录每个任务的输入、输出、耗时和错误信息推理任务放到 Worker 里执行不要在 UI 线程直接跑长任务接口服务如果暴露给局域网或公网要加访问控制限制非法调用模型文件和页面资源如果放在线上考虑加防盗链或鉴权发布或商用前对输出结果做一轮人工复核。12.2 合规提醒浏览器本地推理可以在隐私方面带来优势但不代表完全无风险。首先模型许可必须确认商用场景要检查模型的开源协议是否允许。其次如果应用会记录用户输入或输出日志即便数据没有上传到服务端也要遵守相关隐私保护要求。涉及人脸、声音、版权内容的处理必须先获得授权。任何本地部署方案都不能成为规避法律合规要求的理由。13. 总结与下一步浏览器端 LLM 本地推理最值得尝试的点是把隐私敏感任务留在本地同时用 WebGPU 获得接近原生的计算加速。最需要最先验证的功能就是第 5 节的 WebGPU 检测以及一个最小模型的文本生成这两步通了后面的功能扩展才有基础。最容易踩的坑集中在三处浏览器版本不满足 WebGPU 要求、模型文件格式与推理框架不匹配、批量任务没有用 Worker 导致页面崩溃。建议先跑通 0.5B 模型再按实际需求切换模型、优化性能和接入业务层。下一步可以继续扩展的方向包括把浏览器端推理接到自身应用的搜索或摘要流程中用 Web Worker 构建一个可复用的推理服务模块对比不同量化模型的速度和效果在局域网内把浏览器端推理能力共享给多个前端页面使用。这篇文章不是浏览器端推理的终点只帮你把 WebGPU 验证和本地推理链路跑通。剩下的事情就是选一个具体的业务场景开始测试模型效果和运行稳定性。
老软件在现代电脑上的兼容运行指南)
