张辰LMY这两年“AI 前端化”已经从一个概念词变成了实实在在能跑的东西。以前我们做个 AI 功能，基本就是前端接一个云端接口，把用户输入发给服务器，等结果回来再渲染；现在不一样了，只要浏览器环境够新，你完全可以在用户本机的 GPU 上加载一个几十亿参数的本地模型，推理过程不碰服务器、不传敏感数据、断网也能用。这条路现在有一个比较正式的说法，叫 Edge AI，而打通它的关键，就是本地模型加 WebGPU 推理。
这篇文章我就围绕“AI × 前端的下一站”这条主线来聊。我会从整体思路、模型部署、WebGPU 原理、实际代码、工程化落地和踩坑记录几个角度，把整套链路从零讲清楚。内容会比较偏实操，适合正在做 AI 应用的前端工程师、准备把模型能力搬进浏览器的全栈开发者，以及所有对本地推理感兴趣的同学。看完不说能直接写出生产级产品，至少能把技术选型、运行原理和常见报错都摸个门清。
1. 从“调接口”到“调 GPU”：为啥本地模型加 WebGPU 是前端的下一站
1.1 前端 AI 的演进路径
前端做 AI，其实经历了三个阶段。
第一个阶段是“AI 功能外包”，前端只负责把输入收集起来，传到后端接口，后端调大模型 API，返回结果给前端渲染。这种模式至今还是主流，因为实现最快、门槛最低，但问题也非常明显：每次请求都有网络延迟、有 API 成本、有数据出网的安全隐患。
第二个阶段是“端侧小模型打辅助”。比如用 TensorFlow.js 或 ONNX Runtime Web 在浏览器里跑一些轻量模型，做图像分类、姿态检测、OCR 这类任务。此时推理已经下沉到端侧了，但模型普遍很小，根本跑不动大语言模型，也做不了高质量的文本生成。
现在正在进入第三个阶段：本地模型加 WebGPU 推理。WebGPU 提供了浏览器访问 GPU 计算能力的统一接口，配合 quantize 后的 LLM 模型，浏览器里已经能运行 1.5B 到 8B 甚至更大参数的语言模型。这带来的变化是质变的——模型不再是一个远程黑盒，而是变成了浏览器应用里的一个可编程模块。
我自己第一次在浏览器里看到一个 3B 模型流式输出中文回答时，确实挺震撼的。那种感觉跟调 API 完全不同，因为整个推理链路都在本地，你的代码可以从底层控制 GPU 资源、显存分配、上下文窗口，这在前端开发历史上几乎是从未有过的能力。
1.2 本地推理解决的核心痛点
把模型搬到本地，最直接的价值有三个。
第一个是隐私。很多企业场景里，客户数据是不能出内网的。以前你要么接受在公有云 API 上过一遍数据，要么自己维护一套 GPU 服务集群。现在有了本地模型，用户文档、聊天记录、内部知识库都可以在浏览器里处理，数据不落盘、不出网，合规压力小很多。
第二个是成本。大模型 API 按 token 计费，对话一多、文档一长，钱就像流水一样走。本地推理是一次性把模型下载到设备，之后每次推理只消耗电费和硬件资源。对高频、高并发的内部工具来说，这能省下非常可观的费用。
第三个是延迟和可用性。端侧推理省掉了网络 RTT，首 token 响应可以做到几百毫秒甚至更快。而且断网也能用，适合弱网、离线环境，比如施工现场、野外作业、飞机舱内这些场景。
我记得有个做车间巡检系统的朋友提过，他们想在工控平板上做一个语音问答助手，但车间网络很差，云端 API 经常超时。后来换成本地部署一个量化后的模型，GPU 推理配合 WebGPU，哪怕完全没有外网也能正常工作。这种体验是云 API 永远给不了的。
1.3 选型边界：不是所有场景都要端侧跑
不过我得先说一句公道话：本地模型不是万能药，更不是要取代云端 API。它有自己的边界。
如果你要做的是高难度数学推理、复杂代码生成、超长文本理解，当前设备端能跑的模型规模和云端旗舰模型还是有差距的。这时候硬塞进浏览器，效果大概率会让你失望。
我的建议是走混合架构。轻量任务优先本地跑，比如文本摘要、实体抽取、意图识别、客服分类；重度任务再走云端 API，比如复杂推理、大规模检索增强生成。前端代码里做一次统一的模型抽象层，根据场景、设备能力、网络状态自动选择推理后端。这个思路既能吃到本地推理的红利，又不会牺牲最终效果。
还有一个现实问题：WebGPU 的兼容性。Chrome 系浏览器已经默认支持，Safari 18 也跟进了 WebGPU，但老设备、老浏览器、部分移动端 WebView 依然跑不了。所以工程上一定要做降级方案，比如 WebGPU 不可用时切换到 WebAssembly 推理，再不行退回云端 API。这些后面会展开讲。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 本地模型选型与部署：从 Ollama 到浏览器直接加载
2.1 模型参数量、量化格式与内存预算
本地模型能不能跑起来，第一道坎不是代码，而是显存和内存。
模型占用内存有个非常简单的估算公式：模型大小约等于参数量乘以每参数字节数。FP16 精度下每个参数占 2 字节，INT8 量化占 1 字节，INT4 量化占 0.5 字节。
举几个算例：
- 7B 模型 FP16：7 × 2 = 14GB，普通显卡基本跑不动。
- 7B 模型 Q4_K_M 量化：约 4.2GB，中端显卡还有希望。
- 1.5B 模型 Q4 量化：约 0.9GB，再加 KV Cache 和运行时开销，内存占用大概在 1.2GB 到 1.5GB，浏览器环境勉强可接受。
- 0.5B 模型 Q8 量化：约 0.5GB，手机和低端设备都比较舒服。
这里面的 KV Cache 也要重点说明。Transformer 推理时，每个生成出来的 token 都要缓存中间计算结果，多轮对话后 KV Cache 会不断增长。大致估算：对于 1.5B 模型，每生成 512 个 token，KV Cache 大概要占几十到几百 MB，连续对话越多占用越大。所以做浏览器端应用时，上下文长度不能无脑拉满，否则直接吃爆内存。
我比较推荐的浏览器端模型规模是 0.5B 到 3B。3B 以上不是不能跑，但对设备的显存和内存要求高，普通用户机器容易崩，体验很难保证。
2.2 Ollama 本地部署实操
在正式进入浏览器端之前，先讲一下怎么用 Ollama 在本地把模型部署起来。这样做有两个好处：一是开发阶段调试方便，二是线上架构里你也可以把 Ollama 作为网关层服务，统一管理模型。
Ollama 的安装很简单，官网下载安装包，或者用脚本装，装完后命令行里执行：
bash复制ollama pull qwen2.5:1.5b
ollama list
ollama run qwen2.5:1.5b
ollama 拉起一个本地 HTTP 服务，默认监听 11434 端口，接口协议兼容 OpenAI 风格：
bash复制curl http://localhost:11434/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "qwen2.5:1.5b",
"messages": [{"role": "user", "content": "用一句话介绍 WebGPU"}]
}'
前端接 Ollama 也非常容易，只要把 API Base 指向 http://localhost:11434/v1，模型名填成 ollama list 里看到的名称即可。很多 AI 编程工具都支持自定义模型端点，你完全可以把这类工具接到本地模型上，数据不出本机。
这里有一个非常常见的坑：模型名称不匹配的报错。格式通常是 there's an issue with the selected model ... it may not exist or you may not have access to it。出现这个错，99% 是模型名没写对。Ollama 的模型标识是“名称:标签”格式，比如 qwen2.5:1.5b，少写了标签、或者把冒号写成了横杠/下划线、或者本地跟远程模型库里的名字混用，都会触发这个错误。
排查方式很简单，先执行 ollama list 看看本地到底有哪些模型，再把配置里的模型名严格对齐。如果你改了端口或模型路径，也要一并检查 Base URL 是否正确。这个报错本身不是网络问题，更多是配置笔误，所以别急着去排查链路。
2.3 浏览器端直接加载模型
Ollama 适合本地服务和开发调试，但如果你追求极致端侧化，连本地服务都不想开，那就直接在浏览器里加载模型文件。
目前主流方案有两个：一个是 Transformers.js，底层基于 ONNX Runtime Web，支持文本生成、Embedding、图像分类、语音识别等多种任务；另一个是 WebLLM，底层由 MLC LLM 驱动，专门优化了在 WebGPU 上跑 LLM 的效率，支持流式输出和更完整的量化模型体系。
Transformers.js 的模型通常托管在 Hugging Face 的 ONNX 仓库，浏览器首次加载时把模型文件下载到本地，之后通过 IndexedDB 缓存。这个方案的优势是生态丰富，除了文本生成，还能做 Embedding、分类、抽取等任务，适合做 AI 功能全家桶。
WebLLM 的优势是对 LLM 推理做了深度优化，支持多轮对话、流式输出、KV Cache 复用，代码层面更接近 OpenAI SDK 的体验。如果核心需求就是聊天、生成，我会优先推荐 WebLLM。
实际开发中，模型文件通常有几百 MB 到几个 GB，首次加载体验是个大问题。我建议做“模型预下载 + 加载进度提示 + 断点续传”的组合方案。不要让用户等一个白屏，而是展示进度条，告诉他模型正在下载，大概需要多少流量。同时要利用好 IndexedDB 缓存，避免每次刷新都要重新下载。
3. WebGPU 推理原理与实操
3.1 WebGPU、WebGL、WebAssembly 到底什么关系
很多刚接触 WebGPU 的同学，容易把 WebGL、WebAssembly、WebGPU 搞混。我用一句话区分：WebGL 是老的 GPU 渲染接口，WebAssembly 是让浏览器跑高性能 CPU 代码的技术，而 WebGPU 是新一代浏览器访问 GPU 的通用计算接口，不只是画图，还能做通用计算，包括矩阵乘法、卷积、Transformer 推理。
WASM 和 WebGPU 不是二选一的关系。实践中往往是“WASM 负责 CPU 侧的调度和算子，WebGPU 负责 GPU 侧的并行计算”。比如 Transformers.js 内部就是先用 ONNX Runtime 把模型解析成计算图，然后判断哪些算子可以用 WebGPU 加速，哪些回退到 WASM。这种混合执行机制，让模型在不同设备上都能跑。
为什么 WebGPU 对 LLM 推理这么重要？因为 Transformer 的核心计算是矩阵乘法。GPU 天生适合并行做这类运算，一个典型的矩阵乘可以把几千个线程同时拉起来计算，速度是 CPU 的几十倍甚至上百倍。用 WebGPU 的 Compute Shader，你可以在浏览器里直接编写 GPU 并行计算逻辑，这是 WebGL 时代做不到的事。
3.2 初始化 WebGPU 实战
先来一段最简单的 WebGPU 初始化代码：
javascript复制async function initWebGPU() {
if (!navigator.gpu) {
throw new Error("当前浏览器不支持 WebGPU");
}
const adapter = await navigator.gpu.requestAdapter();
if (!adapter) {
throw new Error("无法获取 GPU Adapter");
}
const device = await adapter.requestDevice();
return { adapter, device };
}
这段代码做了三件事：检测浏览器是否支持 WebGPU、请求 GPU 适配器、创建 GPU 设备实例。adapter 代表物理 GPU，device 是你实际执行渲染和计算的逻辑设备。可以理解为 adapter 是显卡本身，device 是显卡上开出来的一个工作通道。
创建完成后，你既可以用来做 Compute 计算，也可以用来做渲染。做 LLM 推理时，计算图会被编译成 WGSL Shader，提交到 Compute Pipeline 上执行，结果写回 GPU Buffer，再通过 mapAsync 读回 CPU 侧，最终转成文本输出。
如果你发现自己写的 Shader 编译不过，大概率是 WGSL 语法问题，常见错误包括类型不匹配、内存越界、绑定组数量超出设备限制。建议先用 device.limits 打印一下当前设备的上限，很多模型跑不起来不是因为逻辑错了，而是触碰了设备限制。
3.3 用 Transformers.js 跑文本生成
Transformers.js 的好处是屏蔽了底层 GPU 细节，你不需要自己写 WGSL，只需要一行 pipeline 就能完成加载和推理。看代码：
javascript复制import { pipeline } from "@huggingface/transformers";
const generator = await pipeline(
"text-generation",
"Xenova/Qwen2.5-1.5B-Instruct"
);
const output = await generator("介绍一下 WebGPU", {
max_new_tokens: 256,
do_sample: true,
temperature: 0.7,
});
console.log(output[0].generated_text);
这段代码会自动下载模型、创建 ONNX Runtime 会话、在可用后端（WebGPU、WASM、WebGL）之间自动选择。do_sample: true 表示使用随机采样，temperature 控制随机性，值越小越确定，越大越发散。
如果你的应用场景是客服、问答这类需要稳定回答的，建议 temperature 设在 0.3 到 0.7 之间，同时可以考虑加 top_p 做核采样，进一步过滤低置信度 token。
需要提醒的是，pipeline 在首次调用时会加载整个模型，耗时较长，最好在应用启动时就预加载，而不是等用户点击后再初始化。另外，Transformers.js 底层用的是 ONNX 格式模型，如果你手里是 GGUF 或者 PyTorch 权重，需要先转换格式，不要直接把 .bin 或者 .safetensors 当 ONNX 用。
3.4 流式输出与并发控制
文本生成最忌讳的是“憋一个大结果再返回”，用户等太久会以为应用卡死了。所以要做流式输出，一个 token 一个 token 地吐出来。WebLLM 的流式接口体验很接近 OpenAI SDK：
javascript复制import { CreateMLCEngine } from "@mlc-ai/web-llm";
const engine = await CreateMLCEngine("Qwen2.5-1.5B-Instruct-q4f16_1-MLC");
const chunks = await engine.chat.completions.create({
messages: [
{ role: "system", content: "你是一个简洁的技术助手。" },
{ role: "user", content: "用一句话解释 Edge AI" }
],
stream: true,
});
let answer = "";
for await (const chunk of chunks) {
const delta = chunk.choices[0]?.delta?.content || "";
answer += delta;
renderAnswer(answer);
}
流式输出的底层机制并不复杂：模型每次生成一个 token，引擎把增量片段 push 到异步迭代器里，前端拿到后更新 UI。这里要注意 UI 更新不能阻塞主线程，建议把渲染逻辑做成节流，比如每 30ms 刷新一次，否则高频 token 刷新会把 DOM 拖垮。
并发方面我有句劝告：一个标签页同时只跑一个生成任务就好。因为 GPU 显存是有限的，同时跑多个模型或多个生成任务，很容易触发显存溢出，表现为页面直接卡死或浏览器崩溃。如果有多个任务排队，建议用一个任务队列把请求串行化。真要并发，也要把模型实例分开，并且控制总显存预算。
4. Edge AI 典型场景与工程化落地
4.1 适合边缘端跑的 AI 场景
本地模型在端侧最有价值的场景，我总结了四个。
一是企业知识库问答。内部文档、制度、项目资料都不方便外传，用本地模型做检索增强的问答，文档直接在本机解析、分块、向量化、问答，完全不用出网。配合页面内嵌的 Embedding 模型，本地就能完成向量检索，体验还挺好。
二是隐私敏感的数据处理。比如医疗报告脱敏、合同关键信息抽取、身份证信息识别。这些数据只要出网就有风险，本地推理是最稳妥的合规方案。
三是离线工具。像旅途中要用的翻译助手、离线会议室纪要、弱网环境下的语音转写，这些场景网络不可靠，本地模型几乎是唯一选择。
四是高频低成本的自动化任务。比如内容分类、标签抽取、垃圾评论识别，这些任务单次调用 API 不贵，但量大到一定程度费用就上来了。本地跑一次性的推理，成本基本为零。
你可能会问，所有这些任务在电脑上跑不就行了，为什么要塞进浏览器？因为浏览器是天然的分发平台。用户不用装 Python、不用配 GPU 驱动、不用理解什么叫模型权重，打开网页就能用。这是 Edge AI 相比传统本地部署最大的优势：零安装、跨平台、自动更新。
4.2 上下文窗口、内存与缓存策略
到了工程落地阶段，最需要操心的就是上下文长度和内存管理。
先说上下文长度。浏览器端模型的 KV Cache 会随上下文增大而增长，对话轮数越多，显存占用越大。我建议在应用层做“滚动窗口”：只保留最近 N 轮对话，更早的对话内容压缩成摘要，然后塞回 prompt。这样既不会丢失太久远的信息，又能控制内存增长。
再说模型缓存。浏览器有 IndexedDB 可以缓存模型文件，但缓存策略要注意。模型文件通常带版本号，升级模型时要清理旧缓存，否则会出现“模型已更新但页面还在用旧版”的问题。我习惯在模型 URL 里加上版本参数，比如 qwen2.5-1.5b-v3.onnx，缓存 key 跟着版本走，升级时就自然失效。
还需要考虑的是多页面共享模型缓存。如果应用里多个页面都要用同一个模型，建议把模型加载逻辑抽成一个公共模块，通过 Service Worker 统一管理。这样既能减少重复下载，又能让模型文件对页面透明。
4.3 降级与混合推理架构
生产环境里，你不能假设每个用户都有新的 Chrome。我做 Edge AI 落地时，一定会设计三层降级链路：
第一层，WebGPU 可用且设备显存足够，直接走 WebGPU 推理，体验最好。
第二层，WebGPU 不可用或设备太老，降级到 WASM 推理，速度慢不少，但功能可用。
第三层，本地模型加载失败或设备内存不足，降级到云端 API，保证核心功能不挂。
降级判断要在应用初始化时完成，通过 navigator.gpu 是否存在、device.limits 是否满足、实际加载失败回调来决定。不能等到用户正式使用再发现问题，那时候体验已经崩了。
混合推理架构我还想强调一点：不同任务可以走不同后端。比如 Embedding 模型小，用 WASM 跑都很快，没必要非得用 WebGPU；大语言模型重量大，才值得走 WebGPU。把任务和模型做精细匹配，整体资源利用率会高很多。
5. 常见问题与排查技巧实录
5.1 模型不存在或模型名报错怎么排查
这类报错前面提过一次，但真的是高频问题，我单独展开。错误信息一般是：
code复制there's an issue with the selected model xxx.
it may not exist or you may not have access to it.
run /model to pick a different model.
这句话前半段容易让人误以为是权限问题，实际上绝大多数情况是模型名拼写问题，尤其是本地部署时。排查顺序如下：
- 先列出本地所有模型：
ollama list，确认模型标识完整。 - 检查配置文件里的模型名是否跟
ollama list完全一致，注意冒号和标签。 - 检查 Base URL 是否指向了正确的服务地址，端口对不对，有没有加多余的路径。
- 如果用的是“远程模型名”，确认该名字在对应平台真实存在，且当前 token 有权访问。
还有个小坑：有些工具会缓存模型列表，你改完模型名后没重启就报错。遇到这个先重启工具，再重新拉取模型列表。
5.2 WebGPU 不兼容与白屏排查
页面白屏，打开控制台发现 navigator.gpu 是 undefined，这说明浏览器不支持 WebGPU。解决办法就是升级浏览器，或者换一个支持 WebGPU 的浏览器内核。
在移动端，问题会更明显。很多安卓 WebView 默认不支持 WebGPU，需要原生应用开发者主动开启相关开关，或者干脆降级到 WASM 方案。iOS 上 Safari 18 开始支持 WebGPU，但老版本仍不可用。所以移动端优先走 WASM 或云端 API，是更务实的方案。
另外即使浏览器支持 WebGPU，也可能因为设备驱动太老、显卡不支持、GPU 被其他进程占用等原因导致 requestAdapter 返回 null。这层异常一定要 catch 住，提示用户刷新或换设备，不能静默失败。
5.3 内存溢出、崩溃与性能调优
最常见的崩溃场景是：模型加载成功后，一生成内容 tab 页就崩溃。原因基本是显存或内存超了。可以从这几个方向排查：
第一，确认模型大小与设备内存匹配。2GB 内存的低端机器就不要硬塞 3B 模型了，换 0.5B 或 1B 模型更现实。
第二，限制上下文长度。把 max_new_tokens 调低，把 max_context_length 设一个合理上限，防止 KV Cache 无限膨胀。
第三，关闭其他占用显存的页面。浏览器里同时开着多个视频 tab、多个 GPU 加速页面，都会挤占显存。
性能调优方面，我实测下来最有用的三个操作：一是尽量用 INT4 量化模型，速度和内存都更友好；二是把模型预加载放到应用启动阶段，避免使用途中加载；三是流式渲染做节流，减少 UI 更新频率。
还有一个小技巧，WebGPU 推理时可以考虑把通用计算和渲染分开，用两个不同设备实例，避免渲染任务和计算任务互相抢占 GPU 资源。不过这个要看具体场景，数据量不大时没必要过度设计。
最后分享一个我个人的习惯：做本地模型应用，一定要在开发环境里做“内存峰值测试”。连续聊 50 轮对话、刷 20 次页面、同时打开多个模型实例，把能想到的极端场景都跑一遍，观察内存曲线。端侧应用最怕的不是功能做不出来，而是做出来以后在用户机器上莫名其妙崩了。多测、多降级、多缓存，把这几个基本功做好，你手里的 Edge AI 应用才能真正从 demo 走向可靠。