最近在研究浏览器端运行大模型的实现方案，打算搭建DeepSeek-R1轻量化推理演示页面。整个项目采用Vite构建工具，搭配React+TypeScript做页面逻辑，Tailwind CSS全权负责样式，借助WebGPU实现本地模型运算。搭建过程里涉及不少前端基础与AI结合的知识点，我借着这个实战项目，把底层原理和如何实操讲清楚，无论是刚学React的新人，还是想接触前端AI的开发者，或多或少都能有所收获。
一、从零初始化项目，搞懂Vite基础使用逻辑
想要开展开发工作，第一步就是初始化工程，打开终端输入代码：
npm init vite
执行后控制台会弹出选项列表，框架选择React，语言模板选用TypeScript。选定完成后进入项目文件夹，执行 npm install 安装基础依赖，等待依赖安装完毕，运行 npm run dev 就能启动本地开发服务。
这里说下Vite的优势，很多习惯了Webpack的朋友刚上手会明显感受到差异。Webpack会在启动时打包全部文件，项目体量变大后启动速度肉眼可见地变慢；Vite利用浏览器原生ES Module能力，开发环境不会做全量打包，只有访问到的文件才会实时编译，热更新响应速度极快，日常开发能省下不少等待时间。
二、Tailwind CSS安装配置，理清原子化CSS工作原理
原生手写CSS的弊端在复杂页面里会无限放大：重复书写边距、尺寸、排版样式，文件冗余严重，修改样式时还要来回切换css和业务组件文件。Tailwind作为原子化CSS框架，正好解决这类痛点，我们先完成环境部署。
- 安装依赖
在项目根目录运行安装指令，创建项目
npm install tailwindcss @tailwindcss/vite
打开index.css文件，替换为：
@import "tailwindcss";
在找到项目文件下的vite.config.ts文件，替换为：
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'
export default defineConfig({
plugins: [
react(),
tailwindcss(),
],
})
配置完成后，就可以直接在组件标签的className属性里拼接各类样式，不用单独新建样式文件编写选择器规则。
很多初学者会疑惑，HTML标签里用class，到了React JSX中必须替换成className，这里的底层逻辑很关键。class是JavaScript中的保留关键字，专门用来声明类，编译器在解析JSX时，如果直接书写class，会判定为语法报错。React单独设计className属性，专门用来传递样式类名，规避关键字冲突，是JSX的硬性规范。
再说说Tailwind的运行机制，它和传统css完全是两种思路。传统开发需要手动书写选择器与样式键值对，大量重复代码难以维护；Tailwind依靠Vite插件扫描整个项目，收集页面中实际用到的原子类，只把对应的样式注入最终代码，没有使用的类会直接丢弃，不会额外增加打包体积。开发时我们只需要组合语义化类名，像flex控制弹性布局、text-4xl控制字号、mb-1设置外边距，一行代码就能完成布局美化，极大提升开发效率。目前主流的前端UI组件库，比如Vibe UI、ShadCN UI，底层都是基于Tailwind搭建，掌握这套写法之后，对接各类组件库会轻松很多。
三、React函数组件与Hooks，吃透响应式核心逻辑
本项目的页面逻辑全部写在App.tsx中，采用React函数组件搭配TypeScript静态类型约束， useState 、 useEffect 两个基础Hooks贯穿整个页面逻辑，这也是React开发的核心知识点。
useState：实现数据驱动视图
Hooks统一以use作为开头，useState的作用是定义响应式数据，标准语法为 [数据变量，更新函数] = useState(初始值) 。这里有一个高频误区：直接修改变量本身无法更新页面视图，只有调用配套的更新函数，React才会感知数据变化，重新渲染页面，这就是前端常说的数据驱动视图。
结合WebGPU模型加载的业务场景，我定义了多组状态变量：页面运行状态status、错误提示error、加载文案loadingMessage、模型下载进度progressItems。不同状态对应页面不同展示效果，类似川剧变脸，一套页面根据数据切换多种视图，不用重复编写DOM结构。
import { useState, useEffect } from 'react';
function App() {
// 页面运行状态
const [status, setStatus] = useState(null);
// 错误信息状态
const [error, setError] = useState(null);
// 加载提示文字
const [loadingMessage, setLoadingMessage] = useState("");
// 模型下载进度对象
const [progressItems, setProgressItems] = useState([{
file: 'model.onnx',
progress: 0,
total: 34353543453
}]);
// 判断浏览器是否支持WebGPU
const IS_WEBGPU_AVALABLE = !!navigator.gpu;
代码里 !!navigator.gpu 用到了双重取反操作，这里解释下用意：部分老旧浏览器不存在navigator.gpu这个API，取值为undefined，单一取反会得到布尔值true，二次取反之后就能稳定输出标准布尔值true或者false，规避后续TS类型校验报错。
useEffect：处理组件副作用逻辑
前端里副作用指的是和页面渲染无关的操作，比如打印日志、接口请求、定时器、资源初始化，这些逻辑都要放到useEffect内部执行。
函数第二个参数是依赖数组，当数组为空时，内部代码只会在组件初次渲染挂载完成后执行一次，非常适合页面初始化操作。只要组件内任意响应式数据更新，整个App函数都会重新执行，函数顶部的打印语句 console.log('组件函数执行') 会重复触发，我们可以借助这条日志观察组件重新渲染的时机。
useEffect(() => {
console.log('组件已经挂载完成');
}, [])
JSX语法：React描述页面的核心载体
函数组件中return包裹的内容就是JSX语法，它允许我们在JavaScript代码里直接书写类XML结构的标签，编译阶段会自动转化为原生DOM操作，是React最核心的特性之一。
return (
IS_WEBGPU_AVALABLE?(<div className="flex flex-col h-screen mx-auto items-center justify-end text-gray-800 bg-white">
<div className="h-full overflow-auto flex justify-center items-center flex-col relative">
<div className="flex flex-col items-center mb-1 max-w-[400px] text-center">
<h1 className="text-4xl font-bold mb-1">DeepSeek-R1 WebGPU</h1>
<h2 className="font-semibold">
A next generation reasoning model that runs locally in
your browser with WebGPU acceleration.
</h2>
</div>
<div className="flex flex-col items-center px-4">
<p className="max-w-[510px] mb-4">
<br />
You are about to load
<a
href="https://huggingface.co/onnx-community/DeepSeek-R1-Distill-Qwen-1.5B-ONNX"
target="_blank"
rel="noreferrer"
className="font-medium underline"
>
DeepSeek-R1-Distill-Qwen-1.5B
</a>
, a 1.5B parameter reasoning LLM optimized for in-browser
inference. Everything runs entirely in your browser with
<a
href="https://huggingface.co/docs/transformers.js"
target="_blank"
rel="noreferrer"
className="underline"
>
🤗 Transformers.js
</a>{" "}
and ONNX Runtime Web, meaning no data is sent to a server. Once
loaded, it can even be used offline. The source code for the demo
is available on{" "}
</p>
{
error && (
<div className="text-red-500 text-center mb-2">
<p className="mb-1">
Unable to load model due to the following error:
</p>
<p className="text-sm">{error}</p>
</div>
)
}
</div>
</div>
</div>):(
<div>您的浏览器还不支持WebGPU</div>
)
)
我们能在JSX里嵌入三元表达式做分支渲染，根据WebGPU的支持情况展示不同页面；也能通过 {变量} 的形式嵌入JS表达式，比如error有值时展示错误提示模块。页面布局全部依靠Tailwind原子类实现，flex控制弹性布局、h-screen让容器占满屏幕高度、text-red-500设置文字颜色，全程不用单独书写样式表。
最后把组件导出 export default App ，项目入口文件才能导入并渲染这个页面组件，完整的组件链路才算打通。
四、WebGPU端侧模型和云端API的区别
这个项目最大的亮点，是脱离云端接口，直接在浏览器本地运行大模型，这里对比当下主流的两种AI调用方案，方便大家理解应用场景。
目前绝大多数AI对话工具，都是调用厂商远程API。用户输入的对话内容会完整上传到远端服务器进行运算，一方面对话数据存在隐私泄露风险，另一方面高频调用会产生额外费用，断网后完全无法使用。
而本项目依托WebGPU搭配Transformers.js，把DeepSeek-R1蒸馏版15亿参数模型放到浏览器本地运行。首次加载模型文件之后，所有推理运算都调用本机显卡算力执行，对话数据不会外传，离线环境也能正常使用，普通家用电脑无需高端显卡就能流畅运行。
同类型本地部署工具还有Ollama，但Ollama需要在设备上单独安装客户端软件，上手门槛更高；WebGPU方案仅需要现代浏览器，打开网页即可使用，传播和使用门槛更低。放到求职简历里，这个项目区别于常规后台管理系统、静态展示页，覆盖前端工程化、TS类型校验、硬件接口适配、前端AI推理等多个方向，竞争力会高出不少。
| 方案 | 数据隐私 | 网络要求 | 使用门槛 |
|---|---|---|---|
| 云端API | 对话上传服务器 | 全程联网 | 仅需调用接口 |
| WebGPU本地推理 | 数据留存本机 | 首次下载模型后可离线 | 现代浏览器支持WebGPU |
五、技术栈选型思考，理清不同方案适用场景
Vite+React+TypeScript
React在前端AI相关项目里生态最完善，Transformers.js、ONNX Runtime Web这类推理工具都优先适配React；TypeScript增加静态类型检查，能在开发阶段拦截类型错误，企业协作项目都会搭配ESLint统一代码书写规范。Vite优化了开发体验，大幅缩短启动与热更新耗时。
Tailwind CSS
原子化样式框架大幅缩减样式开发工作量，适配绝大多数业务页面，市面上主流UI库基本都基于它开发，学会之后可以快速复用各类组件模板。
WebGPU
属于前端前沿技术，打通了浏览器和设备GPU的通信通道，把原本只能在后端Python环境运行的模型推理移植到前端，是前端开发者切入AI领域很好的突破口。
写在最后
本文只搭建了项目基础页面，完成环境判断与项目介绍模块，后续还可以拓展对话输入框、实时下载进度、推理参数调节等功能。整套技术栈通用性很强，不管是学习练手，还是开发前端AI工具都可以复用。
前端行业现在和AI的结合越来越紧密，单纯掌握页面搭建已经不足以拉开差距，像WebGPU本地推理这类跨界知识点，值得大家多花时间摸索，既能夯实前端基础，也能拓宽自己的技术边界。
