WebLLM 实战：在 Chrome 里跑通 Llama-3.2-1B，附 M1/MacBook/Edge 113 三平台填坑记录

2026/9/32 分钟阅读

WebLLM 实战：在浏览器里跑通本地 LLM

第一次加载 Llama-3.2-1B 要等 8 秒，进度条卡在 92% 是正常现象，别慌，那是模型权重正在解压。WebLLM 让大模型直接在浏览器里跑，数据不用出境，也不用给云厂商交月租。但真到了生产环境，几个坑得提前知道。

为什么选 WebLLM

传统 API 调用要把数据发给第三方，敏感业务不敢用。WebLLM 是 MLC AI 社区的项目，把模型编译成 Wasm 或 WebGPU 格式，直接用你电脑的显卡算。企业定制开发时，内部知识库问答、代码审查这类场景，模型跑在本地，隐私这块确实省心。

不过，别以为装上就能用。知识库问答？先搞定 PDF 提取——WebLLM 不管这个，你得自己上 pdf.js + unstructured，最后发现 chunk 切太大，显存直接爆。代码补全延迟高到没法用，也是因为本地算力有限。

快速上手：第一个本地聊天 Demo

先装包：

npm install webllm

TypeScript 项目里初始化引擎：

import { CreateMLCEngine } from "webllm";

async function main() {
  // 自动检测 WebGPU，加载量化模型
  const engine = await CreateMLCEngine("Llama-3.2-1B-Instruct-Q4F16_1-MLC");
  
  const response = await engine.chat.completions.create({
    model: "Llama-3.2-1B-Instruct",
    messages: [{ role: "user", content: "用一句话解释量子计算" }],
    stream: true,
  });

  for await (const chunk of response) {
    process.stdout.write(chunk.choices[0]?.delta.content || "");
  }
}

main();

注意模型名必须有 -MLC 后缀，这是编译优化过的版本。Q4F16 是 4-bit 量化。实测 Llama-3.2-1B 在 Mac M1 上显存占用从 2.1GB 降到 780MB，但中文续写偶尔漏字，别指望它完全不出错。

性能优化：让推理跑起来

浏览器 GPU 资源就那么多，优化得靠细节。预热模型能躲过首次加载的 8 秒黑屏；切换模型前记得调用 engine.release()——否则 GPU 内存不释放，Chrome 任务管理器里显存会持续上涨，刷新页面也清不掉；别贪大，1B 模型在 8GB 显存上跑得稳，3B 就开始抖，首 token 延迟在 M1 MacBook 上大约 1.2s，再往后就慢了。

预加载代码长这样：

import { PreloadMLCEngine } from "webllm";

PreloadMLCEngine(["Llama-3.2-1B-Instruct-Q4F16_1-MLC"], {
  progressCallback: (msg) => console.log(msg),
});

常见坑与排查

很多开发者跑不通，是因为浏览器版本不够。Chrome 113 起默认开启 WebGPU，但 macOS 用户建议升到 117+；Linux 下 AMD 显卡可能要等到 120 才不报 ‘device lost’ 错误。

还有个高频问题是 CORS。模型文件如果托管在自定义 CDN，服务器得返回正确的 CORS 头，否则浏览器会拦截权重加载。我们给客户部署时，在 Edge 113 上跑不通，最后发现是显卡驱动太旧，更新一下就好了。

下一步

基础跑通后，可以探索自定义编译流程，适配更多小众模型。也可以集成到 Electron 里，利用桌面端的 GPU 调度优势，稳定性比纯网页好不少。