浏览器内模型

createWebLLM 借助 WebLLM，直接在浏览器中通过 WebGPU 运行开源模型（Llama、Qwen、SmolLM、Phi、Gemma……）。请求不会离开设备，因此你不需要 API key、服务器，也无需按 token 付费。

在在线体验中试试 →

安装

WebLLM 是一个可选的 peer 依赖：仅在使用该提供方时才需要安装。

bash

npm i @mlc-ai/web-llm

用法

import { CreateMLCEngine } from '@mlc-ai/web-llm'
import { useChat } from 'vue-llm'
import { createWebLLM } from 'vue-llm/providers'

const ai = createWebLLM({ createEngine: CreateMLCEngine })

const { messages, sendMessage } = useChat({
  provider: ai,
  model: 'Llama-3.2-1B-Instruct-q4f16_1-MLC',
})

第一次请求会下载并编译模型。浏览器会缓存模型权重，之后再次访问只需几秒即可启动。WebLLM prebuiltAppConfig 中的任意模型 ID 都可以使用，也可以通过 engineConfig.appConfig 添加你自己的模型。

加载进度

模型体积有数百 MB，因此应展示加载进度，并在第一条消息之前提前加载：

vue

<script setup lang="ts">
const progress = ref(0)
const status = ref('')

const ai = createWebLLM({
  createEngine: CreateMLCEngine,
  onProgress: report => {
    progress.value = report.progress // 0..1
    status.value = report.text
  },
})

const model = 'Qwen2.5-0.5B-Instruct-q4f16_1-MLC'
const { messages, input, handleSubmit } = useChat({ provider: ai, model })

onMounted(() => ai.load(model))
</script>

成员	说明
`load(model)`	下载并编译模型。并发调用会被去重。
`unload()`	释放 GPU 内存。下一次请求会重新加载模型。
`loadedModel`	当前位于 GPU 上的模型

在主线程之外运行

推理主要受 GPU 限制，但分词和调度仍然在 JavaScript 中运行。将引擎移到 Web Worker 中，可以保持 UI 流畅：

// webllm.worker.ts
import { WebWorkerMLCEngineHandler } from '@mlc-ai/web-llm'

const handler = new WebWorkerMLCEngineHandler()
self.onmessage = (message: MessageEvent) => handler.onmessage(message)

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

const ai = createWebLLM({
  createEngine: (model, engineConfig, chatOptions) => CreateWebWorkerMLCEngine(
    new Worker(new URL('./webllm.worker.ts', import.meta.url), { type: 'module' }),
    model, engineConfig, chatOptions,
  ),
})

切换模型

在每个组合式函数中，model 都接受 ref 或 getter。提供方会在下一次请求时卸载旧模型并加载新模型：

const model = ref('SmolLM2-360M-Instruct-q4f16_1-MLC')
const chat = useChat({ provider: ai, model })

model.value = 'Llama-3.2-1B-Instruct-q4f16_1-MLC'

选择模型

模型	下载大小	备注
`SmolLM2-360M-Instruct-q4f16_1-MLC`	~380 MB	加载最快，适合简单任务
`Qwen2.5-0.5B-Instruct-q4f16_1-MLC`	~950 MB	综合表现不错
`Llama-3.2-1B-Instruct-q4f16_1-MLC`	~880 MB	回答质量更好
`Qwen3-0.6B-q4f16_1-MLC`	~1.4 GB	以 `reasoning` part 流式输出推理过程
`Hermes-3-Llama-3.2-3B-q4f16_1-MLC`	~2.3 GB	工具调用
`Phi-3.5-vision-instruct-q4f16_1-MLC`	~4.5 GB	图片输入

功能

流式输出、stop()（会中断 GPU 上的生成）以及 token usage。
推理： Qwen3 和 DeepSeek-R1 蒸馏模型输出的 <think>…</think> 块会以 reasoning part 的形式流式输出。
工具： tools 和 onToolCall 可用于 Hermes 等支持函数调用的模型。
附件： 视觉模型支持图片，文本文件会被内联。其他文件类型会抛出错误。
选项： providerOptions 接受 temperature、top_p、max_tokens（或 maxTokens）、frequency_penalty、presence_penalty、seed、stop、logit_bias、response_format 和 extra_body。

浏览器支持

桌面端 Chrome 和 Edge 113+、Android 上的 Chrome 以及 Safari 26+ 已内置 WebGPU。在提供该功能前请先检测支持情况：

import { createSSEProvider, isWebGPUSupported } from 'vue-llm/providers'

const ai = isWebGPUSupported()
  ? createWebLLM({ createEngine: CreateMLCEngine })
  : createSSEProvider({ url: '/api/chat' }) // fall back to your server

缺少 WebGPU 时，validateConfig() 会抛出清晰的错误，useChat 会通过 error 暴露该错误。

内存

模型所需的 GPU 内存大致等于其下载大小。在内存较小的设备上，请选择更小的模型，或调低 chatOptions.context_window_size。

浏览器内模型 ​

安装 ​

用法 ​

加载进度 ​

在主线程之外运行 ​

切换模型 ​

选择模型 ​

功能 ​

浏览器支持 ​