WebLLM 最终指南：使用 WebGPU 的浏览器内 LLM

大型语言模型（LLMs）已成为 AI 开发的主流，但大多数生态仍依赖大型云服务器。WebLLM 通过在用户浏览器内完全运行现代 LLM，利用 WebGPU 进行实时推理并保障隐私，改变了这一范式。

在本指南中，我们将：

1. 演示如何安装并设置 WebLLM。
2. 加载并运行热门模型（Llama‑3、Phi‑3、Mistral 等）。
3. 使用与 OpenAI 兼容的 API 进行聊天、流式传输和 JSON 模式。
4. 用 Web Workers、Service Workers 和 Chrome 扩展扩展 WebLLM。
5. 部署轻量级本地聊天机器人演示。

让我们开始吧。

1. 什么是 WebLLM？

WebLLM（即 Web Large Language Model 的缩写）是：

• 浏览器内 – 无需服务器调用。
• 高性能 – 采用 WebGPU 进行硬件加速。
• 与 OpenAI 兼容 – 与您在 OpenAI SDK 中使用的 API 相同。
• 可扩展 – 可插入自定义模型或在 Web Workers 上运行。
• 生产就绪 – 提供流式传输、JSON 模式，并计划支持函数调用。

快速链接： https://webllm.mlc.ai

2. 安装

# npm
npm install @mlc-ai/web-llm
# yarn
yarn add @mlc-ai/web-llm
# pnpm
pnpm add @mlc-ai/web-llm

CDN

如果你喜欢使用 script 标签，WebLLM 可通过 jsDelivr 获取：

<script type="module">
  import * as webllm from "https://esm.run/@mlc-ai/web-llm";
  // …
</script>

3. 构建最小聊天应用

以下是一个 vanilla‑JS 示例。相同逻辑亦可在 React、Vue 或任何框架中使用。

import { CreateMLCEngine } from '@mlc-ai/web-llm';

const initProgress = (p) => console.log(`Loading: ${p.percentage}%`);
const modelId = 'Llama-3.1-8B-Instruct-q4f32_1-MLC';

async function init() {
  const engine = await CreateMLCEngine(modelId, { initProgressCallback: initProgress });
  const chat = async (messages) => {
    const result = await engine.chat.completions.create({ messages });
    return result.choices[0].message.content;
  };
  // Demo call
  const reply = await chat([
    { role: 'system', content: 'You are helpful.' },
    { role: 'user', content: 'Tell me a joke.' }
  ]);
  console.log('AI:', reply);
}
init();

要点： - CreateMLCEngine 同时构建引擎并加载模型。 - initProgressCallback 用于报告下载进度。 - 返回的 API 与 OpenAI 的相同：chat.completions.create。

4. 流式聊天

WebLLM 支持 stream:true，返回一个 AsyncGenerator。

const streamGen = await engine.chat.completions.create({
  messages,
  stream: true,
  stream_options: { include_usage: true }
});

let text = '';
for await (const chunk of streamGen) {
  text += chunk.choices[0]?.delta.content ?? '';
  console.log(text);
}
console.log('Total tokens:', chunk.usage?.total_tokens);

5. JSON 模式与结构化输出

const reply = await engine.chat.completions.create({
  messages,
  temperature: 0.2,
  response_format: { type: 'json_object' }
});
const json = JSON.parse(reply.choices[0].message.content);

当设置 response_format 时，引擎会确保响应符合对应模式。

6. 在 Web Workers 上运行

使用专门的 Web Worker 能保持 UI 响应。

1. worker.ts

   import { WebWorkerMLCEngineHandler } from '@mlc-ai/web-llm';
   const handler = new WebWorkerMLCEngineHandler();
   self.onmessage = handler.onmessage;
   

2. main.ts

   import { CreateWebWorkerMLCEngine } from '@mlc-ai/web-llm';
   const worker = new Worker(new URL('./worker.ts', import.meta.url), { type: 'module' });
   const engine = await CreateWebWorkerMLCEngine(worker, modelId, { initProgressCallback });
   

这种模式可让大规模计算在主线程之外执行。

7. Service Workers 进行离线缓存

借助 Service Workers，模型在页面刷新后仍然可用；可用于离线或低延迟体验。

self.addEventListener('activate', () => {
  /* init handler */
});

然后在主应用中注册：

navigator.serviceWorker.register('./sw.ts', { type: 'module' });
const engine = await CreateServiceWorkerMLCEngine(modelId, { initProgressCallback });

8. 自定义模型

WebLLM 可以加载任何已编译为 MLC 格式的模型。请在 app config 中提供 model 与 model_lib 的 URL：

const appConfig = { model_list: [{
  model: 'https://mydomain.com/my-llama',
  model_id: 'MyLlama-3B',
  model_lib: 'https://mydomain.com/myllama3b.wasm'
}] };
const engine = await CreateMLCEngine('MyLlama-3B', { appConfig });

这使得本地或私有模型的启动变得极为简单。

9. Chrome 扩展示例

WebLLM 附带扩展开发脚手架——可是轻量级 UI，也可以是持久后台 Worker。请参阅仓库中 examples/chrome-extension 目录，了解如何在任何网页中注入本地助手的完整设置。

10. 性能与兼容性

硬件加速

主速提升来自 WebGPU。基准测试显示，针对 8‑B 模型的推理相较纯 JS 具有 3~5 倍的延迟下降。在无 GPU 系统上，引擎可无缝降级至 WebAssembly。

11. 获取帮助 & 贡献

• 文档 & 博客 – https://webllm.mlc.ai/docs
• Discord 社区 – 快速获取帮助。
• GitHub Issues – 提交问题或功能请求。
• Pull Requests – 为代码、示例或文档做贡献。

12. 总结

WebLLM 将 LLM 的强大功能带到浏览器，无需服务器成本且不牺牲隐私。无论你正在原型化 AI 聊天机器人、开发 Chrome 扩展，还是尝试自定义模型，WebLLM 的模块化 API 与 WebGPU 加速都使其成为极具吸引力的选择。

下一步？ - 在 https://webllm.mlc.ai 上尝试 Playground。 - 克隆仓库并使用 examples/get-started 进行探索。 - 尝试构建你自己的 Chrome 扩展。

祝编码愉快，下次在浏览器再会！