在浏览器中运行 LLM — WebLLM 完整指南

介绍

"我想使用 LLM，但管理 API 密钥太麻烦了……" "我不想把用户输入发送到云端……"

WebLLM 可以同时解决这两个问题。

WebLLM 是一个直接在浏览器中运行 LLM——完全无服务器、无后端的高性能推理引擎。与 ChatGPT 或 Claude 等基于云的 AI 服务不同，所有推理处理完全在用户设备上完成。

本文详细介绍 WebLLM 的架构、特性和实现方法。

什么是 WebLLM？

WebLLM（@mlc-ai/web-llm）是由 MLC-AI 项目开发的开源 JavaScript 库。它主要由来自卡内基梅隆大学、上海交通大学和 NVIDIA 的研究人员构建，作为论文 "WebLLM: A High-Performance In-Browser LLM Inference Engine" 于 2024 年底发布。

简而言之：

一个将浏览器变成 LLM 运行环境的框架。

主要特性

工作原理

WebLLM 能够提供高性能的原因在于它充分利用了最新的浏览器技术。

1. WebGPU — GPU 加速

WebGPU 是用于从浏览器进行底层 GPU 访问的新型 Web API。与旧版 WebGL 不同，它专为通用 GPU 计算（GPGPU）设计，能够实现 LLM 所需的高速矩阵运算。

WebLLM 内部使用 Apache TVM 和 MLC-LLM 针对 WebGPU 优化模型计算图。还融入了 PagedAttention 和 FlashAttention 等最先进的推理优化技术。

特别重要的是设备抽象的优势。传统的本机实现需要为每个供应商编写单独的代码库——CUDA（NVIDIA）、Metal（Apple）等——但使用 WebGPU，单一实现可以针对多种 GPU。

graph LR
    A[传统方法] --> B[CUDA 实现]
    A --> C[Metal 实现]
    A --> D[OpenCL 实现]
    A --> E[...]
    
    F[WebLLM 方法] --> G[单一 WebGPU 支持所有 GPU ✨]

2. WebAssembly（Wasm）— CPU 回退

当 GPU 不可用或需要辅助 CPU 计算时，WebAssembly 发挥重要作用。由于它可以在浏览器中以接近本机的速度执行用 C/C++ 编写的高级计算代码，因此能够高效处理 CPU 侧的某些模型处理。

3. Web Workers — UI 线程隔离

LLM 推理极度耗费资源。在主线程上运行会冻结 UI。WebLLM 在 Web Worker 上运行推理处理，保持用户界面的响应性。

graph LR
    A[主线程] <-->|消息传递| B[Web Worker]
    A --> C[UI 更新]
    B --> D[LLM 推理]

4. Cache Storage — 首次加载后快速启动

LLM 模型通常大小从数百兆字节到数吉字节不等。WebLLM 将下载的模型保存在浏览器的 Cache Storage 中，因此后续启动可以从缓存立即加载。

架构概述

WebLLM 的架构由三个主要组件组成。

graph TB
    A[Web 应用程序<br/>类 OpenAI 的 JavaScript API]
    B[MLCEngine Web Worker<br/>将繁重的推理从 UI 线程卸载]
    C[WebGPU / WebAssembly<br/>GPU 加速 / CPU 辅助计算]
    
    A --> B
    B --> C

性能

根据论文"WebLLM: A High-Performance In-Browser LLM Inference Engine"（arXiv:2412.15803）的评估结果：

在 Apple MacBook Pro M3 Max 上对比 WebLLM（WebGPU + JavaScript/Wasm）与 MLC-LLM（Metal + Python/C++）时，WebLLM 保留了最高 80% 的本机解码速度。

尽管在浏览器中运行，能够实现本机性能的最高 80%，表明它已达到实用水平。

支持的模型

WebLLM 支持广泛的模型（部分示例）：

• Llama 3.1 / 3.2 系列
• Phi 3.5 / 4 系列
• Gemma 2 系列
• Mistral 系列
• Qwen 2.5 系列

提供多种量化格式（如 q4f16_1 和 q4f32_1），允许根据设备内存容量进行选择。

实现

我使用 WebLLM 构建了一个聊天应用程序。以下是运行中的截图：

一个完全在浏览器中运行的私人 AI 助手。所有处理在本地执行。

让我们来看看如何实现这样的应用程序。

安装

npm install @mlc-ai/web-llm

基本聊天实现

import * as webllm from "@mlc-ai/web-llm";

async function main() {
  // 选择模型（量化版本）
  const selectedModel = "Llama-3.2-3B-Instruct-q4f16_1-MLC";

  // 初始化引擎（通过回调获取下载进度）
  const engine = await webllm.CreateMLCEngine(selectedModel, {
    initProgressCallback: (progress) => {
      console.log(`Loading: ${Math.round(progress.progress * 100)}%`);
    },
  });

  // 使用兼容 OpenAI 的 API 进行聊天
  const reply = await engine.chat.completions.create({
    messages: [
      { role: "system", content: "You are a helpful assistant." },
      { role: "user", content: "Tell me about WebLLM." },
    ],
  });

  console.log(reply.choices[0].message.content);
}

main();

Web Worker 实现（推荐）

为了防止 UI 冻结，生产环境中推荐使用 Web Workers。

import * as webllm from "@mlc-ai/web-llm";

const handler = new webllm.WebWorkerMLCEngineHandler();
self.onmessage = (msg) => {
  handler.onmessage(msg);
};

import * as webllm from "@mlc-ai/web-llm";

const selectedModel = "Llama-3.2-3B-Instruct-q4f16_1-MLC";

// 创建 Web Worker 引擎
const engine = new webllm.WebWorkerMLCEngine(
  new Worker(new URL("./worker.js", import.meta.url), { type: "module" })
);

// 设置进度回调
engine.setInitProgressCallback((progress) => {
  console.log(`Loading: ${Math.round(progress.progress * 100)}%`);
});

// 加载模型
await engine.reload(selectedModel);

// 然后像平常一样调用 engine.chat.completions.create()

流式支持

const stream = await engine.chat.completions.create({
  messages: [{ role: "user", content: "Tell me about Mount Fuji" }],
  stream: true,
});

for await (const chunk of stream) {
  const delta = chunk.choices[0]?.delta?.content ?? "";
  process.stdout.write(delta); // 实时输出
}

注意事项与限制

虽然 WebLLM 是一项极具吸引力的技术，但了解其当前限制非常重要。

WebGPU 浏览器支持（截至 2026 年 2 月）：情况在 2025 年底得到了显著改善，现在所有四大主流浏览器——Chrome、Edge、Firefox 和 Safari——都默认启用了 WebGPU。但是，支持程度因平台而异。

由于支持还取决于 GPU 硬件和驱动程序状态，仍建议通过 navigator.gpu 进行特性检测并实现 WebAssembly 回退。

硬件加速设置
即使在配备 GPU 的机器上，浏览器设置也可能将渲染限制为软件模式。如果 chrome://gpu 显示 WebGPU"仅软件"：

1. 启用硬件加速：在 chrome://settings/system 中开启"可用时使用硬件加速"
2. 禁用 GPU 黑名单：在 chrome://flags 中启用"覆盖软件渲染列表"
3. 完全重启浏览器：关闭所有窗口后重新启动

配置后，在 chrome://gpu 验证 WebGPU 状态显示为"硬件加速"。

初始下载量大
模型必须在首次启动时下载。即使是 Llama-3.2-3B 的量化版本也约为 2–3 GB，因此进度指示器的实现对良好的用户体验至关重要。

模型不跨域共享
缓存的模型仅在同一源内共享。在不同的 Web 应用上使用同一模型需要单独下载。

净化 LLM 输出
将生成的文本直接插入 DOM 会带来 XSS 风险。始终使用 DOMPurify 等库净化输出。

// ❌ 危险
element.innerHTML = llmOutput;

// ✅ 安全
element.innerHTML = DOMPurify.sanitize(llmOutput);

使用场景

以下是 WebLLM 特别有效的场景。

注重隐私的应用
在处理敏感信息的领域——如医疗、法律和金融——数据不被发送到云端至关重要。WebLLM 在设备上完成所有处理。

支持离线的应用
一旦模型下载完成，就可以在没有互联网连接的情况下提供 AI 功能。结合 PWA，你可以构建离线工作的 AI 助手。

降低成本
由于消除了 API 调用费用，对于高使用量的应用可以期待显著的成本节省。

混合推理
一种混合架构——轻量级任务使用浏览器内 WebLLM，较重的任务使用云 API——也是一种有效的方法。

未来展望

WebGPU 规范仍在不断演进，subgroups 等新特性的添加预期将带来进一步的性能提升。对 Apple Silicon 的 Metal 后端和移动设备的增强支持也值得期待。

随着浏览器作为边缘 AI 执行环境逐渐成熟，WebLLM 有望成为开发注重隐私的 AI 应用的标准选择。

总结