docs: make Chinese README the default

2026-07-13 10:38:53 +00:00
parent 7904c860b9
commit a139047db8
1 changed files with 146 additions and 156 deletions
@@ -1,3 +1,9 @@
+<!-- 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
@@ -8,84 +14,83 @@
 [![Related Repository: WebLLM Chat](https://img.shields.io/badge/Related_Repo-WebLLM_Chat-fafbfc?logo=github)](https://github.com/mlc-ai/web-llm-chat/)
 [![Related Repository: MLC LLM](https://img.shields.io/badge/Related_Repo-MLC_LLM-fafbfc?logo=github)](https://github.com/mlc-ai/mlc-llm/)

-**High-Performance In-Browser LLM Inference Engine.**
+**高性能浏览器内 LLM 推理引擎。**

-[Documentation](https://webllm.mlc.ai/docs/) | [Blogpost](https://blog.mlc.ai/2024/06/13/webllm-a-high-performance-in-browser-llm-inference-engine) | [Paper](https://arxiv.org/abs/2412.15803) | [Examples](examples)
+[文档](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>

-## Overview
+## 概述

-WebLLM is a high-performance in-browser LLM inference engine that brings language model inference directly onto web browsers with hardware acceleration.
-Everything runs inside the browser with no server support and is accelerated with WebGPU.
+WebLLM 是一款高性能的浏览器内 LLM 推理引擎，可将语言模型推理直接带到 Web 浏览器中，并利用硬件加速。
+一切都在浏览器内运行，无需服务器支持，并通过 WebGPU 加速。

-WebLLM is **fully compatible with [OpenAI API](https://platform.openai.com/docs/api-reference/chat).**
-That is, you can use the same OpenAI API on **any open source models** locally, with functionalities
-including streaming, JSON-mode, function-calling (WIP), etc.
+WebLLM **完全兼容 [OpenAI API](https://platform.openai.com/docs/api-reference/chat).**
+也就是说，你可以在本地对**任何开源模型**使用相同的 OpenAI API，功能包括流式输出、JSON 模式、函数调用（开发中）等。

-We can bring a lot of fun opportunities to build AI assistants for everyone and enable privacy while enjoying GPU acceleration.
+这为每个人构建 AI 助手带来了许多有趣的可能，并在享受 GPU 加速的同时保护隐私。

-You can use WebLLM as a base [npm package](https://www.npmjs.com/package/@mlc-ai/web-llm) and build your own web application on top of it by following the examples below. This project is a companion project of [MLC LLM](https://github.com/mlc-ai/mlc-llm), which enables universal deployment of LLM across hardware environments.
+你可以将 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">

-**[Check out WebLLM Chat to try it out!](https://chat.webllm.ai/)**
+**[体验 WebLLM Chat，立即试用！](https://chat.webllm.ai/)**

 </div>

-## Key Features
+## 核心特性

- **In-Browser Inference**: WebLLM is a high-performance, in-browser language model inference engine that leverages WebGPU for hardware acceleration, enabling powerful LLM operations directly within web browsers without server-side processing.
+- **浏览器内推理（In-Browser Inference）**：WebLLM 是一款高性能的浏览器内语言模型推理引擎，利用 WebGPU 进行硬件加速，使强大的 LLM 运算可直接在 Web 浏览器中完成，无需服务端处理。

- [**Full OpenAI API Compatibility**](#full-openai-compatibility): Seamlessly integrate your app with WebLLM using OpenAI API with functionalities such as streaming, JSON-mode, logit-level control, seeding, and more.
+- [**完整 OpenAI API 兼容性**](#full-openai-compatibility)：使用 OpenAI API 将你的应用与 WebLLM 无缝集成，支持流式输出、JSON 模式、logit 级控制、种子（seeding）等功能。

- **Structured JSON Generation**: WebLLM supports state-of-the-art JSON mode structured generation, implemented in the WebAssembly portion of the model library for optimal performance. Check [WebLLM JSON Playground](https://huggingface.co/spaces/mlc-ai/WebLLM-JSON-Playground) on HuggingFace to try generating JSON output with custom JSON schema.
+- **结构化 JSON 生成**：WebLLM 支持业界领先的 JSON 模式结构化生成，在模型库的 WebAssembly 部分实现以获得最佳性能。可在 HuggingFace 上的 [WebLLM JSON Playground](https://huggingface.co/spaces/mlc-ai/WebLLM-JSON-Playground) 试用使用自定义 JSON schema 生成 JSON 输出。

- [**Extensive Model Support**](#built-in-models): WebLLM natively supports a range of models including Llama 3, Phi 3, Gemma, Mistral, Qwen(通义千问), and many others, making it versatile for various AI tasks. For the complete supported model list, check [MLC Models](https://mlc.ai/models).
+- [**广泛的模型支持**](#built-in-models)：WebLLM 原生支持多种模型，包括 Llama 3、Phi 3、Gemma、Mistral、Qwen（通义千问）等，可胜任各类 AI 任务。完整支持模型列表请参见 [MLC Models](https://mlc.ai/models).

- [**Custom Model Integration**](#custom-models): Easily integrate and deploy custom models in MLC format, allowing you to adapt WebLLM to specific needs and scenarios, enhancing flexibility in model deployment.
+- [**自定义模型集成**](#custom-models)：可轻松集成并部署 MLC 格式的自定义模型，使 WebLLM 适应特定需求与场景，提升模型部署的灵活性。

- **Plug-and-Play Integration**: Easily integrate WebLLM into your projects using package managers like NPM and Yarn, or directly via CDN, complete with comprehensive [examples](./examples/) and a modular design for connecting with UI components.
+- **即插即用集成**：通过 NPM、Yarn 等包管理器或直接通过 CDN 轻松将 WebLLM 集成到项目中，配有全面的 [示例](./examples/) 和模块化设计，便于与 UI 组件对接。

- **Streaming & Real-Time Interactions**: Supports streaming chat completions, allowing real-time output generation which enhances interactive applications like chatbots and virtual assistants.
+- **流式输出与实时交互**：支持流式聊天补全，实现实时输出生成，增强聊天机器人和虚拟助手等交互式应用体验。

- **Web Worker & Service Worker Support**: Optimize UI performance and manage the lifecycle of models efficiently by offloading computations to separate worker threads or service workers.
+- **Web Worker 与 Service Worker 支持**：将计算卸载到独立 worker 线程或 service worker，优化 UI 性能并高效管理模型生命周期。

- **Chrome Extension Support**: Extend the functionality of web browsers through custom Chrome extensions using WebLLM, with examples available for building both basic and advanced extensions.
+- **Chrome 扩展支持**：通过自定义 Chrome 扩展扩展 Web 浏览器功能，提供构建基础与高级扩展的示例。

-## Built-in Models
+## 内置模型

-Check the complete list of available models on [MLC Models](https://mlc.ai/models). WebLLM supports a subset of these available models and the list can be accessed at [`prebuiltAppConfig.model_list`](https://github.com/mlc-ai/web-llm/blob/main/src/config.ts#L293).
+完整可用模型列表请参见 [MLC Models](https://mlc.ai/models).。WebLLM 支持其中一部分模型，列表可在 [`prebuiltAppConfig.model_list`](https://github.com/mlc-ai/web-llm/blob/main/src/config.ts#L293). 查看。

-Here are the primary families of models currently supported:
+以下是当前支持的主要模型系列：

- **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
+- **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

-If you need more models, [request a new model via opening an issue](https://github.com/mlc-ai/web-llm/issues/new/choose) or check [Custom Models](#custom-models) for how to compile and use your own models with WebLLM.
+如需更多模型，请[通过提交 issue 申请新模型](https://github.com/mlc-ai/web-llm/issues/new/choose)，或参阅 [自定义模型](#custom-models) 了解如何编译并在 WebLLM 中使用你自己的模型。

-## Jumpstart with Examples
+## 通过示例快速上手

-Learn how to use WebLLM to integrate large language models into your application and generate chat completions through this simple Chatbot example:
+通过以下简单的聊天机器人示例，学习如何使用 WebLLM 将大语言模型集成到应用中并生成聊天补全：

 [![Example Chatbot on JSFiddle](https://img.shields.io/badge/Example-JSFiddle-blue?logo=jsfiddle&logoColor=white)](https://jsfiddle.net/neetnestor/4nmgvsa2/)
 [![Example Chatbot on Codepen](https://img.shields.io/badge/Example-Codepen-gainsboro?logo=codepen)](https://codepen.io/neetnestor/pen/vYwgZaG)

-For an advanced example of a larger, more complicated project, check [WebLLM Chat](https://github.com/mlc-ai/web-llm-chat/blob/main/app/client/webllm.ts).
+如需更复杂的大型项目高级示例，请参阅 [WebLLM Chat](https://github.com/mlc-ai/web-llm-chat/blob/main/app/client/webllm.ts).

-More examples for different use cases are available in the [examples](./examples/) folder.
+更多针对不同用例的示例见 [examples](./examples/) 文件夹。

-## Get Started
+## 快速开始

-WebLLM offers a minimalist and modular interface to access the chatbot in the browser.
-The package is designed in a modular way to hook to any of the UI components.
+WebLLM 提供简洁、模块化的接口，可在浏览器中访问聊天机器人。
+该包采用模块化设计，可对接任意 UI 组件。

-### Installation
+### 安装

-#### Package Manager
+#### 包管理器

 ```sh
 # npm
@@ -96,7 +101,7 @@ yarn add @mlc-ai/web-llm
 pnpm install @mlc-ai/web-llm
 ```

-Then import the module in your code.
+然后在代码中导入该模块。

 ```typescript
 // Import everything
@@ -105,25 +110,25 @@ import * as webllm from "@mlc-ai/web-llm";
 import { CreateMLCEngine } from "@mlc-ai/web-llm";
 ```

-#### CDN Delivery
+#### CDN 分发

-Thanks to [jsdelivr.com](https://www.jsdelivr.com/package/npm/@mlc-ai/web-llm), WebLLM can be imported directly through URL and work out-of-the-box on cloud development platforms like [jsfiddle.net](https://jsfiddle.net/), [Codepen.io](https://codepen.io/), and [Scribbler](https://scribbler.live):
+借助 [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";
 ```

-It can also be dynamically imported as:
+也可以动态导入：

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

-### Create MLCEngine
+### 创建 MLCEngine

-Most operations in WebLLM are invoked through the `MLCEngine` interface. You can create an `MLCEngine` instance and loading the model by calling the `CreateMLCEngine()` factory function.
+WebLLM 中的大多数操作通过 `MLCEngine` 接口调用。你可以创建 `MLCEngine` 实例，并通过调用 `CreateMLCEngine()` 工厂函数加载模型。

-(Note that loading models requires downloading and it can take a significant amount of time for the very first run without caching previously. You should properly handle this asynchronous call.)
+（请注意，加载模型需要下载；若此前未缓存，首次运行可能耗时较长。你应妥善处理此异步调用。）

 ```typescript
 import { CreateMLCEngine } from "@mlc-ai/web-llm";
@@ -140,7 +145,7 @@ const engine = await CreateMLCEngine(
 );
 ```

-Under the hood, this factory function does the following steps for first creating an engine instance (synchronous) and then loading the model (asynchronous). You can also do them separately in your application.
+底层而言，该工厂函数会先同步创建引擎实例，再异步加载模型。你也可以在应用中分步执行这些操作。

 ```typescript
 import { MLCEngine } from "@mlc-ai/web-llm";
@@ -154,16 +159,16 @@ const engine = new MLCEngine({
 await engine.reload(selectedModel);
 ```

-### Cache Backend Policy
+### 缓存后端策略

-WebLLM supports four cache backends through `AppConfig.cacheBackend`:
+WebLLM 通过 `AppConfig.cacheBackend` 支持四种缓存后端：

- `"cache"`: browser [Cache API](https://developer.mozilla.org/en-US/docs/Web/API/Cache) (default).
- `"indexeddb"`: browser [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API).
- `"opfs"`: browser [Origin Private File System (OPFS)](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API/Origin_private_file_system).
- `"cross-origin"`: experimental Chrome [Cross-Origin Storage API](https://github.com/WICG/cross-origin-storage) extension backend. Install the [Cross-Origin Storage extension](https://chromewebstore.google.com/detail/cross-origin-storage/denpnpcgjgikjpoglpjefakmdcbmlgih) to use it. (If the extension isn't installed, WebLLM falls back to the default cache automatically.)
+- `"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 会自动回退到默认缓存。）

-Example:
+示例：

 ```typescript
 import { CreateMLCEngine, prebuiltAppConfig } from "@mlc-ai/web-llm";
@@ -174,17 +179,17 @@ const engine = await CreateMLCEngine("Llama-3.1-8B-Instruct-q4f32_1-MLC", {
 });
 ```

-Notes:
- If `"opfs"` is selected in an environment without OPFS support, cache operations fail with an OPFS availability error.
- When using `"opfs"`, `appConfig.opfsAccessMode` can be set to `"auto"` to use OPFS sync access handles where supported, or `"sync"` to require sync access handles. The default is `"async"`.
- The `"cross-origin"` backend requires installing and enabling a compatible browser extension.
- Cross-origin backend currently does not support programmatic tensor-cache deletion; clearing is extension-managed.
+说明：
+- 在不支持 OPFS 的环境中选择 `"opfs"` 时，缓存操作会因 OPFS 不可用而失败。
+- 使用 `"opfs"` 时，可将 `appConfig.opfsAccessMode` 设为 `"auto"`，在支持的情况下使用 OPFS 同步访问句柄（sync access handles）；或设为 `"sync"` 以强制要求同步访问句柄。默认值为 `"async"`。
+- `"cross-origin"` 后端需要安装并启用兼容的浏览器扩展。
+- 跨源（cross-origin）后端目前不支持以编程方式删除张量缓存（tensor-cache）；清理由扩展管理。

-### Chat Completion
+### 聊天补全（Chat Completion）

-After successfully initializing the engine, you can now invoke chat completions using OpenAI style chat APIs through the `engine.chat.completions` interface. For the full list of parameters and their descriptions, check [section below](#full-openai-compatibility) and [OpenAI API reference](https://platform.openai.com/docs/api-reference/chat/create).
+成功初始化引擎后，即可通过 `engine.chat.completions` 接口，以 OpenAI 风格的聊天 API 调用聊天补全。完整参数列表及说明请参阅[下文章节](#full-openai-compatibility)和 [OpenAI API reference](https://platform.openai.com/docs/api-reference/chat/create).

-(Note: The `model` parameter is not supported and will be ignored here. Instead, call `CreateMLCEngine(model)` or `engine.reload(model)` instead as shown in the [Create MLCEngine](#create-mlcengine) above.)
+（注意：此处不支持 `model` 参数，将被忽略。请改为调用 `CreateMLCEngine(model)` 或 `engine.reload(model)`，如上文 [Create MLCEngine](#create-mlcengine) 所示。）

 ```typescript
 const messages = [
@@ -199,9 +204,9 @@ console.log(reply.choices[0].message);
 console.log(reply.usage);
 ```

-### Streaming
+### 流式输出（Streaming）

-WebLLM also supports streaming chat completion generating. To use it, simply pass `stream: true` to the `engine.chat.completions.create` call.
+WebLLM 也支持流式生成聊天补全。使用时，只需在 `engine.chat.completions.create` 调用中传入 `stream: true`。

 ```typescript
 const messages = [
@@ -230,24 +235,22 @@ const fullReply = await engine.getMessage();
 console.log(fullReply);
 ```

-## Advanced Usage
+## 高级用法

-### Using Workers
+### 使用 Worker

-You can put the heavy computation in a worker script to optimize your application performance. To do so, you need to:
+可将重计算放入 worker 脚本以优化应用性能。为此需要：

-1. Create a handler in the worker thread that communicates with the frontend while handling the requests.
-2. Create a Worker Engine in your main application, which under the hood sends messages to the handler in the worker thread.
+1. 在 worker 线程中创建处理器（handler），在处理请求的同时与前端通信。
+2. 在主应用中创建 Worker Engine，其底层会向 worker 线程中的处理器发送消息。

-For detailed implementations of different kinds of Workers, check the following sections.
+不同 Worker 类型的具体实现请参阅以下章节。

-#### Dedicated Web Worker
+#### 专用 Web Worker

-WebLLM comes with API support for WebWorker so you can hook
-the generation process into a separate worker thread so that
-the computing in the worker thread won't disrupt the UI.
+WebLLM 提供 WebWorker API 支持，可将生成过程挂接到独立 worker 线程，避免 worker 线程中的计算阻塞 UI。

-We create a handler in the worker thread that communicates with the frontend while handling the requests.
+我们在 worker 线程中创建处理器，在处理请求的同时与前端通信。

 ```typescript
 // worker.ts
@@ -260,8 +263,7 @@ self.onmessage = (msg: MessageEvent) => {
 };
 ```

-In the main logic, we create a `WebWorkerMLCEngine` that
-implements the same `MLCEngineInterface`. The rest of the logic remains the same.
+在主逻辑中，我们创建实现相同 `MLCEngineInterface` 的 `WebWorkerMLCEngine`。其余逻辑保持不变。

 ```typescript
 // main.ts
@@ -281,15 +283,13 @@ async function main() {
 }
 ```

-### Use Service Worker
+### 使用 Service Worker

-WebLLM comes with API support for ServiceWorker so you can hook the generation process
-into a service worker to avoid reloading the model in every page visit and optimize
-your application's offline experience.
+WebLLM 提供 ServiceWorker API 支持，可将生成过程挂接到 service worker，避免每次访问页面都重新加载模型，并优化应用的离线体验。

-(Note, Service Worker's life cycle is managed by the browser and can be killed any time without notifying the webapp. `ServiceWorkerMLCEngine` will try to keep the service worker thread alive by periodically sending heartbeat events, but your application should also include proper error handling. Check `keepAliveMs` and `missedHeatbeat` in [`ServiceWorkerMLCEngine`](https://github.com/mlc-ai/web-llm/blob/main/src/service_worker.ts#L234) for more details.)
+（注意：Service Worker 的生命周期由浏览器管理，可能随时被终止且不会通知 Web 应用。`ServiceWorkerMLCEngine` 会尝试通过定期发送心跳事件保持 service worker 线程存活，但应用也应包含适当的错误处理。更多细节请参阅 [`ServiceWorkerMLCEngine`](https://github.com/mlc-ai/web-llm/blob/main/src/service_worker.ts#L234) 中的 `keepAliveMs` 和 `missedHeatbeat`。）

-We create a handler in the worker thread that communicates with the frontend while handling the requests.
+我们在 worker 线程中创建处理器，在处理请求的同时与前端通信。

 ```typescript
 // sw.ts
@@ -303,8 +303,7 @@ self.addEventListener("activate", function (event) {
 });
 ```

-Then in the main logic, we register the service worker and create the engine using
-`CreateServiceWorkerMLCEngine` function. The rest of the logic remains the same.
+然后在主逻辑中注册 service worker，并使用 `CreateServiceWorkerMLCEngine` 函数创建引擎。其余逻辑保持不变。

 ```typescript
 // main.ts
@@ -326,27 +325,25 @@ const engine: MLCEngineInterface = await CreateServiceWorkerMLCEngine(
 );
 ```

-You can find a complete example on how to run WebLLM in service worker in [examples/service-worker](examples/service-worker/).
+在 [examples/service-worker](examples/service-worker/) 中可找到在 service worker 中运行 WebLLM 的完整示例。

-### Chrome Extension
+### Chrome 扩展

-You can also find examples of building Chrome extension with WebLLM in [examples/chrome-extension](examples/chrome-extension/) and [examples/chrome-extension-webgpu-service-worker](examples/chrome-extension-webgpu-service-worker/). The latter one leverages service worker, so the extension is persistent in the background. Additionally, you can explore another full project of a Chrome extension, WebLLM Assistant, which leverages WebLLM [here](https://github.com/mlc-ai/web-llm-assistant).
+也可在 [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).

-## Full OpenAI Compatibility
+## 完整 OpenAI 兼容性

-WebLLM is designed to be fully compatible with [OpenAI API](https://platform.openai.com/docs/api-reference/chat). Thus, besides building a simple chatbot, you can also have the following functionalities with WebLLM:
+WebLLM 设计为与 [OpenAI API](https://platform.openai.com/docs/api-reference/chat). 完全兼容。因此，除构建简单聊天机器人外，还可通过 WebLLM 实现以下功能：

- [streaming](examples/streaming): return output as chunks in real-time in the form of an AsyncGenerator
- [json-mode](examples/json-mode): efficiently ensure output is in JSON format, see [OpenAI Reference](https://platform.openai.com/docs/guides/text-generation/chat-completions-api) for more.
- [seed-to-reproduce](examples/seed-to-reproduce): use seeding to ensure a reproducible output with fields `seed`.
- [function-calling](examples/function-calling) (WIP): function calling with fields `tools` and `tool_choice` (with preliminary support); or manual function calling without `tools` or `tool_choice` (keeps the most flexibility).
+- [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` 进行手动函数调用（灵活性最高）

-## Integrity Verification
+## 完整性验证

-WebLLM supports optional integrity verification for model artifacts using
-[SRI (Subresource Integrity)](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) hashes.
-When the `integrity` field is set on a `ModelRecord`, WebLLM will verify the downloaded config,
-WASM, and tokenizer files against the provided hashes before loading.
+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";
@@ -375,7 +372,7 @@ const engine = await CreateMLCEngine("Llama-3.2-1B-Instruct-q4f16_1-MLC", {
 });
 ```

-You can generate SRI hashes for model files with:
+你可以使用以下方式为模型文件生成 SRI 哈希值：

 ```bash
 # SHA-256
@@ -386,27 +383,25 @@ openssl dgst -sha384 -binary <file> | openssl base64 -A | sed 's/^/sha384-/'
 openssl dgst -sha512 -binary <file> | openssl base64 -A | sed 's/^/sha512-/'
 ```

-> The `openssl` commands require a Unix-like shell (macOS/Linux). On Windows, run `openssl` via [Git Bash](https://gitforwindows.org/) or [WSL](https://learn.microsoft.com/en-us/windows/wsl/).
+> `openssl` 命令需要类 Unix shell（macOS/Linux）。在 Windows 上，可通过 [Git Bash](https://gitforwindows.org/) 或 [WSL](https://learn.microsoft.com/en-us/windows/wsl/). 运行 `openssl`。

-If a hash does not match, an `IntegrityError` is thrown (or a warning is logged when `onFailure: "warn"`).
-All fields in `integrity` are optional — only specified artifacts will be verified.
-When the `integrity` field is omitted entirely, WebLLM behaves exactly as before (no verification).
+如果哈希值不匹配，将抛出 `IntegrityError`（或在 `onFailure: "warn"` 时记录警告）。
+`integrity` 中的所有字段均为可选 — 仅会验证已指定的构件。
+当完全省略 `integrity` 字段时，WebLLM 的行为与之前完全相同（不进行验证）。

-See the [integrity-verification example](examples/integrity-verification/) for a complete working demo.
+请参阅 [integrity-verification 示例](examples/integrity-verification/) 获取完整可运行的演示。

-## Custom Models
+## 自定义模型

-WebLLM works as a companion project of [MLC LLM](https://github.com/mlc-ai/mlc-llm) and it supports custom models in MLC format.
-It reuses the model artifact and builds the flow of MLC LLM. To compile and use your own models with WebLLM, please check out
-[MLC LLM document](https://llm.mlc.ai/docs/deploy/webllm.html)
-on how to compile and deploy new model weights and libraries to WebLLM.
+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。

-Here, we go over the high-level idea. There are two elements of the WebLLM package that enable new models and weight variants.
+此处我们概述高层次思路。WebLLM 包中有两个要素可启用新模型和权重变体。

- `model`: Contains a URL to model artifacts, such as weights and meta-data.
- `model_lib`: A URL to the web assembly library (i.e. wasm file) that contains the executables to accelerate the model computations.
+- `model`：包含指向模型构件（如权重和元数据）的 URL。
+- `model_lib`：指向 WebAssembly 库（即 wasm 文件）的 URL，其中包含用于加速模型计算的可执行代码。

-Both are customizable in the WebLLM.
+两者在 WebLLM 中均可自定义。

 ```typescript
 import { CreateMLCEngine } from "@mlc-ai/web-llm";
@@ -440,26 +435,23 @@ async main() {
 }
 ```

-In many cases, we only want to supply the model weight variant, but
-not necessarily a new model (e.g. `NeuralHermes-Mistral` can reuse `Mistral`'s
-model library). For examples of how a model library can be shared by different model variants,
-see `webllm.prebuiltAppConfig`.
+在许多情况下，我们只需提供模型权重变体，而不一定需要新模型（例如 `NeuralHermes-Mistral` 可以复用 `Mistral` 的模型库）。有关不同模型变体如何共享模型库的示例，请参阅 `webllm.prebuiltAppConfig`。

-## Build WebLLM Package From Source
+## 从源码构建 WebLLM 包

-NOTE: you don't need to build from source unless you would like to modify the WebLLM package.
-To use the npm, simply follow [Get Started](#get-started) or any of the [examples](examples) instead.
+注意：除非你想修改 WebLLM 包，否则无需从源码构建。
+要使用 npm，只需按照 [Get Started](#get-started) 或任一 [examples](examples) 操作即可。

-To build from source, simply run:
+要从源码构建，只需运行：

 ```bash
 npm install
 npm run build
 ```

-Then, to test the effects of your code change in an example, inside `examples/get-started/package.json`, change from `"@mlc-ai/web-llm": "^0.2.84"` to `"@mlc-ai/web-llm": ../..`.
+然后，要在示例中测试代码更改的效果，在 `examples/get-started/package.json` 内，将 `"@mlc-ai/web-llm": "^0.2.84"` 改为 `"@mlc-ai/web-llm": ../..`。

-Then run:
+然后运行：

 ```bash
 cd examples/get-started
@@ -467,7 +459,7 @@ npm install
 npm start
 ```

-Note that sometimes you would need to switch between `file:../..` and `../..` to trigger npm to recognize new changes. In the worst case, you can run:
+请注意，有时你需要在 `file:../..` 与 `../..` 之间切换，以让 npm 识别新更改。最坏情况下，可以运行：

 ```bash
 cd examples/get-started
@@ -476,73 +468,71 @@ npm install
 npm start
 ```

-### In case you need to build TVMjs from source
+### 如需从源码构建 TVMjs

-WebLLM's runtime largely depends on TVMjs: https://github.com/apache/tvm/tree/main/web
+WebLLM 的运行时在很大程度上依赖于 TVMjs：https://github.com/apache/tvm/tree/main/web

-While it is also available as an npm package: https://www.npmjs.com/package/@mlc-ai/web-runtime, you can build it from source if needed by following the steps below.
+虽然它也可作为 npm 包获取：https://www.npmjs.com/package/@mlc-ai/web-runtime,，如有需要，可按以下步骤从源码构建。

-1. Install [emscripten](https://emscripten.org). It is an LLVM-based compiler that compiles C/C++ source code to WebAssembly.
-   - Follow the [installation instruction](https://emscripten.org/docs/getting_started/downloads.html#installation-instructions-using-the-emsdk-recommended) to install the latest emsdk.
-   - Source `emsdk_env.sh` by `source path/to/emsdk_env.sh`, so that `emcc` is reachable from PATH and the command `emcc` works.
+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` 命令可用。

-   We can verify the successful installation by trying out `emcc` terminal.
+   我们可通过在终端尝试 `emcc` 来验证安装是否成功。

-   Note: We recently found that using the latest `emcc` version may run into issues during runtime. Use `./emsdk install 3.1.56` instead of `./emsdk install latest` for now as a workaround. The error may look like
+   注意：我们最近发现使用最新的 `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. In `./package.json`, change from `"@mlc-ai/web-runtime": "0.18.0-dev2",` to `"@mlc-ai/web-runtime": "file:./tvm_home/web",`.
+2. 在 `./package.json` 中，将 `"@mlc-ai/web-runtime": "0.18.0-dev2",` 改为 `"@mlc-ai/web-runtime": "file:./tvm_home/web",`。

-3. Setup necessary environment
+3. 配置必要环境

-   Prepare all the necessary dependencies for web build:
+   准备 Web 构建所需的全部依赖：

   ```shell
   ./scripts/prep_deps.sh
   ```

-   In this step, if `$TVM_SOURCE_DIR` is not defined in the environment, we will execute the following line to build `tvmjs` dependency:
+   在此步骤中，如果环境中未定义 `$TVM_SOURCE_DIR`，我们将执行以下命令以构建 `tvmjs` 依赖：

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

-   This clones the current HEAD of `mlc-ai/relax`. However, it may not always be the correct branch or commit to clone. To build a specific npm version from source, refer to the version bump PR, which states which branch (i.e. `mlc-ai/relax` or `apache/tvm`) and which commit the current WebLLM version depends on. For instance, version 0.2.52, according to its version bump PR https://github.com/mlc-ai/web-llm/pull/521, is built by checking out the following commit https://github.com/apache/tvm/commit/e6476847753c80e054719ac47bc2091c888418b6 in `apache/tvm`, rather than the HEAD of `mlc-ai/relax`.
+   这将克隆 `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。

-   Besides, `--recursive` is necessary and important. Otherwise, you may encounter errors like `fatal error: 'dlpack/dlpack.h' file not found`.
+   此外，`--recursive` 是必要且重要的。否则，你可能会遇到类似 `fatal error: 'dlpack/dlpack.h' file not found` 的错误。

-4. Build WebLLM Package
+4. 构建 WebLLM 包

   ```shell
   npm run build
   ```

-5. Validate some of the sub-packages
+5. 验证部分子包

-   You can then go to the subfolders in [examples](examples) to validate some of the sub-packages.
-   We use Parcelv2 for bundling. Although Parcel is not very good at tracking parent directory
-   changes sometimes. When you make a change in the WebLLM package, try to edit the `package.json`
-   of the subfolder and save it, which will trigger Parcel to rebuild.
+   然后可进入 [examples](examples) 中的子文件夹，验证部分子包。
+   我们使用 Parcelv2 进行打包。尽管 Parcel 有时不太擅长跟踪父目录的更改。当你在 WebLLM 包中做出更改时，尝试编辑子文件夹的 `package.json` 并保存，这将触发 Parcel 重新构建。

-## Links
+## 链接

- [Demo App: WebLLM Chat](https://chat.webllm.ai/)
- If you want to run LLM on native runtime, check out [MLC-LLM](https://github.com/mlc-ai/mlc-llm)
- You might also be interested in [Web Stable Diffusion](https://github.com/mlc-ai/web-stable-diffusion/).
+- [演示应用：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/). 感兴趣

-## Acknowledgement
+## 致谢

-This project is initiated by members from CMU Catalyst, UW SAMPL, SJTU, OctoML, and the MLC community. We would love to continue developing and supporting the open-source ML community.
+本项目由 CMU Catalyst、UW SAMPL、SJTU、OctoML 及 MLC 社区的成员发起。我们希望能够继续开发并支持开源机器学习（ML）社区。

-This project is only possible thanks to the shoulders open-source ecosystems that we stand on. We want to thank the Apache TVM community and developers of the TVM Unity effort. The open-source ML community members made these models publicly available. PyTorch and Hugging Face communities make these models accessible. We would like to thank the teams behind Vicuna, SentencePiece, LLaMA, and Alpaca. We also would like to thank the WebAssembly, Emscripten, and WebGPU communities. Finally, thanks to Dawn and WebGPU developers.
+本项目的实现，离不开我们所依托的开源生态。我们想要感谢 Apache TVM 社区以及 TVM Unity 工作的开发者。开源 ML 社区的成员使这些模型得以公开发布。PyTorch 和 Hugging Face 社区使这些模型更易于获取。我们还要感谢 Vicuna、SentencePiece、LLaMA 和 Alpaca 背后的团队。同时也要感谢 WebAssembly、Emscripten 和 WebGPU 社区。最后，感谢 Dawn 和 WebGPU 开发者。

-## Citation
+## 引用

-If you find this project to be useful, please cite:
+如果您觉得本项目对您有帮助，欢迎引用：

 ```
@misc{ruan2026webllmhighperformanceinbrowserllm,
@@ -556,12 +546,12 @@ If you find this project to be useful, please cite:
 }
 ```

-## Contributors
+## 贡献者

 <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">⬆ Back to Top ⬆</a>
+  <a href="#top">⬆ 返回顶部 ⬆</a>
 </p>