直接放结论：DeepSeek-R1 是能跑进浏览器的，而且不是玩具级演示。我用 WebGPU 后端 + Transformers.js 把量化后的 R1 蒸馏模型装进了 Chrome，完全端侧推理，数据不出本地，生成速度在我的 M 系列芯片上能到每秒 30~60 tokens。这篇文章把这个实战过程完整拆开讲：为什么选 WebGPU 而不是 WASM、Transformers.js 在中间到底做了什么、怎么把 R1 的推理链在浏览器里调出来、模型文件从哪来、量化参数怎么选、显存爆了怎么排查。如果你也想在浏览器里跑大模型，或者你正在纠结“端侧推理到底能不能用”，这篇应该能给你一个比较完整的答案。
1. 为什么非要在浏览器里跑 R1
先说清楚最核心的问题：大家都在用官方 API 或者本地 Python 环境跑 DeepSeek，为什么还有人要折腾浏览器端侧推理？这不是炫技，背后有几类非常现实的需求。
第一是隐私。有些数据你压根不想离开本机。比如你在做一个内部文档问答工具，把公司合同、财务数据传给云端 API，心理那一关就过不去。浏览器端侧推理能让整个流程“数据不出设备”，模型权重、输入输出全部留在本机。
第二是成本。云端 API 按 token 计费，如果你要做的是一个高频调用的功能（比如代码补全、文本批处理），长期算下来账单会很难看。端侧推理是一次性把模型下载到本地，之后每次调用只花电费。
第三是离线可用。网络环境不稳定的场景（会议现场、偏远地区、内网环境），或者干脆是纯前端的 SaaS 工具，端侧推理是唯一可行的方案。
第四是延迟。端侧推理省去了网络请求往返，在模型规模相近的情况下，首 token 延迟往往比云端 API 更低。这一点在做交互式应用时体验差距很明显。
那为什么是浏览器而不是 Electron 或者桌面客户端？因为浏览器有天然的跨平台属性，不用安装任何运行时，打开网址就能跑。而且要用 GPU 计算，浏览器已经给出了标准答案——WebGPU。
我在这个项目里的具体目标很明确：把 DeepSeek-R1 的蒸馏版（1.5B 量化版）跑进浏览器，让它在本地生成包含“推理链”（也就是 reasoning / thinking 部分）的完整回答，并在这个过程中把 WebGPU 的适配、Transformers.js 的加载、显存管理、流式输出这些坑全部趟平。
先强调一点：这里的 DeepSeek-R1 不是 671B 的满血版，用的是蒸馏后的小模型。DeepSeek 官方开源了基于 Llama 和 Qwen 的蒸馏系列，参数量从 1.5B 到 70B 不等。其中 1.5B 蒸馏版在普通笔记本的浏览器里是可以实际跑起来的，这也是全流程能落地的关键前提。
2. 核心技术选型与架构拆解
2.1 WebGPU 为什么是破局点
想明白 WebGPU 为什么关键，得先看看没有 WebGPU 的时候我们是怎么跑的。
我在 2023 年就试过用 Transformers.js 的 WASM 后端在浏览器跑小模型，当时跑的是 400M 左右的模型，生成一个 token 需要几百毫秒甚至更久，几乎没法做交互。原因很简单：WASM 跑在 CPU 上，而大模型的推理本质是海量矩阵乘法，CPU 的并行能力跟 GPU 完全不在一个量级。
WebGPU 解决的就是这件事。它是浏览器的新一代 GPU 图形与计算接口，可以理解为 WebGL 的现代替代品，但它不止做图形渲染，还提供了通用计算能力（compute shader）。大模型推理和 3D 高斯泼溅这类 GPU 计算任务需要的并行调度、显存管理、矩阵运算，WebGPU 都原生支持。
这样说可能有点抽象，我用一个生活化类比解释：WASM 后端相当于你一个人手工做几百道算术题，WebGPU 后端相当于你拉来几百个人排队同时开算，每个人都只算自己那一小块，最后把结果汇总。模型参数量越大，这个并行优势就越夸张。
浏览器端推理的整条技术栈也因为它发生了质变。过去我们需要把模型转换成 C 语言或者汇编级别的优化才能勉强运行，现在 WebGPU 允许我们用接近现代图形 API 的方式直接调度 GPU，把矩阵乘法这类算子直接映射到计算管线里执行。
2.2 Transformers.js 在其中扮演的角色
Transformers.js 是 Hugging Face 的 Transformers 库的 JavaScript 移植版。它的价值在于把“加载模型—预处理—推理—后处理”这整条链路包装成一套友好的 API，让 JavaScript 开发者不用关心 ONNX 模型的底层算子细节。
我在这个项目中用到的 v3 版本，专门引入了一个关键能力：WebGPU 执行后端。它的底层是基于 ONNX Runtime Web（ORT Web）的，模型需要先转成 ONNX 格式，然后在浏览器里通过 WebGPU EP（Execution Provider）来加载和推理。
具体工作流是这样的：
- 模型权重（PyTorch 格式）先用转换脚本转成 ONNX 格式。
- 对 ONNX 模型做量化，把权重从 FP32/FP16 压到 INT4/INT8。
- 浏览器加载 ONNX 模型文件，Transformers.js 自动把计算图交给 WebGPU 后端执行。
- tokenizer、注意力掩码、生成策略这些逻辑都由 Transformers.js 包装好，前端只需要调用
pipeline()或者AutoModelForCausalLM.from_pretrained()这类接口。
这里需要特别提一下 Quantization（量化）的重要性。原始的 1.5B FP16 模型大约是 3GB，浏览器里加载 3GB 权重会非常吃力。量化成 4bit 之后，模型体积能压到 1GB 左右，显存占用也随之下降，普通笔记本才能跑得动。
2.3 DeepSeek-R1 蒸馏版的选型逻辑
上一节提到 R1 系列的模型不止一个版本，这里要展开讲一下为什么我最终选了 1.5B 蒸馏版做演示。
DeepSeek-R1 官方有 671B 的满血版，也有基于 Qwen/Llama 蒸馏的小模型，常见的有 1.5B、7B、8B、14B、32B、70B 这些规格。浏览器端侧推理有一条硬约束：模型权重必须在端上设备的显存/内存里装得下。
我自己用的开发机显卡是 8G 显存，浏览器能调用的 GPU 显存还要打折扣（后面会细讲）。1.5B 的 4bit 量化权重大约是 1GB 左右，适合在 8G 显存设备上跑；7B 量化后大约 4.5GB，8G 显存勉强能放，但 KV cache 和中间激活值很容易挤爆算力；14B 以上基本不用考虑，那是 24G 显存级别设备的事。
如果你要部署到手机或者轻量笔记本上，1.5B 是相对稳妥的起点。如果你用的是 32G 统一内存的 M 系列芯片，可以试着挑战 7B 量化版，速度会慢一些，但也能跑。
2.4 浏览器端推理的完整架构
把整个系统的数据流串起来看，它大概是这个结构：
- 浏览器页面：负责 UI 渲染、用户输入、流式输出展示。
- Transformers.js：负责模型加载、tokenizer 编解码、生成循环、采样策略。
- ONNX Runtime Web：负责把 ONNX 模型的计算图编译成可执行算子。
- WebGPU（compute shader）：真正执行矩阵乘法、注意力计算等 GPU 运算。
- 模型文件：量化的 ONNX 权重和 tokenizer 文件，通常放在静态服务器 / CDN 上，通过浏览器缓存机制留存。
这个架构的好处是每一层都可以独立替换。比如不想用 Transformers.js 这种高层封装，可以直接用 ONNX Runtime Web 的底层 API 手写推理循环；不想用 ONNX 格式，也可以直接用 GGUF 格式配合其他推理库。灵活度很高。
3. 实操：从零把 R1 装进浏览器
3.1 环境准备与项目初始化
先列一下我用到的开发环境，方便你对照：
- Chrome 113+（必须，WebGPU 在旧版浏览器上不可用）
- Node.js 18+（用于模型转换和本地静态服务器）
- Python 3.10（用于模型下载和转换）
- Transformers.js v3 及以上
- ONNX Runtime Web 1.18+（一般随 Transformers.js 自动安装）
为了方便测试，前端我直接用 Vite 搭了一个轻量工程，这样本地开发有热更新，构建时也能自动做静态资源处理。
初始化命令很简单：
npm create vite@latest r1-browser-demo -- --template vanilla cd r1-browser-demo npm install @huggingface/transformers装完依赖之后，项目的核心文件大概是index.html、main.js，再加一个存模型逻辑的model.js。
3.2 模型下载与 ONNX 量化转换
这是整个流程中坑最多的一步，值得多花点篇幅。
Hugging Face 上已经有现成的 ONNX 量化版 DeepSeek-R1 蒸馏模型，你不用从零转。但如果你是第一次接触，我建议自己走一遍转换流程，这样后面出了问题你能知道是哪一步引起的。
我用的转换脚本大致如下：
pip install optimum[onnxruntime] torch transformers然后用 Optimum 命令行工具导出 ONNX：
optimum-cli export onnx --model deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B --task text-generation --quantize int4 model_onnx/这里有几个参数说明一下：
--model：指定 Hugging Face 上的模型 ID，也可以是本地路径。--task text-generation：告诉工具这是因果语言模型任务，会生成对应的 ONNX 计算图。--quantize int4：把权重压缩到 4bit。我们这里用的具体方案是 int4 分组量化，理论上能把 FP16 权重压缩到原来的 1/4 左右。
转换完成之后，模型目录里会有model.onnx和tokenizer.json这样的文件。此时模型可能还有多个分片文件，比如model_quantized.onnx、model_quantized.onnx_data，需要一起部署到静态服务器。
这一步常见的坑是 Optimum 版本和 PyTorch 版本不兼容，建议在干净环境里操作，或者直接用官方已转换好的模型。我在实际中用的是 Hugging Face 社区里已经转好的 ONNX 模型目录，省了很多时间。
3.3 前端调用：Transformers.js 加载模型
我先给出一个能跑起来的最小示例，这段代码是核心。
import { AutoModelForCausalLM, AutoTokenizer, TextStreamer } from "@huggingface/transformers"; // 建议把模型放到同域静态目录，避免跨域加载问题 const MODEL_ID = "./models/deepseek-r1-1.5b-onnx-q4"; // 构造一个流式输出器，把每个生成的 token 实时打印到页面 const streamer = new TextStreamer(tokenizer, { skip_prompt: true, skip_special_tokens: true, callback_function: (text) => { // 这里把文本追加到页面容器里 outputDiv.textContent += text; }, }); // 加载模型与 tokenizer const tokenizer = await AutoTokenizer.from_pretrained(MODEL_ID); const model = await AutoModelForCausalLM.from_pretrained(MODEL_ID, { dtype: "q4", device: "webgpu", }); // 构造推理输入 const messages = [ { role: "user", content: promptText }, ]; const inputs = tokenizer.apply_chat_template(messages, { add_generation_prompt: true, return_tensor: true, }); // 执行生成 const output = await model.generate({ ...inputs, max_new_tokens: 2048, do_sample: false, streamer, });这段代码的核心逻辑其实只有三步：初始化 tokenizer 和 model，把用户输入转成 token 张量，然后调用 generate 生成输出。
这里最关键的参数是device: "webgpu"。Transformers.js 会根据这个参数把 ONNX Runtime 的执行后端切换到 WebGPU EP。如果没有这个参数，默认会走 WASM 的 CPU 后端，速度差距非常明显。
另一个需要注意的点是dtype: "q4"。它要和模型文件实际的量化格式保持一致。如果你加载的是一个 q8 量化模型，却传了 q4，Transformers.js 可能直接报错或者输出乱码。
3.4 推理链：让 R1 的“思考过程”也展示出来
DeepSeek-R1 与普通对话模型最大的不同就是它有一个专门的推理链阶段。在训练时，模型会在输出最终答案之前，生成一段“thinking”内容，然后在内容和思考之间插入特殊标记。
对于 Qwen 蒸馏出来的版本，推理链由<｜User｜>和<｜Assistant｜>之间的内容触发，模型会先输出一段以我认为...或者嗯，用户想知道...风格的内部推理，然后输出最终答案。浏览器端要做的事情很简单：不要把特殊 token 过滤掉，并且在生成的时候把整段文本展示出来。
Transformers.js 的 tokenizer 在apply_chat_template时已经帮你处理了聊天模板。你只需要在生成时把skip_special_tokens设为 false（默认就是 false），并且不要手动截断 thinking 内容。
如果你想区分“思考中”和“正式回答”两个阶段，可以在拿到完整输出后，按<｜Assistant｜>这个关键符号切分文本。前半部分是推理链，后半部分是正式回答。实际体验下来，展示推理链的效果非常震撼，用户能看到模型“一步一步想”，对于教育、问答、代码调试这类场景来说，这本身就是产品价值。
3.5 流式输出与交互优化
第一批跑通之后，你会发现等待推理结果的时间比较长，尤其是生成长文本时，可能要几秒到几十秒。如果页面一直白屏，用户体验极差。
解决方案是流式输出。上面代码里已经用了TextStreamer，它会监听到每一个新生成的 token，并实时回调到页面上。这样做的好处是用户能立刻看到反馈，感知到“模型在动”，而不是呆呆地等。
在实际项目中，我还做了两个额外的优化：
一个是给“思考中”和“正式回答”设置不同的样式。思考阶段用灰色斜体，正式回答用正常字体。这样用户一眼就能分清当前处于哪个阶段。
另一个是实现“生成中断”功能。R1 模型有时候思考链会非常长，用户看完思考过程后觉得再生成下去没有意义，可以直接点“停止”按钮。这个功能的实现并不复杂，调用model.generate()的时候把 generation 任务放进一个 AbortController 里，或者直接销毁当前会话重新初始化即可。
3.6 模型文件怎么放：CDN 还是本地静态目录
模型文件放哪直接影响加载速度。浏览器端推理方案中，模型文件通常有两种放置方式：
一种是把模型放在项目的public目录下面，跟随前端静态资源一起部署。这种方式的好处是简单、无跨域问题，适合中小型模型（< 2GB）。坏处是每次更新模型都要重新构建部署前端。
另一种是把模型放在独立的静态资源服务器或 CDN 上。适合模型文件较大的场景，可以单独做压缩、缓存、断点续传。浏览器加载时由于同源策略限制，需要把静态服务器配置好 CORS 头。
我在实际项目中用的是第一种，本地public/models/目录。由于 Transformers.js 支持浏览器缓存，模型第二次加载时大多从缓存中读取，速度会快不少。
4. 关键性能指标与调优实战
4.1 影响推理速度的四个核心因素
摸清瓶颈才能真正调优。我在实测中总结出四个主要因素：
第一个是模型显存占用和 GPU 带宽。模型参数量越大，推理时需要搬运的数据越多，生成速度越慢。1.5B 量化模型在 M 系列芯片上跑出 30~60 tokens/s，7B 量化模型可能只有 8~15 tokens/s。这个数量级的差距不是优化能填平的。
第二个是上下文长度。序列越长，注意力计算的复杂度越高。用满 8K 上下文时，即使模型本身不大，KV cache 也会占用大量显存，且每生成一个 token 都要重新计算整段注意力的开销。
第三个是量化精度。q4 比 q8 快，但也更可能出现输出质量下降。如果发现生成结果有明显的逻辑混乱，可以尝试把量化精度升到 q8 甚至 fp16。
第四个是 WebGPU 后端的算子覆盖情况。ONNX Runtime Web 的 WebGPU EP 在逐步完善，有些算子如果没被 GPU 支持，会自动回退到 CPU 执行，此时性能就会断崖式下降。这类问题通常只能通过更新 ORT Web 版本或者换模型结构规避。
4.2 上下文窗口和 KV Cache 的配置
Transformers.js 的generate()接口提供了一个max_length参数，它控制了模型推理时的最大 token 长度。在端侧推理中，这个参数不是越大越好。
首先要明确一点：max_length包含输入长度。如果用户输入的对话历史很长（比如多轮聊天），max_length设得再大，留给新生成的空间也只有max_length - input_length。
我在项目里把max_new_tokens单独传参，设置为 2048。这表示无论输入多长，只允许模型最多新生成 2048 个 token。如果你只是想快速演示，这个值可以调到 512，生成速度会明显提升。
后端 KV cache 的管理在 Transformers.js 中是自动的，但它受显存制约。当显存不够时，浏览器通常不会像桌面程序一样直接崩溃，而是 WebGPU 设备被系统回收，页面变黑或者提示设备丢失。出现这种情况时，优先降低max_new_tokens和输入长度。
4.3 实测性能数据
我自己在两种设备上做了对比测试，数据仅供参考：
- 设备 A：M2 MacBook Air 24G 统一内存，Chrome 最新版。1.5B q4 量化模型，输入 50 token，输出 200 token，稳定在 35~45 tokens/s。
- 设备 B：Windows 台式机 RTX 3060 12G，Chrome 最新版。同样的模型，速度大概在 20~30 tokens/s 之间，不如 M 系列但完全可用。
这里有个挺有意思的现象：M 系列芯片的统一内存架构让 GPU 和 CPU 共享内存，省去了数据拷贝环节，在跑这种中小模型时反而比独显更有优势。
如果你用的是没有独立 GPU 的轻薄本，WebGPU 大概率会调用核显，生成速度可能降到个位数，但依然可以跑。如果低于 5 tokens/s，建议换更小的模型。
4.4 预加载与模型缓存优化
首次打开页面时，模型文件需要完整下载。1GB 的模型在普通家用宽带上需要几十秒到几分钟不等，这个等待过程很容易让用户流失。
我的做法是做一个模型预加载页。页面进入后先检测浏览器是否支持 WebGPU，然后再判断本地缓存里有没有模型文件。没有的话就展示一个带进度条的加载界面，用 fetch API 手动拉取模型分片文件。如果担心 CORS 的限制，可以用cache: "force-cache"配合浏览器的 HTTP 缓存。
Transformers.js 内部也有自己的缓存机制，它在from_pretrained的时候会把文件缓存到浏览器 Cache Storage 中。第二次加载时无需重新下载，体验会好很多。
但要注意，浏览器缓存的空间并不是无限的。如果模型文件很大，浏览器可能在存储空间不足时自动清除旧缓存。对关键项目，建议做一个“检查模型完整性”的逻辑，意外删除后能快速重新拉取。
5. 常见问题与排查实录
5.1 WebGPU 报错：浏览器不支持或设备丢失
WebGPU 是个比较新的特性，不少用户用的还是稍旧版本的浏览器。navigator.gpu不存在时，页面会直接报错。
我写的探测逻辑是：
if (!navigator.gpu) { alert("当前浏览器不支持 WebGPU，请升级到最新版 Chrome 或 Edge"); return; }设备丢失问题（GPUDeviceLostError）通常会出现在显存被其他应用大量占用的时候。这个问题没有一劳永逸的解法，只能降配重试。
5.2 模型加载很慢甚至卡死
模型文件大是主要原因。如果本地开发时出现这个问题，先确认静态服务器是否开启了 gzip 或 brotli 压缩。虽然 ONNX 权重文件本身已经是量化后的二进制数据，压缩率有限，但 tokenizer 和配置文件的压缩收益很明显。
如果模型分片文件很多，注意浏览器对并发请求的数量限制。可以把分片文件打包成一个单文件，或者用 CDN 优化分发。
5.3 生成过程中出现乱码或重复输出
这个问题我踩过两次，原因都指向 tokenizer 与模型不匹配。在 Transformers.js 中，如果你用 A 模型的 tokenizer 加载 B 模型的权重，必乱码。解决办法是把模型目录里的tokenizer.json、tokenizer_config.json一起下载并与模型版本严格对应。
另一个常见的乱码原因是精度匹配问题。模型实际是 q8 量化，代码里却写dtype: "q4"，解析时字节错位，输出自然就是乱码。遇到这种情况，打开浏览器开发者工具的 Network 面板，看模型文件的响应头或者目录里的配置文件，确认量化格式。
5.4 为什么我已经用了 WebGPU 但速度还是很慢
这个问题的排查思路最重要。先去确认 WebGPU 是否真的被启用了。我见过不少人把device: "webgpu"写进了代码，但因为 Transformers.js 版本太旧，这个参数根本没有生效，实际还是在走 WASM。
判断方式很简单：生成时打开 Chrome 的开发者工具，在 Performance 面板里录制一段，如果看到大量 compute shader 在 GPU 上运行，说明 WebGPU 生效了。如果看到的主要是 JavaScript 调用和 CPU 计算，说明还在走 WASM。
另一种“慢”的原因是生成长度设置过大。把max_new_tokens从 2048 调到 512，速度会有非常直观的提升，但这并不是模型变快了，只是输出总量变少了。
5.5 常见问题速查表
为了方便后续排查，我把遇到过的典型问题整理成一张速查表：
| 现象 | 可能原因 | 解决方案 |
|---|---|---|
| 页面提示不支持 WebGPU | 浏览器版本过低 | 升级 Chrome/Edge 到最新版，开启硬件加速 |
| 模型加载进度条卡住 | 跨域请求被拦截 | 为静态服务器配置 CORS 头，或放到同域下 |
| 生成结果乱码 | tokenizer 与模型不匹配 | 确保 tokenizer 文件与模型权重属于同一个模型版本 |
| 生成结果乱码（量化格式不匹配） | dtype 与实际量化格式不一致 | 检查模型目录的配置文件，调整整个会话的加载参数 |
| 生成速度极慢 | WebGPU 未生效或走了 WASM 回退 | 检查 Transformers.js 版本，确认代码里device参数正确 |
| 浏览器标签页崩溃或变黑 | 显存不足，WebGPU 设备被系统回收 | 降低模型参数量或量化精度，减少max_new_tokens |
| 上下文很长时首 token 延迟高 | 注意力计算开销随序列长度线性/平方增长 | 限制对话历史长度，缩短输入序列 |
| 模型第二次加载依然很慢 | 浏览器缓存未命中或缓存被清空 | 检查 Cache Storage 使用情况，必要时做预加载逻辑 |
5.6 一个值得注意的坑：浏览器与本地 Python 推理的表现差异
把浏览器端推理和 Python 本地推理放在一起对比，性能差异可能超出直觉。浏览器有沙箱、渲染进程和 GPU 进程隔离等机制，WebGPU 的调度效率不一定比得上原生 CUDA。同一个量化模型在桌面的 Python 环境可能跑到 100 tokens/s，浏览器里只有 40，这并不奇怪。
但浏览器的优势在于“分发”和“免安装”。不需要用户装 Python、配置环境、下载 CUDA，一个 URL 就能打开即用。对 To C 产品和内部可视化工具来说，这种分发效率远胜过 0.1 秒的推理延迟优化。
6. 扩展思考：端侧推理与 3D 可视化的结合
浏览器端侧推理的意义不止于“在网页里跑 LLM”。WebGPU 同时还能处理 3D 渲染和高性能计算，这意味着 AI 推理和可视化渲染可以在同一条 GPU 管线上共处。
最近我看到不少有意思的方向，比如 splat.js——一个用纯 JavaScript + WebGPU 实现的 3D 高斯泼溅（3D Gaussian Splatting）处理方案。它可以实时渲染高质量 3D 场景，不需要传统意义上的网格重建，直接在浏览器里加载训练好的高斯点云。
如果把 DeepSeek-R1 这类端侧推理模型和 3D 高斯泼溅结合起来，可以做出很多有想象力的应用：
比如 AI 辅助的空间理解。摄像头采集场景后，先通过高斯泼溅做实时 3D 重建，再让本地模型对重建结果做语义理解，回答“这个房间里有什么”“哪面墙是承重墙”这类问题。整个过程都在浏览器内完成，不需要把场景数据传到云端。
再比如在无人机巡检、工业设备维护的场景中，操作人员在平板上打开网页，看到设备的 3D 模型，同时通过本地大模型对设备状态进行诊断。端侧推理的隐私优势和离线特性在这里非常有价值。
这类项目的技术栈高度一致：WebGPU 负责并行计算，ONNX Runtime 负责加载 AI 模型，Transformers.js 负责文本相关的逻辑，再做一层渲染引擎负责 3D 展示。前端工程师通过这些技术栈，完全可以在浏览器里实现过去需要原生应用才能做到的能力。
当然，端侧推理目前还有不少限制。比如 WebGPU 在移动端的支持还不够整齐，iOS Safari 的部分版本仍然有限；模型的量化精度对复杂推理任务确实有影响，R1 这种深度思考模型在 q4 下偶尔会表现出逻辑跳跃；浏览器内存管理也远不如 Python 后端灵活。
但趋势已经很明显了：浏览器从“展示层”进化成“计算层”，GPU 算力正成为网页应用的常规资源。
最后再分享一点个人体会
把 R1 装进浏览器的过程，让我对“端侧 AI”有了更实际的认识。以前大家聊端侧 AI，讨论的多是理论可能性和参数对比，真到自己动手把一个能用的模型从下载、量化、转换、前端调用到调优跑通，才体会到这里面有多少琐碎但关键的细节。
几个印象比较深的点：一是量化格式不匹配导致的乱码，排查了很久才发现是 dtype 传参问题；二是 WebGPU 在某些 Windows 设备上表现极其不稳定，设备丢失后页面直接黑掉，没有任何报错提示；三是模型加载的等待时间对用户体验的影响比想象中大得多，预加载和缓存策略必须从一开始就设计进去。
如果你也想做类似的事情，我的建议是：先从 1.5B 量化模型起步，跑通完整链路之后再考虑更大规模的模型；在选型时优先看 Transformers.js 官方支持的模型列表，减少转换环节的麻烦；对 GPU 设备丢失这类偶发问题，一开始就要设计好降级方案。
现在浏览器已经不是那个只能展示静态网页的“花瓶”了，它可以承载真正的 AI 推理能力。下一步我打算把同样的技术整合进一个带 3D 高斯泼溅渲染的演示应用里，让本地大模型既“能看懂文字”，也“能看懂空间”。这条路走起来很有意思，也希望这篇文章能给想入坑浏览器端推理的你一点实际的帮助。
