mlc-ai--web-llm/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

WebLLM

高性能浏览器内 LLM 推理引擎。

文档 | 博客文章 | 论文 | 示例

概述

WebLLM 是一款高性能的浏览器内 LLM 推理引擎，可将语言模型推理直接带到 Web 浏览器中，并利用硬件加速。 一切都在浏览器内运行，无需服务器支持，并通过 WebGPU 加速。

WebLLM 完全兼容 OpenAI API. 也就是说，你可以在本地对任何开源模型使用相同的 OpenAI API，功能包括流式输出、JSON 模式、函数调用（开发中）等。

这为每个人构建 AI 助手带来了许多有趣的可能，并在享受 GPU 加速的同时保护隐私。

你可以将 WebLLM 作为基础 npm 包，并按照下方示例在其之上构建自己的 Web 应用。本项目是 MLC LLM, 的配套项目，后者可在各类硬件环境中实现 LLM 的通用部署。

体验 WebLLM Chat，立即试用！

核心特性

• 浏览器内推理（In-Browser Inference）：WebLLM 是一款高性能的浏览器内语言模型推理引擎，利用 WebGPU 进行硬件加速，使强大的 LLM 运算可直接在 Web 浏览器中完成，无需服务端处理。

• 完整 OpenAI API 兼容性：使用 OpenAI API 将你的应用与 WebLLM 无缝集成，支持流式输出、JSON 模式、logit 级控制、种子（seeding）等功能。

• 结构化 JSON 生成：WebLLM 支持业界领先的 JSON 模式结构化生成，在模型库的 WebAssembly 部分实现以获得最佳性能。可在 HuggingFace 上的 WebLLM JSON Playground 试用使用自定义 JSON schema 生成 JSON 输出。

• 广泛的模型支持：WebLLM 原生支持多种模型，包括 Llama 3、Phi 3、Gemma、Mistral、Qwen（通义千问）等，可胜任各类 AI 任务。完整支持模型列表请参见 MLC Models.

• 自定义模型集成：可轻松集成并部署 MLC 格式的自定义模型，使 WebLLM 适应特定需求与场景，提升模型部署的灵活性。

• 即插即用集成：通过 NPM、Yarn 等包管理器或直接通过 CDN 轻松将 WebLLM 集成到项目中，配有全面的 示例 和模块化设计，便于与 UI 组件对接。

• 流式输出与实时交互：支持流式聊天补全，实现实时输出生成，增强聊天机器人和虚拟助手等交互式应用体验。

• Web Worker 与 Service Worker 支持：将计算卸载到独立 worker 线程或 service worker，优化 UI 性能并高效管理模型生命周期。

• Chrome 扩展支持：通过自定义 Chrome 扩展扩展 Web 浏览器功能，提供构建基础与高级扩展的示例。

内置模型

完整可用模型列表请参见 MLC Models.。WebLLM 支持其中一部分模型，列表可在 prebuiltAppConfig.model_list. 查看。

以下是当前支持的主要模型系列：

• Llama：Llama 3、Llama 2、Hermes-2-Pro-Llama-3
• Phi：Phi 3、Phi 2、Phi 1.5
• Gemma：Gemma-2B
• Mistral：Mistral-7B-v0.3、Hermes-2-Pro-Mistral-7B、NeuralHermes-2.5-Mistral-7B、OpenHermes-2.5-Mistral-7B
• Qwen（通义千问）：Qwen2 0.5B、1.5B、7B

如需更多模型，请通过提交 issue 申请新模型，或参阅 自定义模型 了解如何编译并在 WebLLM 中使用你自己的模型。

通过示例快速上手

通过以下简单的聊天机器人示例，学习如何使用 WebLLM 将大语言模型集成到应用中并生成聊天补全：

如需更复杂的大型项目高级示例，请参阅 WebLLM Chat.

更多针对不同用例的示例见 examples 文件夹。

快速开始

WebLLM 提供简洁、模块化的接口，可在浏览器中访问聊天机器人。 该包采用模块化设计，可对接任意 UI 组件。

安装

包管理器

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

然后在代码中导入该模块。

// Import everything
import * as webllm from "@mlc-ai/web-llm";
// Or only import what you need
import { CreateMLCEngine } from "@mlc-ai/web-llm";

CDN 分发

借助 jsdelivr.com,，WebLLM 可直接通过 URL 导入，并在 jsfiddle.net,、Codepen.io, 和 Scribbler: 等云端开发平台上开箱即用。

import * as webllm from "https://esm.run/@mlc-ai/web-llm";

也可以动态导入：

const webllm = await import("https://esm.run/@mlc-ai/web-llm");

创建 MLCEngine

WebLLM 中的大多数操作通过 MLCEngine 接口调用。你可以创建 MLCEngine 实例，并通过调用 CreateMLCEngine() 工厂函数加载模型。

（请注意，加载模型需要下载；若此前未缓存，首次运行可能耗时较长。你应妥善处理此异步调用。）

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

// Callback function to update model loading progress
const initProgressCallback = (initProgress) => {
  console.log(initProgress);
};
const selectedModel = "Llama-3.1-8B-Instruct-q4f32_1-MLC";

const engine = await CreateMLCEngine(
  selectedModel,
  { initProgressCallback: initProgressCallback }, // engineConfig
);

底层而言，该工厂函数会先同步创建引擎实例，再异步加载模型。你也可以在应用中分步执行这些操作。

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

// This is a synchronous call that returns immediately
const engine = new MLCEngine({
  initProgressCallback: initProgressCallback,
});

// This is an asynchronous call and can take a long time to finish
await engine.reload(selectedModel);

缓存后端策略

WebLLM 通过 AppConfig.cacheBackend 支持四种缓存后端：

• "cache"：浏览器 Cache API（默认）。
• "indexeddb"：浏览器 IndexedDB.
• "opfs"：浏览器 Origin Private File System (OPFS).
• "cross-origin"：实验性 Chrome Cross-Origin Storage API 扩展后端。安装 Cross-Origin Storage extension 即可使用。（若未安装该扩展，WebLLM 会自动回退到默认缓存。）

示例：

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 的环境中选择 "opfs" 时，缓存操作会因 OPFS 不可用而失败。
• 使用 "opfs" 时，可将 appConfig.opfsAccessMode 设为 "auto"，在支持的情况下使用 OPFS 同步访问句柄（sync access handles）；或设为 "sync" 以强制要求同步访问句柄。默认值为 "async"。
• "cross-origin" 后端需要安装并启用兼容的浏览器扩展。
• 跨源（cross-origin）后端目前不支持以编程方式删除张量缓存（tensor-cache）；清理由扩展管理。

聊天补全（Chat Completion）

成功初始化引擎后，即可通过 engine.chat.completions 接口，以 OpenAI 风格的聊天 API 调用聊天补全。完整参数列表及说明请参阅下文章节和 OpenAI API reference.

（注意：此处不支持 model 参数，将被忽略。请改为调用 CreateMLCEngine(model) 或 engine.reload(model)，如上文 Create MLCEngine 所示。）

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);

流式输出（Streaming）

WebLLM 也支持流式生成聊天补全。使用时，只需在 engine.chat.completions.create 调用中传入 stream: true。

const messages = [
  { role: "system", content: "You are a helpful AI assistant." },
  { role: "user", content: "Hello!" },
];

// Chunks is an AsyncGenerator object
const chunks = await engine.chat.completions.create({
  messages,
  temperature: 1,
  stream: true, // <-- Enable streaming
  stream_options: { include_usage: true },
});

let reply = "";
for await (const chunk of chunks) {
  reply += chunk.choices[0]?.delta.content || "";
  console.log(reply);
  if (chunk.usage) {
    console.log(chunk.usage); // only last chunk has usage
  }
}

const fullReply = await engine.getMessage();
console.log(fullReply);

高级用法

使用 Worker

可将重计算放入 worker 脚本以优化应用性能。为此需要：

1. 在 worker 线程中创建处理器（handler），在处理请求的同时与前端通信。
2. 在主应用中创建 Worker Engine，其底层会向 worker 线程中的处理器发送消息。

不同 Worker 类型的具体实现请参阅以下章节。

专用 Web Worker

WebLLM 提供 WebWorker API 支持，可将生成过程挂接到独立 worker 线程，避免 worker 线程中的计算阻塞 UI。

我们在 worker 线程中创建处理器，在处理请求的同时与前端通信。

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

// A handler that resides in the worker thread
const handler = new WebWorkerMLCEngineHandler();
self.onmessage = (msg: MessageEvent) => {
  handler.onmessage(msg);
};

在主逻辑中，我们创建实现相同 MLCEngineInterface 的 WebWorkerMLCEngine。其余逻辑保持不变。

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

async function main() {
  // Use a WebWorkerMLCEngine instead of MLCEngine here
  const engine = await CreateWebWorkerMLCEngine(
    new Worker(new URL("./worker.ts", import.meta.url), {
      type: "module",
    }),
    selectedModel,
    { initProgressCallback }, // engineConfig
  );

  // everything else remains the same
}

使用 Service Worker

WebLLM 提供 ServiceWorker API 支持，可将生成过程挂接到 service worker，避免每次访问页面都重新加载模型，并优化应用的离线体验。

（注意：Service Worker 的生命周期由浏览器管理，可能随时被终止且不会通知 Web 应用。ServiceWorkerMLCEngine 会尝试通过定期发送心跳事件保持 service worker 线程存活，但应用也应包含适当的错误处理。更多细节请参阅 ServiceWorkerMLCEngine 中的 keepAliveMs 和 missedHeatbeat。）

我们在 worker 线程中创建处理器，在处理请求的同时与前端通信。

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

let handler: ServiceWorkerMLCEngineHandler;

self.addEventListener("activate", function (event) {
  handler = new ServiceWorkerMLCEngineHandler();
  console.log("Service Worker is ready");
});

然后在主逻辑中注册 service worker，并使用 CreateServiceWorkerMLCEngine 函数创建引擎。其余逻辑保持不变。

// main.ts
import {
  MLCEngineInterface,
  CreateServiceWorkerMLCEngine,
} from "@mlc-ai/web-llm";

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

const engine: MLCEngineInterface = await CreateServiceWorkerMLCEngine(
  selectedModel,
  { initProgressCallback }, // engineConfig
);

在 examples/service-worker 中可找到在 service worker 中运行 WebLLM 的完整示例。

Chrome 扩展

也可在 examples/chrome-extension 和 examples/chrome-extension-webgpu-service-worker 中找到使用 WebLLM 构建 Chrome 扩展的示例。后者借助 service worker，使扩展可在后台持久运行。此外，还可探索另一个完整的 Chrome 扩展项目 WebLLM Assistant，该项目基于 WebLLM，见此处.

完整 OpenAI 兼容性

WebLLM 设计为与 OpenAI API. 完全兼容。因此，除构建简单聊天机器人外，还可通过 WebLLM 实现以下功能：

• streaming：以 AsyncGenerator 形式实时分块返回输出
• json-mode：高效确保输出为 JSON 格式，详见 OpenAI Reference
• seed-to-reproduce：使用种子（seeding）配合字段 seed 确保可复现输出
• function-calling（WIP）：使用字段 tools 和 tool_choice 进行函数调用（初步支持）；或不使用 tools 或 tool_choice 进行手动函数调用（灵活性最高）

完整性验证

WebLLM 支持使用 SRI（Subresource Integrity，子资源完整性） 哈希值对模型构件进行可选的完整性验证。 当在 ModelRecord 上设置了 integrity 字段时，WebLLM 会在加载前根据提供的哈希值验证已下载的 config、WASM 和 tokenizer 文件。

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

const appConfig = {
  model_list: [
    {
      model: "https://huggingface.co/mlc-ai/Llama-3.2-1B-Instruct-q4f16_1-MLC",
      model_id: "Llama-3.2-1B-Instruct-q4f16_1-MLC",
      model_lib:
        "https://raw.githubusercontent.com/user/model-libs/main/model.wasm",
      integrity: {
        config: "sha256-<base64-hash-of-mlc-chat-config.json>",
        model_lib: "sha256-<base64-hash-of-wasm-file>",
        tokenizer: {
          "tokenizer.json": "sha256-<base64-hash-of-tokenizer.json>",
        },
        onFailure: "error", // "error" (default) throws IntegrityError, "warn" logs and continues
      },
    },
  ],
};

const engine = await CreateMLCEngine("Llama-3.2-1B-Instruct-q4f16_1-MLC", {
  appConfig,
});

你可以使用以下方式为模型文件生成 SRI 哈希值：

# SHA-256
openssl dgst -sha256 -binary <file> | openssl base64 -A | sed 's/^/sha256-/'
# SHA-384
openssl dgst -sha384 -binary <file> | openssl base64 -A | sed 's/^/sha384-/'
# SHA-512
openssl dgst -sha512 -binary <file> | openssl base64 -A | sed 's/^/sha512-/'

openssl 命令需要类 Unix shell（macOS/Linux）。在 Windows 上，可通过 Git Bash 或 WSL. 运行 openssl。

如果哈希值不匹配，将抛出 IntegrityError（或在 onFailure: "warn" 时记录警告）。 integrity 中的所有字段均为可选 — 仅会验证已指定的构件。 当完全省略 integrity 字段时，WebLLM 的行为与之前完全相同（不进行验证）。

请参阅 integrity-verification 示例 获取完整可运行的演示。

自定义模型

WebLLM 是 MLC LLM 的配套项目，支持 MLC 格式的自定义模型。 它复用模型构件并构建 MLC LLM 的流程。要在 WebLLM 中使用并编译你自己的模型，请参阅 MLC LLM 文档，了解如何将新的模型权重和库编译并部署到 WebLLM。

此处我们概述高层次思路。WebLLM 包中有两个要素可启用新模型和权重变体。

• model：包含指向模型构件（如权重和元数据）的 URL。
• model_lib：指向 WebAssembly 库（即 wasm 文件）的 URL，其中包含用于加速模型计算的可执行代码。

两者在 WebLLM 中均可自定义。

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

async main() {
  const appConfig = {
    "model_list": [
      {
        "model": "/url/to/my/llama",
        "model_id": "MyLlama-3b-v1-q4f32_0",
        "model_lib": "/url/to/myllama3b.wasm",
      }
    ],
  };
  // override default
  const chatOpts = {
    "repetition_penalty": 1.01
  };

  // load a prebuilt model
  // with a chat option override and app config
  // under the hood, it will load the model from myLlamaUrl
  // and cache it in the browser cache
  // The chat will also load the model library from "/url/to/myllama3b.wasm",
  // assuming that it is compatible to the model in myLlamaUrl.
  const engine = await CreateMLCEngine(
    "MyLlama-3b-v1-q4f32_0",
    { appConfig }, // engineConfig
    chatOpts,
  );
}

在许多情况下，我们只需提供模型权重变体，而不一定需要新模型（例如 NeuralHermes-Mistral 可以复用 Mistral 的模型库）。有关不同模型变体如何共享模型库的示例，请参阅 webllm.prebuiltAppConfig。

从源码构建 WebLLM 包

注意：除非你想修改 WebLLM 包，否则无需从源码构建。 要使用 npm，只需按照 Get Started 或任一 examples 操作即可。

要从源码构建，只需运行：

npm install
npm run build

然后，要在示例中测试代码更改的效果，在 examples/get-started/package.json 内，将 "@mlc-ai/web-llm": "^0.2.84" 改为 "@mlc-ai/web-llm": ../..。

然后运行：

cd examples/get-started
npm install
npm start

请注意，有时你需要在 file:../.. 与 ../.. 之间切换，以让 npm 识别新更改。最坏情况下，可以运行：

cd examples/get-started
rm -rf node_modules dist package-lock.json .parcel-cache
npm install
npm start

如需从源码构建 TVMjs

WebLLM 的运行时在很大程度上依赖于 TVMjs：https://github.com/apache/tvm/tree/main/web

虽然它也可作为 npm 包获取：https://www.npmjs.com/package/@mlc-ai/web-runtime,，如有需要，可按以下步骤从源码构建。

1. 安装 emscripten.。它是基于 LLVM 的编译器，可将 C/C++ 源代码编译为 WebAssembly。

   • 按照 安装说明 安装最新的 emsdk。
   • 通过 source path/to/emsdk_env.sh source emsdk_env.sh，使 emcc 可从 PATH 访问，且 emcc 命令可用。

   我们可通过在终端尝试 emcc 来验证安装是否成功。

   注意：我们最近发现使用最新的 emcc 版本可能在运行时遇到问题。目前请改用 ./emsdk install 3.1.56 而非 ./emsdk install latest 作为变通方案。错误可能如下所示

   Init error, LinkError: WebAssembly.instantiate(): Import #6 module="wasi_snapshot_preview1"
   function="proc_exit": function import requires a callable
   

2. 在 ./package.json 中，将 "@mlc-ai/web-runtime": "0.18.0-dev2", 改为 "@mlc-ai/web-runtime": "file:./tvm_home/web",。

3. 配置必要环境

   准备 Web 构建所需的全部依赖：

   ./scripts/prep_deps.sh
   

   在此步骤中，如果环境中未定义 $TVM_SOURCE_DIR，我们将执行以下命令以构建 tvmjs 依赖：

   git clone https://github.com/mlc-ai/relax 3rdparty/tvm-unity --recursive
   

   这将克隆 mlc-ai/relax 的当前 HEAD。然而，这未必总是应克隆的正确分支或提交。要从源码构建特定 npm 版本，请参阅 version bump PR，其中说明了当前 WebLLM 版本依赖的分支（即 mlc-ai/relax 或 apache/tvm）以及对应的提交。例如，版本 0.2.52 根据其 version bump PR https://github.com/mlc-ai/web-llm/pull/521,，需在 apache/tvm 中检出以下提交 https://github.com/apache/tvm/commit/e6476847753c80e054719ac47bc2091c888418b6 进行构建，而非 mlc-ai/relax 的 HEAD。

   此外，--recursive 是必要且重要的。否则，你可能会遇到类似 fatal error: 'dlpack/dlpack.h' file not found 的错误。

4. 构建 WebLLM 包

   npm run build
   

5. 验证部分子包

   然后可进入 examples 中的子文件夹，验证部分子包。 我们使用 Parcelv2 进行打包。尽管 Parcel 有时不太擅长跟踪父目录的更改。当你在 WebLLM 包中做出更改时，尝试编辑子文件夹的 package.json 并保存，这将触发 Parcel 重新构建。

链接

• 演示应用：WebLLM Chat
• 若要在原生运行时上运行 LLM，请参阅 MLC-LLM
• 你可能还会对 Web Stable Diffusion. 感兴趣

致谢

本项目由 CMU Catalyst、UW SAMPL、SJTU、OctoML 及 MLC 社区的成员发起。我们希望能够继续开发并支持开源机器学习（ML）社区。

本项目的实现，离不开我们所依托的开源生态。我们想要感谢 Apache TVM 社区以及 TVM Unity 工作的开发者。开源 ML 社区的成员使这些模型得以公开发布。PyTorch 和 Hugging Face 社区使这些模型更易于获取。我们还要感谢 Vicuna、SentencePiece、LLaMA 和 Alpaca 背后的团队。同时也要感谢 WebAssembly、Emscripten 和 WebGPU 社区。最后，感谢 Dawn 和 WebGPU 开发者。

引用

如果您觉得本项目对您有帮助，欢迎引用：

@misc{ruan2026webllmhighperformanceinbrowserllm,
      title={WebLLM: A High-Performance In-Browser LLM Inference Engine},
      author={Charlie F. Ruan and Yucheng Qin and Akaash R. Parthasarathy and Xun Zhou and Ruihang Lai and Hongyi Jin and Yixin Dong and Bohan Hou and Meng-Shiun Yu and Yiyan Zhai and Sudeep Agarwal and Hangrui Cao and Siyuan Feng and Tianqi Chen},
      year={2026},
      eprint={2412.15803},
      archivePrefix={arXiv},
      primaryClass={cs.LG},
      url={https://arxiv.org/abs/2412.15803},
}

贡献者

⬆ 返回顶部 ⬆