mlc-ai--web-llm
wehub-resource-sync
a139047db8
Build site and push to gh-pages / Build site (push) Has been cancelled
Build / build (push) Has been cancelled
Linter / lint (push) Has been cancelled
Security / dependency-review (push) Has been cancelled
Security / npm-audit (push) Has been cancelled
Security / codeql (push) Has been cancelled
Tests / test (push) Has been cancelled
558 行
24 KiB
Markdown
558 行
24 KiB
Markdown
<!-- WEHUB_ZH_README -->
|
||
> [!NOTE]
|
||
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
|
||
> [English](./README.en.md) · [原始项目](https://github.com/mlc-ai/web-llm) · [上游 README](https://github.com/mlc-ai/web-llm/blob/HEAD/README.md)
|
||
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
|
||
|
||
<div align="center" id="top">
|
||
|
||
# WebLLM
|
||
|
||
[](https://www.npmjs.com/package/@mlc-ai/web-llm)
|
||
[](https://chat.webllm.ai/)
|
||
[](https://discord.gg/9Xpy2HGBuD)
|
||
[](https://github.com/mlc-ai/web-llm-chat/)
|
||
[](https://github.com/mlc-ai/mlc-llm/)
|
||
|
||
**高性能浏览器内 LLM 推理引擎。**
|
||
|
||
[文档](https://webllm.mlc.ai/docs/) | [博客文章](https://blog.mlc.ai/2024/06/13/webllm-a-high-performance-in-browser-llm-inference-engine) | [论文](https://arxiv.org/abs/2412.15803) | [示例](examples)
|
||
|
||
</div>
|
||
|
||
## 概述
|
||
|
||
WebLLM 是一款高性能的浏览器内 LLM 推理引擎，可将语言模型推理直接带到 Web 浏览器中，并利用硬件加速。
|
||
一切都在浏览器内运行，无需服务器支持，并通过 WebGPU 加速。
|
||
|
||
WebLLM **完全兼容 [OpenAI API](https://platform.openai.com/docs/api-reference/chat).**
|
||
也就是说，你可以在本地对**任何开源模型**使用相同的 OpenAI API，功能包括流式输出、JSON 模式、函数调用（开发中）等。
|
||
|
||
这为每个人构建 AI 助手带来了许多有趣的可能，并在享受 GPU 加速的同时保护隐私。
|
||
|
||
你可以将 WebLLM 作为基础 [npm 包](https://www.npmjs.com/package/@mlc-ai/web-llm)，并按照下方示例在其之上构建自己的 Web 应用。本项目是 [MLC LLM](https://github.com/mlc-ai/mlc-llm), 的配套项目，后者可在各类硬件环境中实现 LLM 的通用部署。
|
||
|
||
<div align="center">
|
||
|
||
**[体验 WebLLM Chat，立即试用！](https://chat.webllm.ai/)**
|
||
|
||
</div>
|
||
|
||
## 核心特性
|
||
|
||
- **浏览器内推理（In-Browser Inference）**：WebLLM 是一款高性能的浏览器内语言模型推理引擎，利用 WebGPU 进行硬件加速，使强大的 LLM 运算可直接在 Web 浏览器中完成，无需服务端处理。
|
||
|
||
- [**完整 OpenAI API 兼容性**](#full-openai-compatibility)：使用 OpenAI API 将你的应用与 WebLLM 无缝集成，支持流式输出、JSON 模式、logit 级控制、种子（seeding）等功能。
|
||
|
||
- **结构化 JSON 生成**：WebLLM 支持业界领先的 JSON 模式结构化生成，在模型库的 WebAssembly 部分实现以获得最佳性能。可在 HuggingFace 上的 [WebLLM JSON Playground](https://huggingface.co/spaces/mlc-ai/WebLLM-JSON-Playground) 试用使用自定义 JSON schema 生成 JSON 输出。
|
||
|
||
- [**广泛的模型支持**](#built-in-models)：WebLLM 原生支持多种模型，包括 Llama 3、Phi 3、Gemma、Mistral、Qwen（通义千问）等，可胜任各类 AI 任务。完整支持模型列表请参见 [MLC Models](https://mlc.ai/models).
|
||
|
||
- [**自定义模型集成**](#custom-models)：可轻松集成并部署 MLC 格式的自定义模型，使 WebLLM 适应特定需求与场景，提升模型部署的灵活性。
|
||
|
||
- **即插即用集成**：通过 NPM、Yarn 等包管理器或直接通过 CDN 轻松将 WebLLM 集成到项目中，配有全面的 [示例](./examples/) 和模块化设计，便于与 UI 组件对接。
|
||
|
||
- **流式输出与实时交互**：支持流式聊天补全，实现实时输出生成，增强聊天机器人和虚拟助手等交互式应用体验。
|
||
|
||
- **Web Worker 与 Service Worker 支持**：将计算卸载到独立 worker 线程或 service worker，优化 UI 性能并高效管理模型生命周期。
|
||
|
||
- **Chrome 扩展支持**：通过自定义 Chrome 扩展扩展 Web 浏览器功能，提供构建基础与高级扩展的示例。
|
||
|
||
## 内置模型
|
||
|
||
完整可用模型列表请参见 [MLC Models](https://mlc.ai/models).。WebLLM 支持其中一部分模型，列表可在 [`prebuiltAppConfig.model_list`](https://github.com/mlc-ai/web-llm/blob/main/src/config.ts#L293). 查看。
|
||
|
||
以下是当前支持的主要模型系列：
|
||
|
||
- **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 申请新模型](https://github.com/mlc-ai/web-llm/issues/new/choose)，或参阅 [自定义模型](#custom-models) 了解如何编译并在 WebLLM 中使用你自己的模型。
|
||
|
||
## 通过示例快速上手
|
||
|
||
通过以下简单的聊天机器人示例，学习如何使用 WebLLM 将大语言模型集成到应用中并生成聊天补全：
|
||
|
||
[](https://jsfiddle.net/neetnestor/4nmgvsa2/)
|
||
[](https://codepen.io/neetnestor/pen/vYwgZaG)
|
||
|
||
如需更复杂的大型项目高级示例，请参阅 [WebLLM Chat](https://github.com/mlc-ai/web-llm-chat/blob/main/app/client/webllm.ts).
|
||
|
||
更多针对不同用例的示例见 [examples](./examples/) 文件夹。
|
||
|
||
## 快速开始
|
||
|
||
WebLLM 提供简洁、模块化的接口，可在浏览器中访问聊天机器人。
|
||
该包采用模块化设计，可对接任意 UI 组件。
|
||
|
||
### 安装
|
||
|
||
#### 包管理器
|
||
|
||
```sh
|
||
# npm
|
||
npm install @mlc-ai/web-llm
|
||
# yarn
|
||
yarn add @mlc-ai/web-llm
|
||
# or pnpm
|
||
pnpm install @mlc-ai/web-llm
|
||
```
|
||
|
||
然后在代码中导入该模块。
|
||
|
||
```typescript
|
||
// 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](https://www.jsdelivr.com/package/npm/@mlc-ai/web-llm),，WebLLM 可直接通过 URL 导入，并在 [jsfiddle.net](https://jsfiddle.net/),、[Codepen.io](https://codepen.io/), 和 [Scribbler](https://scribbler.live): 等云端开发平台上开箱即用。
|
||
|
||
```javascript
|
||
import * as webllm from "https://esm.run/@mlc-ai/web-llm";
|
||
```
|
||
|
||
也可以动态导入：
|
||
|
||
```javascript
|
||
const webllm = await import("https://esm.run/@mlc-ai/web-llm");
|
||
```
|
||
|
||
### 创建 MLCEngine
|
||
|
||
WebLLM 中的大多数操作通过 `MLCEngine` 接口调用。你可以创建 `MLCEngine` 实例，并通过调用 `CreateMLCEngine()` 工厂函数加载模型。
|
||
|
||
（请注意，加载模型需要下载；若此前未缓存，首次运行可能耗时较长。你应妥善处理此异步调用。）
|
||
|
||
```typescript
|
||
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
|
||
);
|
||
```
|
||
|
||
底层而言，该工厂函数会先同步创建引擎实例，再异步加载模型。你也可以在应用中分步执行这些操作。
|
||
|
||
```typescript
|
||
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](https://developer.mozilla.org/en-US/docs/Web/API/Cache)（默认）。
|
||
- `"indexeddb"`：浏览器 [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API).
|
||
- `"opfs"`：浏览器 [Origin Private File System (OPFS)](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API/Origin_private_file_system).
|
||
- `"cross-origin"`：实验性 Chrome [Cross-Origin Storage API](https://github.com/WICG/cross-origin-storage) 扩展后端。安装 [Cross-Origin Storage extension](https://chromewebstore.google.com/detail/cross-origin-storage/denpnpcgjgikjpoglpjefakmdcbmlgih) 即可使用。（若未安装该扩展，WebLLM 会自动回退到默认缓存。）
|
||
|
||
示例：
|
||
|
||
```typescript
|
||
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 调用聊天补全。完整参数列表及说明请参阅[下文章节](#full-openai-compatibility)和 [OpenAI API reference](https://platform.openai.com/docs/api-reference/chat/create).
|
||
|
||
（注意：此处不支持 `model` 参数，将被忽略。请改为调用 `CreateMLCEngine(model)` 或 `engine.reload(model)`，如上文 [Create MLCEngine](#create-mlcengine) 所示。）
|
||
|
||
```typescript
|
||
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`。
|
||
|
||
```typescript
|
||
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 线程中创建处理器，在处理请求的同时与前端通信。
|
||
|
||
```typescript
|
||
// 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`。其余逻辑保持不变。
|
||
|
||
```typescript
|
||
// 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`](https://github.com/mlc-ai/web-llm/blob/main/src/service_worker.ts#L234) 中的 `keepAliveMs` 和 `missedHeatbeat`。）
|
||
|
||
我们在 worker 线程中创建处理器，在处理请求的同时与前端通信。
|
||
|
||
```typescript
|
||
// 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` 函数创建引擎。其余逻辑保持不变。
|
||
|
||
```typescript
|
||
// 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](examples/service-worker/) 中可找到在 service worker 中运行 WebLLM 的完整示例。
|
||
|
||
### Chrome 扩展
|
||
|
||
也可在 [examples/chrome-extension](examples/chrome-extension/) 和 [examples/chrome-extension-webgpu-service-worker](examples/chrome-extension-webgpu-service-worker/) 中找到使用 WebLLM 构建 Chrome 扩展的示例。后者借助 service worker，使扩展可在后台持久运行。此外，还可探索另一个完整的 Chrome 扩展项目 WebLLM Assistant，该项目基于 WebLLM，见[此处](https://github.com/mlc-ai/web-llm-assistant).
|
||
|
||
## 完整 OpenAI 兼容性
|
||
|
||
WebLLM 设计为与 [OpenAI API](https://platform.openai.com/docs/api-reference/chat). 完全兼容。因此，除构建简单聊天机器人外，还可通过 WebLLM 实现以下功能：
|
||
|
||
- [streaming](examples/streaming)：以 AsyncGenerator 形式实时分块返回输出
|
||
- [json-mode](examples/json-mode)：高效确保输出为 JSON 格式，详见 [OpenAI Reference](https://platform.openai.com/docs/guides/text-generation/chat-completions-api)
|
||
- [seed-to-reproduce](examples/seed-to-reproduce)：使用种子（seeding）配合字段 `seed` 确保可复现输出
|
||
- [function-calling](examples/function-calling)（WIP）：使用字段 `tools` 和 `tool_choice` 进行函数调用（初步支持）；或不使用 `tools` 或 `tool_choice` 进行手动函数调用（灵活性最高）
|
||
|
||
## 完整性验证
|
||
|
||
WebLLM 支持使用 [SRI（Subresource Integrity，子资源完整性）](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) 哈希值对模型构件进行可选的完整性验证。
|
||
当在 `ModelRecord` 上设置了 `integrity` 字段时，WebLLM 会在加载前根据提供的哈希值验证已下载的 config、WASM 和 tokenizer 文件。
|
||
|
||
```typescript
|
||
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 哈希值：
|
||
|
||
```bash
|
||
# 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](https://gitforwindows.org/) 或 [WSL](https://learn.microsoft.com/en-us/windows/wsl/). 运行 `openssl`。
|
||
|
||
如果哈希值不匹配，将抛出 `IntegrityError`（或在 `onFailure: "warn"` 时记录警告）。
|
||
`integrity` 中的所有字段均为可选 — 仅会验证已指定的构件。
|
||
当完全省略 `integrity` 字段时，WebLLM 的行为与之前完全相同（不进行验证）。
|
||
|
||
请参阅 [integrity-verification 示例](examples/integrity-verification/) 获取完整可运行的演示。
|
||
|
||
## 自定义模型
|
||
|
||
WebLLM 是 [MLC LLM](https://github.com/mlc-ai/mlc-llm) 的配套项目，支持 MLC 格式的自定义模型。
|
||
它复用模型构件并构建 MLC LLM 的流程。要在 WebLLM 中使用并编译你自己的模型，请参阅 [MLC LLM 文档](https://llm.mlc.ai/docs/deploy/webllm.html)，了解如何将新的模型权重和库编译并部署到 WebLLM。
|
||
|
||
此处我们概述高层次思路。WebLLM 包中有两个要素可启用新模型和权重变体。
|
||
|
||
- `model`：包含指向模型构件（如权重和元数据）的 URL。
|
||
- `model_lib`：指向 WebAssembly 库（即 wasm 文件）的 URL，其中包含用于加速模型计算的可执行代码。
|
||
|
||
两者在 WebLLM 中均可自定义。
|
||
|
||
```typescript
|
||
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](#get-started) 或任一 [examples](examples) 操作即可。
|
||
|
||
要从源码构建，只需运行：
|
||
|
||
```bash
|
||
npm install
|
||
npm run build
|
||
```
|
||
|
||
然后，要在示例中测试代码更改的效果，在 `examples/get-started/package.json` 内，将 `"@mlc-ai/web-llm": "^0.2.84"` 改为 `"@mlc-ai/web-llm": ../..`。
|
||
|
||
然后运行：
|
||
|
||
```bash
|
||
cd examples/get-started
|
||
npm install
|
||
npm start
|
||
```
|
||
|
||
请注意，有时你需要在 `file:../..` 与 `../..` 之间切换，以让 npm 识别新更改。最坏情况下，可以运行：
|
||
|
||
```bash
|
||
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](https://emscripten.org).。它是基于 LLVM 的编译器，可将 C/C++ 源代码编译为 WebAssembly。
|
||
- 按照 [安装说明](https://emscripten.org/docs/getting_started/downloads.html#installation-instructions-using-the-emsdk-recommended) 安装最新的 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 构建所需的全部依赖：
|
||
|
||
```shell
|
||
./scripts/prep_deps.sh
|
||
```
|
||
|
||
在此步骤中，如果环境中未定义 `$TVM_SOURCE_DIR`，我们将执行以下命令以构建 `tvmjs` 依赖：
|
||
|
||
```shell
|
||
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 包
|
||
|
||
```shell
|
||
npm run build
|
||
```
|
||
|
||
5. 验证部分子包
|
||
|
||
然后可进入 [examples](examples) 中的子文件夹，验证部分子包。
|
||
我们使用 Parcelv2 进行打包。尽管 Parcel 有时不太擅长跟踪父目录的更改。当你在 WebLLM 包中做出更改时，尝试编辑子文件夹的 `package.json` 并保存，这将触发 Parcel 重新构建。
|
||
|
||
## 链接
|
||
|
||
- [演示应用：WebLLM Chat](https://chat.webllm.ai/)
|
||
- 若要在原生运行时上运行 LLM，请参阅 [MLC-LLM](https://github.com/mlc-ai/mlc-llm)
|
||
- 你可能还会对 [Web Stable Diffusion](https://github.com/mlc-ai/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},
|
||
}
|
||
```
|
||
|
||
## 贡献者
|
||
|
||
<a href="https://github.com/mlc-ai/web-llm/graphs/contributors">
|
||
<img alt="contributors" src="https://contrib.rocks/image?repo=mlc-ai/web-llm"/>
|
||
</a>
|
||
|
||
<p align="right">
|
||
<a href="#top">⬆ 返回顶部 ⬆</a>
|
||
</p>
|