第一篇：项目概览 --- 在浏览器里跑大模型，端侧 AI 的革命来了
阅读完本文你将能回答：这个项目是做什么的？用了哪些技术？为什么要在浏览器里跑 AI？WebGPU 是什么？
一、引言
简单来说，这个项目的核心目标是：在浏览器里本地运行一个 15 亿参数的推理大模型，所有的计算都在你的电脑上完成，数据不会离开你的机器。
你可能会问：大模型不都是跑在云端服务器上的吗？ChatGPT、DeepSeek 官网不都是发 HTTP 请求吗？为什么要把模型搬到浏览器里？
这就引出了我们第一个话题 ------ 端侧模型（On-Device AI） 。
二、为什么要做端侧 AI？
2.1 云端推理的三大痛点
| 痛点 | 说明 |
|---|---|
| 贵 | 每次 API 调用都要花钱，token 计费模式对于高频使用场景成本很高 |
| 不安全 | 你的 prompt 和上下文（context）会随着请求发送到远程服务器，敏感数据有泄露风险 |
| 延迟高 | 网络往返 + 服务端排队 + 推理耗时，用户体验不够丝滑 |
2.2 端侧模型的优势
端侧模型（On-Device Model）是指模型文件就在用户设备上，推理计算也发生在本地：
- 零网络延迟：没有 HTTP 请求，GPU 直接计算
- 数据隐私：你的对话内容永远不会离开你的设备
- 离线可用：模型下载一次，之后不需要网络
- 零成本：不需要付费 API，算力来自你的 GPU
端侧模型的典型场景：
- 📱 手机端：iOS 的 CoreML、Android 的 MediaPipe
- 🚗 汽车端：车载语音助手离线运行
- 🖥️ 浏览器端：通过 WebGPU 调用本地 GPU，就是我们这个项目做的事
- 🤖 Agent 场景：本地小模型做意图识别，云端大模型做复杂推理，协同工作
三、技术栈全景图
让我用一张图来展示项目的技术架构：
scss
┌─────────────────────────────────────────────────────────┐
│ 浏览器 (Browser)
│ ┌───────────────────────────────────────────────────┐
│ │ React 19 + TypeScript
│ │ ┌─────────────┐ ┌──────────────┐
│ │ │ App.tsx │ │ Progress.tsx │
│ │ │ (主组件) │ │ (进度条组件) │
│ │ └──────┬───────┘ └──────────────┘
│ │ │
│ │ ┌──────▼──────────────────────────────────────┐
│ │ │ 🤗 Transformers.js
│ │ │ (HuggingFace 官方的 JS 推理库)
│ │ └──────┬──────────────────────────────────────┘
│ │ │
│ │ ┌──────▼──────────────────────────────────────┐
│ │ │ ONNX Runtime Web
│ │ │ (开放神经网络交换格式的浏览器运行时)
│ │ └──────┬──────────────────────────────────────┘
│ └─────────┼──────────────────────────────────────────┘
│ │
│ ┌─────────▼──────────────────────────────────────┐
│ │ WebGPU API
│ │ (直接调用本地 GPU 进行并行计算)
│ └──────────────────────┬─────────────────────────┘
└─────────────────────────┼──────────────────────────────┘
│
┌─────────────────────────▼──────────────────────────────┐
│ 本地 GPU (NVIDIA / AMD / Intel)
│ 运行 DeepSeek-R1-Distill-Qwen-1.5B (ONNX 格式)
└────────────────────────────────────────────────────────┘核心技术栈一览
| 层级 | 技术 | 作用 |
|---|---|---|
| 前端框架 | React 19 + TypeScript | 构建 UI 界面，类型安全 |
| 构建工具 | Vite 8 | 极速开发服务器与生产构建 |
| 样式方案 | TailwindCSS 4 | 原子化 CSS，几乎不用写 CSS 文件 |
| AI 推理库 | Transformers.js | HuggingFace 官方 JS 库，加载和运行模型 |
| 模型运行时 | ONNX Runtime Web | 高效的跨平台神经网络推理引擎 |
| 硬件加速 | WebGPU | 新一代浏览器 GPU API，取代 WebGL |
| 模型 | DeepSeek-R1-Distill-Qwen-1.5B | 15 亿参数的蒸馏推理模型 |
四、WebGPU --- 浏览器里的 GPU 编程
4.1 从 WebGL 到 WebGPU
如果你写过 Three.js 或者了解过浏览器图形编程，你可能知道 WebGL。它是 2011 年发布的，基于 OpenGL ES 2.0，已经用了十几年了。
WebGPU 是下一代标准，2023 年在 Chrome 113 中正式发布。它和 WebGL 的关系，就像 Vulkan/DirectX 12/Metal 和 OpenGL 的关系 ------ 是革命性的升级。
| 对比维度 | WebGL | WebGPU |
|---|---|---|
| 底层 API | OpenGL ES 2.0 (2011) | Vulkan / Metal / DirectX 12 |
| 计算管线 | 不支持通用计算 | 原生支持 Compute Shader |
| 多线程 | 单线程为主 | 原生多线程支持 |
| 性能 | 受限于旧架构 | 接近原生 GPU 性能 |
| AI 推理 | 几乎不可行 | 非常适合 |
关键区别：WebGL 是为"画三角形"设计的，而 WebGPU 从一开始就为**通用 GPU 计算（GPGPU）**设计了 Compute Shader 管线。这意味着 WebGPU 可以让 GPU 做矩阵乘法 ------ 而这恰恰是 AI 推理的核心运算。
4.2 WebGPU 和 AI 推理的关系
大模型的推理过程，本质上是大量矩阵乘法和张量运算。GPU 有成千上万个计算核心，天然适合做这种"简单但大量"的并行计算。
一个 token 的推理 ≈ 数十亿次乘加运算 → GPU 并行执行 → 毫秒级完成WebGPU 让浏览器可以直接调度本机的 GPU 来完成这些运算，这就是"在浏览器里跑大模型"的硬件基础。
4.3 检测浏览器是否支持
项目中有一行非常巧妙的代码：
ini
const IS_WEBGPU_AVAILABLE = !!navigator.gpu;这个 !! 双感叹号的技巧值得说一下：
navigator.gpu→ 浏览器支持 WebGPU 时返回 GPU 对象，不支持时返回undefined- 第一个
!→ 将值转为布尔值并取反（undefined→true） - 第二个
!→ 再取反一次，得到正确的布尔值（true→false）
这就是 JavaScript 中经典的"双重否定等于肯定"。
五、模型 --- DeepSeek-R1 蒸馏版
5.1 什么是蒸馏（Distillation）？
"蒸馏"是模型压缩的一种技术。想象一下：
- 老师模型：DeepSeek-R1 完整版，参数规模巨大（671B），推理能力极强，但普通电脑根本跑不动
- 学生模型：Qwen-1.5B，只有 15 亿参数，体积小，普通电脑能跑
- 蒸馏过程：用老师模型的输出和中间表示来训练学生模型，让学生模型"学到"老师模型的推理能力
就像把一大锅汤（老师模型的知识）蒸馏浓缩成一小瓶精华（学生模型），体积大幅减小但保留了核心能力。
5.2 为什么选 Qwen 1.5B？
| 考量 | 说明 |
|---|---|
| 参数量 | 1.5B 参数 ≈ 3-4GB 模型文件，浏览器可以承受 |
| 推理能力 | 经过 DeepSeek-R1 蒸馏，保留了强大的推理链（Chain of Thought）能力 |
| ONNX 格式 | ONNX 社区提供了优化好的 ONNX 版本，可以直接用 ONNX Runtime Web 加载 |
| 开源协议 | 完全开源，可以自由使用 |
5.3 HuggingFace --- 全球最大的开源模型社区
模型托管在 HuggingFace 上：onnx-community/DeepSeek-R1-Distill-Qwen-1.5B-ONNX
HuggingFace 你可以把它理解为 AI 界的 GitHub：
- 托管开源模型（模型文件就是"代码"）
- 提供模型下载、版本管理
- 提供 Transformers.js 这样的工具库让开发者方便地使用模型
六、Transformers.js 和 ONNX Runtime Web
6.1 Transformers.js
Transformers.js 是 HuggingFace 官方推出的 JavaScript 推理库。它的设计目标很明确：
让你在浏览器里使用 HuggingFace 上的模型，就像在 Python 里用
pipeline()一样简单。
它屏蔽了模型加载、分词器（Tokenizer）、推理管线的复杂性，提供统一的 API。
6.2 ONNX Runtime Web
ONNX（Open Neural Network Exchange，开放神经网络交换格式）是一个跨框架的模型格式标准。
它的设计哲学是：
你用 PyTorch 或 TensorFlow 训练模型 → 导出为 ONNX 格式 → 在任何支持 ONNX 的运行时上推理
ONNX Runtime Web 就是浏览器端的推理引擎，它底层可以调用 WebGPU 来加速计算。
6.3 两者的配合
arduino
┌─────────────────────┐
│ Transformers.js │ ← 高层封装：加载模型、分词、构建 pipeline
│ "给我一个模型名" │
└────────┬────────────┘
│ 调用
┌────────▼────────────┐
│ ONNX Runtime Web │ ← 底层引擎：加载 ONNX 文件、调度 GPU 计算
│ "用 WebGPU 跑它" │
└────────┬────────────┘
│ 调度
┌────────▼────────────┐
│ WebGPU / GPU │ ← 硬件：真正执行矩阵运算
└─────────────────────┘七、项目体验流程
用户打开网页后，经历了这样几个步骤：
arduino
1. 打开页面
→ 浏览器检测 WebGPU 支持（navigator.gpu）
→ 不支持：显示"您的浏览器还不支持 WebGPU"
→ 支持：显示 "Load Model" 按钮
2. 点击 "Load Model"
→ 状态变为 "loading"
→ Transformers.js 从 HuggingFace 下载模型文件（约 3-4GB）
→ 进度条实时显示每个文件的下载进度
→ 显示当前正在下载的文件名和大小
3. 加载完成
→ 状态变为 "ready"
→ 聊天输入框激活
→ 用户输入问题，模型本地推理，返回结果
4. 整个过程：
✅ 零服务器请求（除了下载模型文件）
✅ 数据完全本地
✅ 加载后可离线使用八、本篇小结
这篇文章我们建立了项目的全局认知：
- 端侧 AI 是趋势，解决了云端的成本、隐私、延迟三大痛点
- WebGPU 是浏览器里跑 AI 的硬件基础，它提供了通用 GPU 计算能力
- DeepSeek-R1-Distill-Qwen-1.5B 是蒸馏后的轻量推理模型，适合浏览器运行
- Transformers.js + ONNX Runtime Web 是浏览器端 AI 推理的软件基础
- 整个项目实现了从模型下载到本地推理的完整闭环
下一篇我们将深入工程化层面，详解 Vite + React + TypeScript + TailwindCSS 的项目搭建过程，每一个配置文件我都会掰开揉碎了讲。
下一篇预告 ：第二篇：工程化搭建 --- Vite + React + TypeScript + TailwindCSS 全解析