WebLLM 是一个高性能的浏览器端 LLM 推理引擎

WebLLM 部署与使用教程

WebLLM 是一个高性能的浏览器端 LLM 推理引擎，它利用 WebGPU 加速，让你可以直接在浏览器中运行大语言模型，无需服务器支持。本教程将带你从零开始，完成 WebLLM 的集成、配置到部署的全过程。

---

一、核心特性概览

在开始部署前，了解 WebLLM 的主要能力有助于你更好地使用它：

• 纯浏览器推理：所有计算在本地完成，保护隐私，降低服务器成本。
• OpenAI API 兼容：使用熟悉的 OpenAI API 格式与开源模型交互，支持流式输出、JSON 模式等。
• 广泛模型支持：原生支持 Llama、Phi、Gemma、Mistral、Qwen 等主流模型系列。
• 多种缓存策略：支持 Cache API、IndexedDB、OPFS 等，灵活管理模型缓存。
• Web Worker 优化：可将模型加载和推理放到 Worker 线程，避免阻塞主线程 UI。

---

二、快速开始：在项目中集成 WebLLM

2.1 安装方式

通过包管理器安装

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

通过 CDN 直接引入

<script type="importmap">
{
  "imports": {
    "@mlc-ai/web-llm": "https://esm.run/@mlc-ai/web-llm"
  }
}
</script>
<script type="module">
import * as webllm from "@mlc-ai/web-llm";
// ... 使用 webllm
</script>

2.2 创建引擎与加载模型

核心操作是通过 CreateMLCEngine 工厂函数创建引擎实例并加载模型。

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

// 进度回调，用于显示加载状态
const initProgressCallback = (progress) => {
  console.log(`加载进度: ${progress.text} (${progress.progress || 0}%)`);
};

// 指定要使用的模型（完整列表见 MLC Models）
const selectedModel = "Llama-3.1-8B-Instruct-q4f32_1-MLC";

// 创建引擎并加载模型
const engine = await CreateMLCEngine(
  selectedModel,
  { initProgressCallback } // 引擎配置
);

console.log("模型加载完成，可以开始对话");

注意：首次加载模型需要下载数 GB 的文件，耗时较长，请耐心等待并妥善处理加载状态。

2.3 执行对话

加载完成后，即可通过 engine.chat.completions 接口发送消息。

非流式对话

const messages = [
  { role: "system", content: "你是一个有用的AI助手。" },
  { role: "user", content: "你好！请介绍一下你自己。" }
];

const reply = await engine.chat.completions.create({ messages });
console.log(reply.choices[0].message.content);

流式对话

const chunks = await engine.chat.completions.create({
  messages,
  stream: true, // 启用流式
});

let fullReply = "";
for await (const chunk of chunks) {
  const content = chunk.choices[0]?.delta?.content || "";
  fullReply += content;
  console.log(fullReply); // 实时打印累积内容
}

---

三、高级部署配置

3.1 使用 Web Worker 优化性能

将推理任务放在 Worker 线程中，可以避免阻塞主页面 UI。

1. 创建 Worker 脚本 (worker.js)

import { WebWorkerMLCEngineHandler } from "@mlc-ai/web-llm";

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

2. 在主线程中调用

import { CreateWebWorkerMLCEngine } from "@mlc-ai/web-llm";

const engine = await CreateWebWorkerMLCEngine(
  new Worker(new URL("./worker.js", import.meta.url), { type: "module" }),
  selectedModel,
  { initProgressCallback }
);

// 后续对话用法与普通引擎完全一致

3.2 使用 Service Worker 实现模型持久化

Service Worker 可以让模型在页面刷新后保持加载状态，优化重复访问体验。

1. 创建 Service Worker 脚本 (sw.js)

import { ServiceWorkerMLCEngineHandler } from "@mlc-ai/web-llm";

// 必须在顶层立即实例化
new ServiceWorkerMLCEngineHandler();
console.log("Service Worker 已就绪");

2. 在主线程注册并创建引擎

if ("serviceWorker" in navigator) {
  navigator.serviceWorker.register(
    new URL("./sw.js", import.meta.url),
    { type: "module" }
  );
}

const engine = await CreateServiceWorkerMLCEngine(
  selectedModel,
  { initProgressCallback }
);

3.3 缓存后端策略

WebLLM 提供多种缓存后端，可通过 appConfig.cacheBackend 配置：

import { CreateMLCEngine, prebuiltAppConfig } from "@mlc-ai/web-llm";

const appConfig = {
  ...prebuiltAppConfig,
  cacheBackend: "indexeddb" // 可选: "cache" (默认), "indexeddb", "opfs"
};

const engine = await CreateMLCEngine(selectedModel, { appConfig });

后端	说明
"cache"	浏览器 Cache API，默认选项。
"indexeddb"	IndexedDB，适合存储大文件，持久性好。
"opfs"	源私有文件系统，性能更好，需环境支持。

3.4 自定义模型与模型库

你可以使用 MLC LLM 编译自己的模型，并在 WebLLM 中加载。

const appConfig = {
  model_list: [
    {
      model: "https://your-cdn.com/path/to/your-model/", // 模型权重 URL
      model_id: "MyCustomModel-Q4",                      // 自定义 ID
      model_lib: "https://your-cdn.com/path/to/model.wasm" // WASM 库 URL
    }
  ]
};

const engine = await CreateMLCEngine("MyCustomModel-Q4", { appConfig });

---

四、构建与部署

4.1 构建项目

使用任何前端构建工具（如 Vite、Webpack、Parcel）打包你的应用。关键是在构建时正确处理 WASM 文件和 Worker。

Vite 示例配置

// vite.config.js
import { defineConfig } from 'vite';

export default defineConfig({
  optimizeDeps: {
    exclude: ['@mlc-ai/web-llm'], // 防止预构建时出现问题
  },
  worker: {
    format: 'es', // Worker 使用 ES Module 格式
  },
});

4.2 部署注意事项

1. 跨域资源共享 (CORS)：确保模型文件所在的 CDN 或存储桶配置了正确的 CORS 头，允许浏览器跨域加载。
2. WebGPU 支持：WebLLM 依赖 WebGPU，请确保目标浏览器（Chrome 113+、Edge 113+、Firefox Nightly）支持并已启用。
3. Service Worker 作用域：如果使用 Service Worker，需确保其注册路径能覆盖你的应用页面。
4. 缓存策略：对于模型文件（常为 .bin, .wasm 等），建议设置较长的缓存时间，减少重复下载。
5. 内存管理：大模型会占用较多内存（数 GB），注意测试目标设备的可用内存。

---

五、部署清单

步骤	操作	关键点
1. 环境准备	确认浏览器支持 WebGPU	推荐最新版 Chrome/Edge。
2. 项目集成	npm install @mlc-ai/web-llm	选择合适的包管理器。
3. 代码实现	创建引擎、加载模型、处理对话	实现加载进度反馈，处理流式输出。
4. 优化（可选）	启用 Worker	避免阻塞 UI。
5. 优化（可选）	配置缓存后端	平衡加载速度与存储空间。
6. 构建	使用 Vite/Webpack 打包	正确处理 Worker 和 WASM。
7. 部署	上传静态文件到托管服务	配置 CORS，设置缓存头。
8. 验证	在目标浏览器中测试	检查 WebGPU 是否启用，模型是否能正确加载并推理。

---

总结

通过本教程，你已经掌握了在浏览器中部署 WebLLM 的核心方法。从简单的聊天应用，到复杂的、利用 Worker 优化性能的项目，WebLLM 提供了一个强大且灵活的框架。

后续学习建议：

• 查看官方 示例库 获取更多集成参考。
• 阅读 MLC LLM 文档 了解如何编译自定义模型。
• 关注 WebGPU 标准演进，以获得更好的性能支持。

WebLLM 使在浏览器中运行强大 AI 模型成为可能，现在就开始你的探索吧！