WebLLM：把大语言模型装进浏览器
想在网页里跑 LLM，传统答案只有两条路：要么调云端 API（数据出境、按 token 付费、断网即废），要么本地起服务再暴露接口（部署麻烦、跨设备困难）。MLC AI（CMU 系团队，Apache TVM 背后的力量）开源的 WebLLM 给出了第三条路——高性能浏览器内 LLM 推理引擎：模型直接在浏览器里运行，WebGPU 硬件加速，零服务器支持，API 完全兼容 OpenAI。Llama 3、Qwen、Phi、Gemma、Mistral 等主流开源模型开箱即用，配合 Web Worker 不卡 UI，还有论文背书的推理优化。它让"完全离线、隐私内生"的网页 AI 助手成为现实。参考 GitHub 仓库 与 在线 Demo。
1、概述：WebLLM 是什么
官方定位："High-Performance In-Browser LLM Inference Engine"（高性能浏览器内 LLM 推理引擎）。它是 MLC LLM 的姊妹项目——MLC LLM 负责"跨硬件通用部署 LLM"，WebLLM 专门攻"浏览器这块硬件"：
定位 浏览器内 LLM 推理引擎，WebGPU 硬件加速
出品 MLC AI（MLC LLM 姊妹项目，CMU 系，有论文 arXiv:2412.15803）
架构 零服务器：一切在浏览器里跑，无后端支持
API 完全兼容 OpenAI API（streaming/JSON 模式/函数调用 WIP）
模型 Llama 3 / Qwen 通义千问 / Phi 3 / Gemma / Mistral 家族
分发 npm 包 @mlc-ai/web-llm 或 CDN 直接 import
工程特性 Web Worker / Service Worker / Chrome 扩展支持
自定义 MLC 格式自定义模型可自行编译集成
体验 chat.webllm.ai 在线可玩核心要点：
1. 无服务器：推理发生在用户设备的 GPU 上，服务器只静态托管网页
2. OpenAI API 全兼容：会调 OpenAI 就会用 WebLLM，迁移成本近乎零
3. WebGPU 加速 + WebAssembly 结构化生成，性能是"能用"而非"演示"
4. 学术出身：配套论文 + MLC LLM 生态，模型编译管线成熟
2、核心价值：隐私、离线与零成本
把 LLM 搬进浏览器不只是技术炫技，它一次性解锁三个传统方案给不了的性质：
性质 原理 对比云端 API
------------------------------------------------------------------------
隐私内生 对话全程不出浏览器 数据出境/被记录
无网络传输、无服务端日志 合规成本高
完全离线 模型缓存后断网可用 断网即废
飞机上、内网里照样跑 内网无法部署
零边际成本 推理用用户自己的 GPU 按 token 计费
服务端零计算开销 流量越大越贵
// 附加红利：
// 服务端只托管静态网页 → 无并发压力、无 GPU 采购
// 适合高并发"免费 AI 功能"场景（如网站智能助手）核心要点：
1. 隐私是架构性质而非承诺——数据物理上没有出设备的通道
2. 模型经浏览器缓存（Cache API 等），二次访问离线可跑
3. 推理成本转嫁给用户设备——服务端只有静态资源开销
4. 高并发场景友好：一万用户同时聊，服务器毫无感觉
3、快速上手：三步跑起浏览器 Chatbot
装包（或 CDN 一行 import）→ CreateMLCEngine 加载模型 → OpenAI 风格调用。README 官方示例：
// ① 安装：npm / yarn / pnpm 任选，或 CDN 免安装
npm install @mlc-ai/web-llm
// CDN 方式（jsfiddle/codepen 可直接跑）：
// import * as webllm from "https://esm.run/@mlc-ai/web-llm";
// ② 创建引擎并加载模型（首次需下载，注意异步与进度回调）
import { CreateMLCEngine } from "@mlc-ai/web-llm";
const initProgressCallback = (initProgress) => {
console.log(initProgress); // 加载进度（0~1 与文本）
};
const selectedModel = "Llama-3.1-8B-Instruct-q4f32_1-MLC";
const engine = await CreateMLCEngine(
selectedModel,
{ initProgressCallback: initProgressCallback }, // engineConfig
);// ③ 对话补全：与 OpenAI API 完全同构
const messages = [
{ role: "system", content: "You are a helpful AI assistant." },
{ role: "user", content: "Hello!" },
];
const reply = await engine.chat.completions.create({ messages });
console.log(reply.choices[0].message);
console.log(reply.usage); // token 用量也有核心要点：
1. CreateMLCEngine(模型, 配置)：工厂函数 = 同步建实例 + 异步载模型
2. 首次加载要下载模型权重，务必用 initProgressCallback 反馈进度
3. 也可拆开：new MLCEngine() 同步 + engine.reload(model) 异步
4. chat.completions.create 与 OpenAI SDK 同构到参数级（model 参数除外）
4、流式输出与结构化 JSON
两个生产级特性让浏览器 LLM 从"能聊"走向"能用"：
// ① 流式输出：stream: true，返回 AsyncGenerator
const chunks = await engine.chat.completions.create({
messages,
temperature: 1,
stream: true, // <-- 开启流式
stream_options: { include_usage: true },
});
let reply = "";
for await (const chunk of chunks) {
reply += chunk.choices[0]?.delta?.content || "";
console.log(reply); // 逐 token 上屏
if (chunk.usage) console.log(chunk.usage); // 仅最后一个 chunk 带 usage
}
// ② 结构化 JSON 生成（JSON mode）
// 按 JSON Schema 约束输出，保证可解析
// 实现位于模型库的 WebAssembly 部分——性能最优
// 试玩：HuggingFace 上的 WebLLM JSON Playground
// 可自定义 JSON schema 直接体验核心要点：
1. stream: true 返回 AsyncGenerator，for await 逐 token 消费
2. stream_options.include_usage 让最后一个 chunk 携带用量
3. JSON 模式按 schema 硬约束输出——结构化数据抽取的保障
4. JSON 约束在 WASM 层实现，性能与正确性兼得
5、模型生态：内置家族与自定义编译
内置模型覆盖主流开源家族，完整清单在 prebuiltAppConfig.model_list（src/config.ts），更多模型可自行编译：
// 内置模型家族（节选）
Llama Llama 3 / Llama 2 / Hermes-2-Pro-Llama-3
Phi Phi 3 / Phi 2 / Phi 1.5（小钢炮系列）
Gemma Gemma-2B（Google 轻量）
Mistral Mistral-7B-v0.3 / Hermes-2-Pro / NeuralHermes /
OpenHermes-2.5（社区微调版）
Qwen Qwen2 0.5B / 1.5B / 7B（通义千问，小杯到大杯）
// 模型标识格式（版本-精度-MLC）：
"Llama-3.1-8B-Instruct-q4f32_1-MLC"
// q4f32_1 = 权重 4bit 量化 / 激活 32bit —— 浏览器显存友好
// 需要更多模型？
// ① 官方提 issue 申请新模型
// ② 自定义模型：用 MLC LLM 编译流程把自己的模型
// 转成 MLC 格式，注册进 appConfig 即可加载
// 完整模型列表：mlc.ai/models核心要点：
1. Qwen 全系支持——中文场景的浏览器部署有了趁手选择
2. 模型名带量化后缀（q4f32_1），按设备显存挑精度
3. 自定义模型走 MLC LLM 编译管线，注册 appConfig 即用
4. 小参数量模型（0.5B~3B）在集显设备也能流畅跑
6、缓存后端：模型存哪、二次加载多快
模型动辄几个 GB，浏览器缓存策略直接决定二次体验。WebLLM 提供四种缓存后端可选：
// 通过 AppConfig.cacheBackend 指定
"cache" 浏览器 Cache API（默认）
"indexeddb" 浏览器 IndexedDB
"opfs" Origin Private File System（OPFS 私有文件系统）
"cross-origin" 实验性：Chrome Cross-Origin Storage 扩展后端
（需装扩展，未装则自动回落默认缓存）
// 示例：切换缓存后端
import { CreateMLCEngine, prebuiltAppConfig } from "@mlc-ai/web-llm";
const appConfig = { ...prebuiltAppConfig, cacheBackend: "cross-origin" };
const engine = await CreateMLCEngine(
"Llama-3.1-8B-Instruct-q4f32_1-MLC", { appConfig });
// OPFS 细节：
// opfsAccessMode 可设 "auto"/"sync"/"async"（默认 async）
// sync access handles 支持时性能更佳
// 注意：
// 选 opfs 但环境不支持 → 缓存操作报 OPFS 可用性错误
// cross-origin 后端暂不支持编程式删除 tensor 缓存（扩展管理）核心要点：
1. 默认 Cache API 开箱即用；OPFS 适合大模型存储
2. 首次下载耗时可观，缓存后二次进入秒级可用
3. cross-origin 实验后端可跨站点共享模型缓存（装扩展）
4. 缓存就是"离线可用"的物理基础——存下来的就是你的
7、进阶：Worker 架构与 Chrome 扩展
推理是重计算，放主线程会卡 UI。WebLLM 原生支持把引擎搬进 Worker，还能做浏览器扩展：
// ① Dedicated Web Worker：计算不干扰 UI
// worker.ts —— worker 线程里跑 handler
import { WebWorkerMLCEngineHandler } from "@mlc-ai/web-llm";
const handler = new WebWorkerMLCEngineHandler();
self.onmessage = (msg: MessageEvent) => handler.onmessage(msg);
// 主线程 —— 创建 WorkerEngine，消息转发到 worker
// 重计算在 worker 线程，页面滚动/动画不卡
// ② Service Worker：模型生命周期管理更灵活
// 适合 PWA 场景：后台保活、跨页面共享引擎
// ③ Chrome 扩展支持
// 官方提供基础与进阶扩展示例
// → 把"网页内 AI"做成增强浏览器能力的常驻工具
// 使用模式总结：
// 简单 demo → 主线程直接 CreateMLCEngine
// 正经应用 → Web Worker 隔离计算
// PWA/离线应用 → Service Worker
// 浏览器增强 → Chrome 扩展核心要点：
1. WebWorkerMLCEngineHandler 在 worker 线程宿主引擎
2. 主线程用 Worker 版 Engine 以消息通信驱动推理
3. 生成过程不占 UI 线程——聊天时页面照常丝滑
4. Service Worker/扩展路线拓展了"AI 常驻浏览器"的想象空间
8、总结
WebLLM 证明了"浏览器即 AI 运行时"不是概念演示：WebGPU 加速 + OpenAI 兼容 API + 成熟模型生态 + 工程级缓存与 Worker 方案，让 LLM 网页应用可以做到零服务器、全隐私、可离线。
关键要点：
- 定位：高性能浏览器内 LLM 推理引擎，WebGPU 加速，零服务器
- API：完全兼容 OpenAI——streaming / JSON 模式 / logit 控制 / 种子
- 模型：Llama 3 / Qwen2 / Phi 3 / Gemma / Mistral 内置，MLC 格式可自定义
- 上手：CreateMLCEngine + chat.completions.create，CDN 一行可跑
- 缓存：Cache API / IndexedDB / OPFS / 跨源实验后端四种可选
- 工程：Web Worker / Service Worker / Chrome 扩展原生支持
- 出身：MLC LLM 姊妹项目，配套论文 arXiv:2412.15803
对于要做隐私敏感场景（医疗/法律/企业内网问答）、离线可用的网页 AI 助手，或想给网站加"零服务器成本 AI 功能"的开发者而言，WebLLM 是目前浏览器端 LLM 的事实标准——它把"AI 功能"变成了一种可以随网页静态分发的资源：用户打开页面、模型缓存到本地，之后的每次对话都在自己的 GPU 上完成。从 chat.webllm.ai 的在线 Demo 感受一次"断网还能聊"，再用 CDN 一行 import 在 jsfiddle 里写出你的第一个浏览器 Chatbot——当你的网页在飞行模式下依然对答如流，你会真切感到：LLM 的部署边界，已经被推到了"每个浏览器"。
