端侧 AI 应用这两年从小众玩具变成了正经的工程方向。我最初动这个念头是因为手上有一台没有独显的轻薄本跑不动本地大模型但又不想把每一段对话都发到远端服务器上。后来发现浏览器里的 WebGPU 已经能直接调用 GPU 做并行计算配合量化后的小参数模型完全可以在本地跑起来一个能用的推理服务。这个项目就是把这套想法落地用 DeepSeek-R1 的蒸馏小模型做推理核心WebGPU 做算力后端React TypeScript Tailwind 搭界面整个链路全部跑在浏览器里不依赖任何后端服务。它适合想入门端侧 AI 的前端工程师、想给自己的工具站加本地推理能力的独立开发者以及单纯想搞清楚 WebGPU 到底能干什么的技术爱好者。读完你能拿到一套可复现的搭建流程、几个关键参数的取舍逻辑还有我在调试过程中踩过的坑。1. 项目整体设计与技术选型思路1.1 为什么是端侧推理而不是调 API先说清楚这个项目要解决的核心问题。传统做法是把用户输入发到服务端服务端跑模型再把结果流式返回。这套方案成熟、稳定但有几个绕不开的约束一是网络延迟二是数据要离开用户设备三是服务端 GPU 成本会随着调用量线性上涨。端侧推理把这三件事一次性解决——模型下载到本地后推理全程在浏览器内完成输入数据不出设备服务端只需要托管静态资源。代价也很明显。浏览器能拿到的显存有限模型必须做量化压缩参数量通常控制在 1B 到 3B 之间。DeepSeek-R1 的蒸馏版本正好落在这个区间它的推理能力在同尺寸模型里属于第一梯队尤其是数学和逻辑推理任务这也是我选它而不是选通用对话模型的原因。你要做的是通用闲聊选别的更小的模型也行你要做的是需要多步推理的任务R1 蒸馏版是当前性价比很高的选择。1.2 WebGPU 相比 WebGL 和 WASM 的优势在哪推理后端的选择直接决定了性能上限。我对比过三条路线方案算力来源适合场景主要短板WebAssembly (CPU)CPU 多线程极小模型、兼容性优先矩阵运算慢大模型基本跑不动WebGLGPU 片元着色器早期方案兼容性好不支持通用计算算子实现受限WebGPUGPU 计算管线现代浏览器通用并行计算浏览器支持仍在铺开WebGPU 的关键价值在于它提供了 compute shader也就是通用计算着色器。矩阵乘法、归一化、激活函数这些推理里的核心算子都能写成 compute shader 直接在 GPU 上并行执行。WebGL 时代要靠片元着色器曲线救国很多算子实现起来别扭且低效。WASM 走 CPU 路线小模型还能撑参数量一上去就崩。所以只要目标用户的浏览器支持 WebGPU这条路是当前最优解。提示WebGPU 在主流桌面浏览器的较新版本里已经默认开启移动端支持参差不齐。上线前一定要做能力检测不支持时给出降级提示而不是直接白屏。1.3 React TS Tailwind 这套前端组合的取舍前端部分我没有太多纠结。React 的生态成熟状态管理、流式渲染、组件复用都有现成方案TypeScript 在对接推理引擎这种接口复杂、数据结构多的场景里几乎是刚需模型输出的 token 流、张量形状、配置对象没有类型约束很容易写出一堆运行时才暴露的 bugTailwind 负责把界面快速搭起来省掉写 CSS 文件的时间。这里有个容易被忽略的点推理引擎和 UI 之间要做线程隔离。模型加载和推理都是重计算任务如果直接跑在主线程界面会卡死。我的做法是把整个推理逻辑放进 Web Worker主线程只负责收发消息和渲染。TypeScript 在这里帮了大忙Worker 的消息协议可以用联合类型定义清楚主线程和 Worker 两边共享同一套类型定义改一处两边都跟着变。1.4 整体架构分层把上面的决策串起来整个项目分成四层模型层DeepSeek-R1 蒸馏模型的量化权重通常是 ONNX 或 GGUF 格式托管在静态资源服务器上。推理层WebGPU 计算管线 算子实现负责加载权重、执行前向传播、输出 token。通信层Web Worker 消息通道主线程和推理线程之间传递输入文本和输出 token 流。界面层React 组件 Tailwind 样式负责输入框、对话历史、流式输出渲染。分层的好处是每一层可以独立替换。比如你后面想把推理后端从 WebGPU 换成 WASM只需要改推理层界面层完全不用动。这种可替换性在端侧项目里特别重要因为硬件和浏览器环境太碎片化了。2. 核心细节解析与实操要点2.1 模型量化格式的选择逻辑模型下载下来是浮点权重直接塞进浏览器不现实。一个 1.5B 参数的模型FP16 精度下大约 3GBFP32 直接翻倍。量化就是把这部分精度降下来常见的有 INT8、INT4 两档。我的实测数据1.5B 模型 INT8 量化后约 1.5GBINT4 约 800MB。INT4 的体积优势明显但推理质量会下降尤其是长链推理任务量化误差会累积。折中方案是用 INT8 做主权重对注意力层的关键矩阵保留更高精度。这个取舍没有标准答案取决于你的任务对精度有多敏感。注意量化不是无损的。做数学推理这类对数值敏感的任务时建议先用 INT8 跑通确认质量可接受再考虑压到 INT4。别一上来就追最小体积。2.2 WebGPU 计算管线的搭建要点WebGPU 的编程模型和传统 GPU 编程类似创建设备、写 shader、建管线、传数据、派发计算。核心步骤我拆成五步请求适配器和设备navigator.gpu.requestAdapter()拿到适配器再requestDevice()拿到逻辑设备。这一步要处理失败情况用户设备可能不支持。编写 compute shader用 WGSL 语言写矩阵乘法、LayerNorm、Softmax 等算子。WGSL 语法接近 Rust写起来比 GLSL 清晰。创建计算管线把 shader 编译成管线对象指定工作组大小。准备缓冲区权重和输入数据通过GPUBuffer传到 GPU注意用mappedAtCreation或 staging buffer 做上传。派发计算并读回结果dispatchWorkgroups触发计算结果通过mapAsync读回 CPU。工作组大小的选择直接影响性能。太小 GPU 利用率不足太大可能超出硬件限制。我的经验是从 64 或 128 起步根据实测调整。矩阵乘法里每个工作组负责输出矩阵的一个 tiletile 大小要和共享内存容量匹配。2.3 Worker 通信协议的设计主线程和 Worker 之间的消息协议我用 TypeScript 的判别联合类型定义type WorkerMessage | { type: load; modelUrl: string } | { type: generate; prompt: string; maxTokens: number } | { type: abort }; type WorkerResponse | { type: progress; loaded: number; total: number } | { type: token; value: string } | { type: done } | { type: error; message: string };这样两边 switch 的时候 TypeScript 能自动收窄类型漏处理某个分支编译器会报错。流式输出靠token消息逐条推送主线程收到就追加到对话历史里用户看到的就是逐字输出的效果。2.4 流式渲染的性能陷阱React 里做流式输出有个经典问题每来一个 token 就 setState高频更新会把渲染压垮。我一开始就是这么写的输出长文本时明显掉帧。解决办法有两个。一是用useRef累积 token配合requestAnimationFrame批量刷新把每秒几十次的更新压到每秒 60 次以内。二是把已经输出完的历史消息和正在输出的当前消息分开渲染历史消息用memo包起来避免重复渲染。这两个手段叠加后长文本输出的流畅度提升非常明显。3. 实操过程与核心环节实现3.1 环境准备与依赖安装项目初始化用 Vite它对 Web Worker 和 WebGPU 的支持都比较顺。命令如下npm create vitelatest edge-ai-demo -- --template react-ts cd edge-ai-demo npm install npm install -D tailwindcss postcss autoprefixer npx tailwindcss init -pTailwind 的配置里把content指向./src/**/*.{ts,tsx}然后在入口 CSS 里引入三个指令。这一步没什么坑按官方文档走就行。WebGPU 的类型定义需要单独装npm install -D webgpu/types然后在tsconfig.json的compilerOptions.types里加上webgpu/types否则navigator.gpu会报类型错误。3.2 模型加载与权重上传模型文件我放在public/models目录下通过 fetch 拉取。加载流程分三步先读模型配置层数、隐藏维度、头数再按层读权重最后把权重上传到 GPU 缓冲区。权重上传是耗时大头。1.5B 模型 INT8 量化后约 1.5GB即使走本地缓存首次加载也要几十秒。我的做法是分片加载每加载完一层就通过progress消息回报进度界面上显示进度条。用户看到进度在动等待体验会好很多。async function loadWeights(url: string, device: GPUDevice) { const response await fetch(url); const reader response.body!.getReader(); const chunks: Uint8Array[] []; let loaded 0; const total Number(response.headers.get(content-length) || 0); while (true) { const { done, value } await reader.read(); if (done) break; chunks.push(value); loaded value.length; self.postMessage({ type: progress, loaded, total }); } // 合并后上传到 GPU return concatChunks(chunks); }提示大文件加载一定要用流式读取别用response.arrayBuffer()一次性读。后者会把整个文件塞进内存移动端很容易触发内存上限。3.3 矩阵乘法的 compute shader 实现推理里最耗时的算子是矩阵乘法它的实现质量直接决定整体速度。我用的是分块tiling策略把输出矩阵切成若干 tile每个工作组算一个 tiletile 内的数据先加载到共享内存减少全局内存访问。WGSL 里共享内存用varworkgroup声明。工作组大小设成 16x16每个线程负责输出 tile 里的一个元素。内层循环沿着 K 维度累加每次从共享内存读数据。这个结构是 GPU 矩阵乘法的经典写法实测比朴素实现快好几倍。关键参数是 tile 大小。16x16 是通用起点如果你的 GPU 共享内存大可以试 32x32但要注意工作组线程数上限。我在这台轻薄本上测下来16x16 的配置最稳再大反而因为寄存器压力掉性能。3.4 采样与生成循环模型输出的是 logits要转成 token 需要采样。我实现了温度采样和 top-k 两种策略。温度控制随机性温度越低输出越确定top-k 限制候选范围避免采到概率极低的怪词。生成循环的逻辑是输入 prompt 的 token 序列前向传播得到最后一个位置的 logits采样出一个新 token把它追加到序列末尾再跑下一轮。这个过程是自回归的每生成一个 token 就要完整跑一次前向传播所以生成速度取决于单次前向的耗时。为了控制生成长度我设了maxTokens上限默认 512。同时支持中断用户点停止按钮时通过abort消息通知 Worker 跳出循环。3.5 界面层的流式渲染实现界面部分用 React 函数组件核心是一个对话列表加一个输入框。流式渲染的关键代码const bufferRef useRef(); const rafRef useRefnumber(); function onToken(value: string) { bufferRef.current value; if (!rafRef.current) { rafRef.current requestAnimationFrame(() { setDisplayText(bufferRef.current); rafRef.current undefined; }); } }这样无论 token 来得多快实际 setState 的频率都被压到每帧一次。实测在输出 500 字的长回复时帧率能稳定在 55 以上不卡顿。4. 常见问题与排查技巧实录4.1 WebGPU 初始化失败的排查路径这是新手最容易卡住的地方。requestAdapter()返回 null 的情况有好几种排查顺序建议这样现象可能原因排查方法adapter 为 null浏览器不支持检查navigator.gpu是否存在adapter 为 null硬件被禁用检查浏览器 GPU 加速设置device 请求失败驱动问题更新显卡驱动后重试计算无输出shader 编译错误监听createShaderModule的编译信息我遇到过一次 adapter 拿不到折腾半天发现是浏览器设置里关掉了硬件加速。这种问题不看日志根本想不到所以一定要把错误信息完整打出来。4.2 显存不足的表现与应对显存不足通常表现为计算中途报错或者浏览器标签页直接崩溃。1.5B 模型 INT8 量化后占 1.5GB 左右加上中间激活值和 KV cache峰值可能到 2GB 以上。低端设备很容易触顶。应对手段有三个一是换更小的模型0.5B 到 1B 的版本对显存友好很多二是缩短上下文长度KV cache 的大小和序列长度成正比三是及时释放不再使用的缓冲区WebGPU 的 buffer 用完要destroy()不然会一直占着显存。4.3 输出乱码或重复的成因模型输出乱码或陷入重复循环多半是采样参数的问题。温度设得太高会乱设得太低又容易重复。我的经验值是温度 0.7 左右top-k 设 40这个组合在推理任务上比较平衡。另一个原因是量化误差。INT4 量化在长链推理上容易出现逻辑断裂换成 INT8 通常能缓解。如果换了精度还是乱检查一下 tokenizer 的实现分词和反分词不对齐也会导致输出异常。4.4 性能优化的几个实操技巧推理速度是端侧项目的生命线。我总结了几条实测有效的优化算子融合把 LayerNorm 和残差连接合并到一个 shader 里减少 kernel 启动次数和内存往返。KV cache 复用自回归生成时前面 token 的 key/value 不用重算缓存起来直接复用长文本生成能快一倍以上。权重预转置矩阵乘法里权重矩阵的转置在加载时就做好别在每次前向传播时现算。工作组大小调优不同 GPU 的最优工作组大小不一样做成可配置项上线前在目标设备上实测。提示优化要有优先级。先用性能分析工具定位瓶颈算子再针对性优化。盲目优化非热点代码投入产出比很低。4.5 浏览器兼容性处理WebGPU 的支持情况在变化上线前必须做能力检测。我的做法是在应用启动时检查navigator.gpu不支持就显示提示引导用户升级浏览器或使用其他设备。同时准备一个 WASM 降级路径虽然慢但至少能用。检测代码很简单if (!navigator.gpu) { showFallbackMessage(当前浏览器不支持 WebGPU请升级到最新版本); }别小看这一步我见过太多项目在开发者自己的机器上跑得好好的一到用户那里就白屏就是因为没做能力检测。5. 项目扩展与后续方向5.1 多模态能力的接入思路纯文本推理跑通后往多模态扩展是自然的下一步。思路是加一个视觉编码器把图像编码成 embedding再和文本 token 拼在一起送进模型。WebGPU 同样能加速视觉编码器的卷积和注意力计算。不过多模态模型的体积会大不少端侧部署要更谨慎地做量化。5.2 本地知识库的检索增强端侧推理的一个短板是模型知识截止到训练时间。要让它回答私有领域的问题可以接一个本地检索模块把文档切块、向量化存到 IndexedDB 里推理前先检索相关片段拼进 prompt。整个链路都在本地数据不出设备这是端侧方案相对云端方案的独特优势。5.3 模型热更新的工程化模型文件动辄上 G每次更新都让用户重新下载不现实。工程上要做增量更新把模型按层或按分片切分每片单独做哈希更新时只下载变化的片。配合 Service Worker 做缓存用户第二次打开时直接从缓存加载体验会好很多。我在实际项目里发现端侧 AI 最难的不是把模型跑起来而是把加载时间、显存占用、输出质量这三者平衡好。每一个参数的调整都会牵动另外两个没有一劳永逸的配置。我的建议是先跑通最小可用版本再根据目标设备的实测数据逐步调优别一开始就追求完美参数。另外把推理逻辑和界面逻辑彻底解耦后面换模型、换后端的时候会省下大量重构时间。