AI × Frontend

AI 驱动的
前端新范式

想象一下:你的浏览器不再只是一个"展示信息的窗口", 而是一台自带大脑的智能终端。 WebLLM 让大语言模型直接在浏览器的 GPU 上运行—— 就像把一台 AI 服务器塞进了用户的标签页。

100%
浏览器端推理
0$
API 调用费用
42 t/s
1B 模型推理速度
WebGPU
底层加速引擎
L2 · 为什么需要

传统 AI 前端集成的三大痛点

在 WebLLM 出现之前,前端想用 AI,必须忍受以下问题——

延迟地狱

每次 AI 请求都要跨越太平洋往返服务器。GPT-4o 的 P50 延迟为 800ms-2s,在 3G 网络下可飙升至 8s+。用户等得起,体验等不起。

客户机 → TLS握手 → 跨洋 → API网关 → GPU推理 → 响应
每一步都是延迟来源

隐私裸奔

用户的健康数据、法律文档、商业机密全都要发送到第三方服务器。GDPR 合规?HIPAA 合规?每一条请求都是一次合规赌博。

⚠️ 2023年三星芯片设计源码因员工粘贴到 ChatGPT 导致泄露,直接禁用全公司 API

成本失控

GPT-4o 输入 $2.5/M tokens,输出 $10/M tokens。一个每天 10 万用户的 AI 助手月均 API 成本轻松破万刀。C 端产品根本扛不住。

10万 DAU × 20次/天 =
~$6,000/月 (仅 API)
传统方案
用户输入 → API 调用 → 等待 1-5s → 渲染
数据离开浏览器,无法保证隐私
按 token 计费,规模化成本指数增长
离线时完全不可用
受限于 API 速率限制 (Rate Limit)
WebLLM 方案
用户输入 → 本地 GPU 推理 → 即时渲染
数据永不出浏览器,端到端零泄露
零边际成本,用户承担算力
完全离线可用,断网也能推理
无速率限制,并发只受硬件约束
L3 · 核心原理

WebLLM 是怎么在浏览器里跑 LLM 的?

从 WebGPU 到模型量化,拆解浏览器端 AI 推理的每一层技术栈

🏗️ 架构层级探索器点击各层查看详情

WebGPU:浏览器的 GPU 钥匙

WebGL 时代,浏览器只能用 GPU 画三角形。WebGPU 是 W3C 2023 年发布的新标准, 允许浏览器直接调度 GPU 的 Compute Shader——这正是矩阵乘法所需的核心能力。

🔴
WebGL 2.0 (2017)
仅图形管线,无 Compute Shader
🟢
WebGPU (2023)
Compute Shader + Storage Buffer,LLM 可用

量化:把大象装进冰箱

一个 FP16 的 7B 模型需要 14GB 显存,浏览器根本放不下。量化 (Quantization) 将权重精度从 FP16 压缩到 INT4/INT8, 模型大小直降 75%,精度损失仅 1-3%。

精度7B 模型大小精度损失浏览器可用?
FP1614 GB
INT87 GB~1%⚠️ 勉强
INT43.5 GB~2-3%

完整推理数据流

💬用户输入
🔤Tokenizer 分词
🔢Token IDs → GPU Buffer
🧠Transformer × N 层
📊Logits 概率分布
🎲采样 Top-P/K
📝解码 → 文字
流式 输出
L4 · 代码实战

从零构建 AI 驱动的前端应用

三个递进的真实代码示例:Vercel AI SDK → WebLLM 本地推理 → 混合架构

1

Vercel AI SDK — 最快的流式对话起步

推荐

Vercel AI SDK 的 useChat hook 封装了流式传输、状态管理、错误重试——10 行代码搞定一个 ChatGPT 级别的对话 UI。

app/api/chat/route.ts — 服务端路由typescript
import { openai } from "@ai-sdk/openai";
import { streamText } from "ai"; // ← Vercel AI SDK 核心

export const runtime = "edge"; // ← 关键:使用 Edge Runtime,首字延迟降至 ~100ms

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = streamText({
    model: openai("gpt-4o"),
    system: "你是一个专业的前端工程师助手。",
    messages,
    maxTokens: 1024,
    temperature: 0.7, // ← 交互式实验场里我们验证过的最佳值
  });

  return result.toDataStreamResponse(); // ← 自动处理 SSE 流式协议
}
components/ChatUI.tsx — 客户端组件tsx
"use client";
import { useChat } from "@ai-sdk/react"; // ← 一行搞定所有状态

export function ChatUI() {
  const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat({
    api: "/api/chat",
    maxSteps: 5, // ← 支持多轮工具调用(tool calling)
    onFinish: (message) => {
      console.log("Token usage:", message.usage); // ← 追踪 token 消耗
    },
  });

  return (
    <div className="flex flex-col h-screen max-w-2xl mx-auto">
      {/* 消息列表 */}
      <div className="flex-1 overflow-y-auto p-4 space-y-4">
        {messages.map((m) => (
          <div key={m.id} className={m.role === "user" ? "text-right" : "text-left"}>
            <span className="inline-block px-4 py-2 rounded-2xl max-w-[80%]
              bg-white border-2 border-[var(--foreground)]
              shadow-[4px_4px_0px_0px_var(--foreground)]">
              {m.content} {/* ← 流式更新:每个 token 到达时自动 re-render */}
            </span>
          </div>
        ))}
      </div>

      {/* 输入框 */}
      <form onSubmit={handleSubmit} className="p-4 border-t-2 border-[var(--foreground)]">
        <div className="flex gap-2">
          <input
            value={input}
            onChange={handleInputChange}
            placeholder="问点什么..."
            className="flex-1 px-4 py-3 rounded-xl border-2 border-[var(--foreground)]
              focus:outline-none focus:ring-2 focus:ring-[var(--accent)]"
          />
          <button
            type="submit"
            disabled={isLoading}
            className="px-6 py-3 bg-[var(--accent)] text-white font-bold rounded-xl
              border-2 border-[var(--foreground)] shadow-[4px_4px_0px_0px_var(--foreground)]
              hover:translate-y-[2px] hover:shadow-[2px_2px_0px_0px_var(--foreground)]
              active:translate-y-[4px] active:shadow-none transition-all"
          >
            {isLoading ? "思考中..." : "发送"}
          </button>
        </div>
      </form>
    </div>
  );
}
2

WebLLM — 浏览器内的完整推理引擎

本地运行

WebLLM 将 Hugging Face 上的模型编译为 WebGPU shader,直接在浏览器 GPU 上运行。 首次加载模型需下载权重(~1GB),后续从 IndexedDB 缓存读取仅需 2-5 秒

lib/webllm-engine.ts — 引擎初始化typescript
import * as webllm from "@mlc-ai/web-llm";

// 模型配置:选择量化版本以适配浏览器
const MODEL_CONFIG: webllm.ModelRecord = {
  model: "https://huggingface.co/mlc-ai/Qwen2.5-1.5B-Instruct-q4f16_1-MLC",
  model_id: "Qwen2.5-1.5B-Instruct-q4f16_1", // ← q4 = INT4量化, f16 = 权重FP16
  model_lib: webllm.modelLibURLPrefix + "v0_2_48/Qwen2-1.5B-q4f16_1-ctx4k_cs1k-webgpu.wasm",
  overrides: {
    context_window_size: 4096, // ← 上下文窗口
  },
};

let engine: webllm.MLCEngine | null = null;

export async function initEngine(
  onProgress: (progress: webllm.InitProgressReport) => void
) {
  if (engine) return engine;

  engine = await webllm.CreateMLCEngine(MODEL_CONFIG.model_id, {
    initProgressCallback: onProgress, // ← 进度回调:模型加载 0% → 100%
    logLevel: "INFO",
  });

  return engine;
}

// 流式推理:与 GPT API 几乎相同的接口
export async function* streamChat(prompt: string) {
  if (!engine) throw new Error("Engine not initialized");

  const chunks = await engine.chat.completions.create({
    messages: [{ role: "user", content: prompt }],
    temperature: 0.7,
    max_tokens: 512,
    stream: true, // ← 关键:开启流式输出
  });

  for await (const chunk of chunks) {
    const content = chunk.choices[0]?.delta?.content;
    if (content) yield content; // ← 逐 token yield
  }
}
components/LocalAI.tsx — 使用 WebLLM 的 React 组件tsx
"use client";
import { useState, useCallback } from "react";
import { initEngine, streamChat } from "@/lib/webllm-engine";

export function LocalAI() {
  const [loading, setLoading] = useState(false);
  const [loadProgress, setLoadProgress] = useState(0);
  const [response, setResponse] = useState("");
  const [isStreaming, setIsStreaming] = useState(false);

  // 1. 初始化引擎(只需一次)
  const handleInit = useCallback(async () => {
    setLoading(true);
    await initEngine((progress) => {
      setLoadProgress(Math.round(progress.progress * 100)); // ← "Loading model: 45%"
    });
    setLoading(false);
  }, []);

  // 2. 发起推理
  const handleGenerate = useCallback(async (prompt: string) => {
    setResponse("");
    setIsStreaming(true);

    try {
      for await (const token of streamChat(prompt)) {
        setResponse((prev) => prev + token); // ← 逐字追加,实现打字机效果
      }
    } finally {
      setIsStreaming(false);
    }
  }, []);

  return (
    <div className="p-6">
      {!engine && (
        <button onClick={handleInit} disabled={loading}>
          {loading ? `加载中 ${loadProgress}%...` : "🧠 初始化本地模型"}
        </button>
      )}

      {loading && (
        <div className="mt-4 h-3 bg-gray-200 rounded-full overflow-hidden border-2 border-[var(--foreground)]">
          <div
            className="h-full bg-[var(--accent)] transition-all duration-300"
            style={{ width: `${loadProgress}%` }}
          />
        </div>
      )}

      <button onClick={() => handleGenerate("用一句话解释 WebGPU")}>
        ⚡ 本地推理
      </button>

      <p className="mt-4 whitespace-pre-wrap">{response}</p>
    </div>
  );
}
3

混合架构 — 智能路由,按需选择

生产级

真实项目中,本地小模型处理简单任务(语法检查、代码补全),复杂任务路由到云端大模型(GPT-4o / Claude)。 这就是「混合推理架构」——兼顾隐私、成本和能力。

lib/hybrid-router.ts — 智能推理路由typescript
import { streamChat as localChat } from "./webllm-engine";
import { openai } from "@ai-sdk/openai";
import { streamText } from "ai";

type TaskType = "simple" | "complex" | "private";

// 路由策略:根据任务类型选择推理后端
function routeInference(taskType: TaskType) {
  const strategies = {
    simple:  "local",   // ← 代码补全、语法检查、简单问答 → 本地小模型
    complex: "cloud",   // ← 长文分析、多步推理、创意写作 → 云端大模型
    private: "local",   // ← 涉及敏感数据 → 强制本地,数据不出浏览器
  } as const;
  return strategies[taskType];
}

// 统一接口:对外暴露相同的流式 API
export async function* smartChat(
  messages: Message[],
  taskType: TaskType = "simple"
) {
  const target = routeInference(taskType);

  if (target === "local") {
    // 本地 WebLLM 推理
    const lastMsg = messages[messages.length - 1].content;
    yield* localChat(lastMsg);
  } else {
    // 云端 API 推理
    const result = streamText({
      model: openai("gpt-4o"),
      messages,
      temperature: 0.7,
    });

    for await (const chunk of result.textStream) {
      yield chunk;
    }
  }
}

// 自动分类:使用简单的启发式规则(可替换为分类模型)
export function classifyTask(prompt: string): TaskType {
  const sensitiveKeywords = ["密码", "token", "key", "secret", "私钥"];
  const complexKeywords = ["分析", "比较", "总结", "写一篇", "设计一个"];

  if (sensitiveKeywords.some((k) => prompt.includes(k))) return "private";
  if (complexKeywords.some((k) => prompt.includes(k))) return "complex";
  if (prompt.length > 500) return "complex"; // ← 长 prompt 通常需要更强的模型
  return "simple";
}

🎛️ 流式输出体验演示

Token 流式输出模拟~40 tokens/s
点击下方按钮体验 token 流式效果…
🌡️ Temperature 可视化
0.70
0 (确定性)2 (随机)
0.90
0.1 (聚焦)1.0 (全开)
Token 概率分布 (简化示意)
73%
20%
5%
1%
0%
0%
0%
0%
0%
0%
⚖️ Temperature ~0.7 → 平衡创造性和连贯性,多数场景推荐值
L5 · 工程全景

生产级 AI 前端的关键决策

模型选型、性能陷阱、安全考量——从 Demo 到 Production 的鸿沟

⚡ 延迟对比实验场Interactive
101024
云端 API (GPT-4o)更快 ✨
RTT 延迟50ms
生成速度~30 tokens/s
输出 tokens200
总延迟~6.8s
WebLLM (本地)
模型加载18s (首次)
生成速度~42 tokens/s
输出 tokens200
总延迟~22.8s
💡 洞察:高速网络下,云端 API 通常更快——但 WebLLM 胜在零 API 费用和完全隐私。
浏览器端模型选型速查
模型参数量量化后大小速度 (M2 MacBook)适合场景推荐度
Qwen2.5-0.5B0.5B~350MB85 t/s代码补全、简单QA⭐⭐⭐
Llama3.2-1B1B~650MB42 t/s通用对话、摘要⭐⭐⭐⭐
Phi-3.5-3.8B3.8B~2.2GB12 t/s复杂推理、多语言⭐⭐⭐⭐⭐
Gemma2-2B2B~1.3GB22 t/s指令跟随、工具调用⭐⭐⭐⭐
SmolLM2-1.7B1.7B~1.0GB28 t/s轻量助手、移动端⭐⭐⭐⭐

⚠️ 常见陷阱与反模式

🚫

陷阱 #1:不做模型缓存

每次刷新页面都重新下载 1GB 模型权重?用户体验直接归零。

❌ 错误
// 每次都重新初始化
const engine = await CreateMLCEngine(
  modelId
); // 下载 1GB...
✅ 正确
// 检查 IndexedDB 缓存
const cached = await caches.match(
  modelUrl
);
if (cached) { /* 直接读取 */ }
🚫

陷阱 #2:阻塞主线程

推理运算量极大,直接在主线程调用会让 UI 冻结 3-10 秒。

❌ 错误
// 主线程推理 → UI 冻结!
const result = await engine.chat(
  messages
);
✅ 正确
// WebLLM 内部已使用 Web Worker
// 但仍需流式更新 UI:
for await (const chunk of stream) {
  appendToken(chunk); // 非阻塞
}
⚠️

陷阱 #3:忽视设备差异

3.8B 模型在 MacBook M2 上跑 12 tokens/s,在低端安卓上可能只有 1 token/s。必须做设备适配。

自适应模型选择typescript
async function selectModelForDevice() {
  const adapter = await navigator.gpu.requestAdapter();
  const device = await adapter?.requestDevice();

  // 检测 GPU 内存(WebGPU 特有 API)
  const limits = device?.limits;
  const maxBuffer = limits?.maxStorageBufferBindingSize ?? 0;

  // 策略:GPU 内存 > 2GB 用大模型,否则用小模型
  if (maxBuffer > 2 * 1024 ** 3) {
    return "Phi-3.5-3.8B";  // ← 高端设备
  } else if (maxBuffer > 1 * 1024 ** 3) {
    return "Llama3.2-1B";   // ← 中端设备
  } else {
    return "Qwen2.5-0.5B";  // ← 低端设备 / 移动端
  }
}
⚠️

陷阱 #4:WebGPU 兼容性

WebGPU 截至 2025 年仅 Chrome / Edge / Firefox Nightly 支持,Safari 仍在实验阶段。必须有 fallback 方案。

🟢 Chrome 113+ — 完全支持
🟢 Edge 113+ — 完全支持
🟡 Firefox Nightly — 实验性 flag
🟡 Safari 18+ — 技术预览版
🔴 移动端浏览器 — 极有限支持

真实性能基准 (Apple M2, 16GB)

18s
首次加载 (冷启动)
下载 + 编译 shader + 加载权重到 GPU
3.2s
缓存加载 (热启动)
IndexedDB 缓存命中,仅需 GPU 上传
42 t/s
推理速度 (Llama3.2-1B)
首字延迟 ~50ms,与 GPT-3.5 感知相当
决策矩阵:何时用 WebLLM vs 云端 API
场景推荐方案原因
医疗/法律文档分析🏠 本地 WebLLM数据合规强制要求零泄露
实时代码补全 (IDE)🏠 本地 WebLLM延迟敏感,<50ms 首字要求
深度论文分析☁️ 云端 API需要 100K+ context window 和强推理
离线笔记应用🏠 本地 WebLLM离线可用是核心卖点
企业客服机器人🔄 混合架构简单问题本地答,复杂问题转人工/API
多语言实时翻译🏠 本地 WebLLM高频低延迟,API 成本不可接受
AI 图片生成☁️ 云端 APISDXL 级模型无法在浏览器运行
速查清单

AI × 前端 开发速查表

一页纸搞定 WebLLM + Vercel AI SDK 的所有关键 API

安装 WebLLM
npm install @mlc-ai/web-llm
安装 Vercel AI SDK
npm install ai @ai-sdk/openai
流式响应 (Server)
const result = streamText({
  model: openai("gpt-4o"),
  messages,
});
return result.toDataStreamResponse();
useChat Hook
const { messages, input, handleSubmit }
  = useChat({ api: "/api/chat" });
初始化 WebLLM
const engine = await CreateMLCEngine(
  "Llama-3.2-1B-Instruct-q4f16_1"
);
流式推理 (本地)
const chunks = await engine.chat
  .completions.create({
    messages, stream: true
  });
for await (const c of chunks) { ... }
检测 WebGPU 支持
if (!navigator.gpu) {
  console.log("WebGPU 不支持");
  // fallback to API
}
模型加载进度
await CreateMLCEngine(id, {
  initProgressCallback: (p) => {
    console.log(`${p.progress * 100}%`);
  }
});
useCompletion Hook
const { completion, complete }
  = useCompletion({
    api: "/api/completion"
  });
await complete("写一个冒泡排序");
下一步行动

浏览器是下一个 AI 平台

WebGPU 标准刚满两年,WebLLM 生态正在爆发式增长。 2025 年,你的前端应用不再只是"调 API 的壳", 而是一台拥有本地 AI 能力的智能终端