浏览器端跑大模型这两年的推进速度比预想中快。这次我们来看一个叫 Glaux 的开源项目它把 Hugging Face 社区里的 ONNX 模型直接搬到浏览器里做推理。你可以把它理解成一个“浏览器版模型运行底座”不用安装 Python不用配 CUDA不用启动后端服务打开网页就能加载并运行成百上千个社区模型。最值得关注的有几点一是纯浏览器运行推理计算发生在本地数据不用上传到服务端二是模型来自 Hugging Face 的 ONNX 社区模型覆盖文本、图像、语音等常见任务三是底层有 WebGPU / WebAssembly 两套执行后端有可用显卡就走 GPU 加速没有就退回 CPU。对前端团队、对只想快速验证模型效果的人来说这条链路足够直接。这篇文章会按照“功能定位 - 技术原理 - 环境准备 - 部署启动 - 功能测试 - API 与批量 - 性能观察 - 问题排查 - 最佳实践”的顺序来写帮你判断它能不能解决你的问题以及该怎么验证。1. Glaux 核心能力速览先给出一张速览表后续所有细节都围绕这张表展开。能力项说明项目名称Glaux项目类型浏览器端Browser-OnlyAI 推理工具 / 应用模型来源Hugging Face 社区 ONNX 模型推理引擎ONNX Runtime Web执行后端为 WebGPU / WebAssembly运行环境现代浏览器首次加载模型需要网络资源服务端依赖无后端推理服务模型在浏览器本地运行主要功能文本生成、图像识别、语音识别等取决于加载的具体 ONNX 模型硬件门槛支持 WebGPU 的显卡可获得 GPU 加速无显卡可退回 CPU 推理启动方式静态网页部署或本地开发服务器启动API 能力浏览器端 JavaScript 接口批量任务可通过 Web Worker 做前端并发处理吞吐受浏览器内存限制隐私特性输入数据不离开浏览器无需上传服务端适合场景前端 AI 应用、模型效果快速验证、隐私敏感场景、教学演示需要强调一点这个工具和传统 AI 软件最大的区别是模型并不是内嵌死的。Glaux 的核心价值是“浏览器端模型加载与推理”这一套底座具体跑什么能力取决于你从 Hugging Face 加载哪个 ONNX 模型。所以评估 Glaux 时第一件事不是问“它能做什么”而是问“我要跑的模型是否已经导出成 ONNX 格式”。2. 适用场景与使用边界2.1 适合谁用从浏览器端 AI 这一类工具的通用定位来看Glaux 适合下面几类人前端开发者是第一批受益者。想在现有 Web 应用里嵌入 AI 能力又不想为了一个图像分类接口去维护 Python 服务和 GPU 服务器浏览器端推理可以显著降低交付成本。AI 学习者也能省很多事不需要理解 CUDA 版本、PyTorch 环境或 Docker 镜像打开一个浏览器页面就能把 Hugging Face 上的模型拉下来跑对理解模型输入输出格式、推理链路很有帮助。数据敏感场景同样值得关注。聊天内容、图片、文档如果不想经过第三方 API浏览器端推理让数据留在用户本机服务端完全不接触原始输入隐私模型会清爽很多。另外运维成本敏感的团队可以把它落地为内部工具静态页面就能承载推理场景不需要常年挂着 GPU 实例。2.2 不适合什么场景浏览器端推理不是万能的。超大规模模型不要硬上浏览器内存和显存都很有限跑 7B、13B 甚至更大的模型加载时间长、推理速度慢体验很难受。高频并发的生产环境也不适合单机浏览器的资源上限决定了它不能替代服务端推理引擎如果要做高并发 API还是老老实实部署后端服务。模型训练同样不在讨论范围内Glaux 这类工具定位是推理不是训练。还有一类场景要提前想清楚完全离线内网部署。虽然模型加载后会进入浏览器缓存但首次获取权重仍然需要网络路径。如果内网完全隔离需要先把模型文件放到内部静态文件服务上。2.3 使用边界与合规提醒浏览器端 AI 不等于没有边界。模型授权方面Hugging Face 上不同模型有不同的 License有些模型仅限研究商用前必须确认模型许可。数据方面虽然输入不离开浏览器但模型权重本身从公共网络加载传输链路可用性取决于当前网络环境。内容方面不要让浏览器端生成或识别的内容用于违法、侵权场景。涉及人脸、声音、版权素材时必须确认授权这是所有 AI 应用绕不开的红线。3. 技术原理浏览器端 AI 如何跑 ONNX 模型看 Glaux 之前先理解浏览器端推理的四个关键概念。3.1 ONNX 是模型交换的中间格式ONNXOpen Neural Network Exchange是开放神经网络交换格式它不是某个训练框架的私有格式。Hugging Face 上大量模型同时提供 PyTorch 权重和 ONNX 导出权重。浏览器端要跑模型推荐优先选 ONNX 格式因为 ONNX Runtime Web 直接消费这款格式。如果模型只提供 PyTorch 权重需要先用转换工具导出成 ONNX再交给前端。这也解释了为什么 Glaux 会把“支持 Hugging Face ONNX 社区模型”作为核心卖点——ONNX 是浏览器端最容易承载的模型形态。社区里还经常出现两种量化格式INT8 和 INT4。量化的目的是把 FP32 权重压缩成更小的整数精度模型体积缩小、加载速度变快浏览器端尤其需要。代价是精度会有一定损失具体损失多少因模型和任务而异。实际选型时我建议先跑 FP32 版本确认效果再对比 INT8 版本如果质量可接受就把 INT8 作为浏览器端默认版本。3.2 WebAssembly 与 WebGPU 双后端ONNX Runtime Web 提供两条执行路径。没有可用 GPU 时它退回 WebAssembly 后端这相当于在浏览器里用 CPU 做推理兼容性最好几乎所有现代浏览器都能跑。检测到 WebGPU 时推理算子会被编译到 GPU 执行速度优势明显尤其适合矩阵运算密集的 Transformer 模型。WebGPU 是浏览器 GPU API 的新标准Chrome 113 之后、Edge 113 之后开始支持NVIDIA、AMD、Intel 近几年的显卡都在支持范围内。如果你用的浏览器比较老或者系统没有可用 GPUGlaux 这类工具会走 WebAssembly 路径功能仍然可用只是速度会慢一些。3.3 Transformers.js 模型生态浏览器端加载 Hugging Face 模型常用的方式是借助huggingface/transformers这类前端库。它把模型加载、分词、后处理这些步骤封装成了 pipeline 接口前端开发者不需要手动处理 tokenizer 和 tensor 形状。Glaux 选择 Hugging Face ONNX 社区模型本质上就是把这一整套模型生态搬到了浏览器。3.4 推理数据流一次完整的浏览器端推理大致是这条链路根据任务类型和模型名从 Hugging Face 拉取 ONNX 权重和 tokenizer 配置文件权重文件进入浏览器缓存后续重复加载可以跳过下载输入文本/图片经过分词器和预处理管线转成模型的输入 tensorONNX Runtime Web 把 tensor 交给 WebGPU 或 WebAssembly 后端执行拿到输出 tensor再做后处理得到用户可读的文本、分类标签或坐标数据。理解这条链路之后后面所有测试、排错就都有据可依了。4. Glaux 本地部署环境准备浏览器端项目对环境的要求比传统 AI 项目低很多但也不是零准备。下面是建议的环境检查清单。4.1 浏览器版本与 WebGPU 支持优先使用的浏览器Chrome 113、Edge 113。Firefox 对 WebGPU 的支持仍在推进中Safari 的支持相对滞后建议把 Chrome 或 Edge 作为主力测试环境。第一次使用之前先跑一个 WebGPU 检测脚本见后面第 6 节。4.2 网络访问与模型资源加载浏览器端要从 Hugging Face 拉取模型权重首次加载时间取决于模型大小和网络带宽。如果当前网络访问 Hugging Face 不稳定更稳妥的做法是把模型权重文件下载到本地托管到自己的静态文件服务或 CDN 上然后在代码里把模型路径指向自己的服务器地址。这样既保证可用性也让资源加载路径可控。4.3 磁盘与内存规划不同模型体积差异很大文本生成模型从几百 MB 到几个 GB 都有图像分类模型常见的是几十 MB 到几百 MB。首次加载前要确认磁盘空间足够。运行阶段模型会被加载进浏览器内存模型越大、同时加载的模型越多内存占用越高浏览器标签页崩溃的风险也越大。建议一次只保持一个模型在内存里不用的模型及时清理。4.4 开发工具准备建议准备Node.js 16 以上用于跑本地开发服务器和安装依赖一个前端项目目录模型文件、输入素材、输出结果分目录管理Chrome DevTools用来观察网络请求、CPU 占用、GPU 进程和内存变化。5. 安装部署与启动方式Glaux 这类浏览器端项目的部署方式比较灵活下面给出三种常见启动路径。5.1 本地 npm 项目方式推荐用 Vite 作为本地开发服务器依赖管理清晰改动代码即时刷新。# 初始化项目 npm init -y # 安装浏览器端推理依赖 npm install huggingface/transformers onnxruntime-web # 安装 Vite 作为本地开发服务器 npm install -D vite # 启动本地服务 npx vite启动后Vite 会输出一个本地访问地址。在自己电脑上做测试访问http://localhost:5173即可。5.2 静态页面方式如果不想引入构建工具也可以直接用原生 HTML 加 CDN 引入。新建一个index.html在script标签里通过 CDN 加载依赖。!DOCTYPE html html langzh-CN head meta charsetUTF-8 / meta nameviewport contentwidthdevice-width, initial-scale1.0 / titleGlaux 浏览器端 AI 测试页/title /head body h1Glaux Browser AI Test/h1 pre idlog准备加载模型.../pre script typemodule import { pipeline } from https://cdn.jsdelivr.net/npm/huggingface/transformers; const log document.getElementById(log); async function main() { const classifier await pipeline( sentiment-analysis, Xenova/distilbert-base-uncased-finetuned-sst-2-english ); const result await classifier(Browser-only AI is great!); log.textContent JSON.stringify(result, null, 2); } main().catch((err) { log.textContent 加载失败: err.message; }); /script /body /html这种方式适合快速验证。把 HTML 放到任意静态目录或者直接用npx serve就可以跑起来。5.3 模型加载路径配置如果 Hugging Face 原始域名访问不稳定可以把模型权重放到自己的静态服务器上。以图像分类模型为例先手动下载模型仓库里的onnx/model.onnx、config.json、tokenizer.json等文件然后放到本地public/models/目录代码里改成相对路径import { pipeline } from huggingface/transformers; const classifier await pipeline( image-classification, /models/vit-base-patch16-224 );这里的关键是模型仓库目录结构要和 Transformers.js 预期的结构保持一致。不同模型需要的配置文件不同文本模型必须保证 tokenizer 文件齐全图像模型需要确认图像处理器配置存在。路径改成本地之后首次访问会从自己的静态服务加载不再依赖外部网络。6. Glaux 功能测试与效果验证下面用一套通用验证流程跑通浏览器端 ONNX 模型的加载和推理。6.1 检查 WebGPU 是否可用新建check-gpu.jsasync function checkWebGPU() { if (!navigator.gpu) { console.warn(当前浏览器不支持 WebGPU将使用 CPU 推理); return false; } const adapter await navigator.gpu.requestAdapter(); if (!adapter) { console.warn(未获取到 GPUAdapter将使用 CPU 推理); return false; } console.log(GPU 适配器信息:, adapter.info); return true; } checkWebGPU().then((supported) { console.log(WebGPU 支持状态:, supported); });把这段脚本引入页面控制台能看到 GPU 适配器信息说明 WebGPU 可用。如果打印的是false后面推理会走 WebAssembly 后端能力不受影响只是速度慢一些。6.2 文本生成测试文本生成是浏览器端 ONNX 模型最常见的测试场景。以一个小型 GPT-2 ONNX 模型为例import { pipeline } from huggingface/transformers; async function runTextGeneration() { const generator await pipeline(text-generation, Xenova/gpt2); const result await generator( Browser-only AI can run models directly in, { max_new_tokens: 50, do_sample: true } ); console.log(result); } runTextGeneration().catch((err) console.error(err));判断成功的标准模型加载阶段控制台没有报错返回结果包含generated_text字段内容是连贯的英文文本生成 50 个 token 没有触发浏览器崩溃第二次运行同一句提示词能明显感觉到加载速度变快因为权重已经进了缓存。返回结构大致如下[ { generated_text: Browser-only AI can run models directly in the browser with WebGPU acceleration... } ]常见失败模型加载 404、tokenizer 文件缺失、浏览器内存不足导致标签页崩溃。后面第 9 节会展开。6.3 图像分类测试图像分类任务需要一张测试图片。样例代码import { pipeline } from huggingface/transformers; const classifier await pipeline( image-classification, Xenova/vit-base-patch16-224 ); const output await classifier(./test.jpg); console.log(output);判断标准控制台正常打印分类标签和置信度分数第一张图片首次推理耗时明显比后续推理高原因是权重加载和 WebGPU 编译缓存预热更换不同图片后输出的标签和分数有区分度而不是固定输出同一个结果。6.4 从 Hugging Face 加载其他 ONNX 模型的通用步骤Glaux 的价值在于模型可替换所以要学会“换模型”的通用方法去 Hugging Face 搜索目标模型确认该模型有 ONNX 权重文件查看模型卡片里的onnx目录或 ONNX 版本信息确认模型任务类型例如text-classification、image-segmentation、automatic-speech-recognition把任务类型和模型名传入pipeline接口首次加载成功后记录模型体积、加载耗时、推理解析结果作为后续批量选型的参考基线。6.5 功能验收清单验证项输入预期结果WebGPU 探测启动脚本控制台输出适配器信息文本生成英文短句返回带generated_text的 JSON图像分类本地 JPG返回标签和分数模型重复加载刷新页面后再推理第二次更快命中浏览器缓存模型切换更换另一个 ONNX 模型正常加载输出结构匹配任务类型7. 浏览器端接口 API 与批量任务处理Glaux 这类工具虽然没有传统意义上的后端 API但前端 JavaScript 接口本身就是“API”。只需要把模型推理封装成一个异步函数外部调用方完全感知不到后端是 Python 服务还是浏览器线程。7.1 封装单个推理接口import { pipeline } from huggingface/transformers; class InferenceService { constructor(task, model) { this.task task; this.model model; this.pipe null; } async ensureLoaded() { if (!this.pipe) { this.pipe await pipeline(this.task, this.model); } return this.pipe; } async predict(input) { const pipe await this.ensureLoaded(); return pipe(input); } } const service new InferenceService( sentiment-analysis, Xenova/distilbert-base-uncased-finetuned-sst-2-english ); async function handleRequest(text) { const result await service.predict(text); console.log(result); }引入ensureLoaded是为了避免每次调用都重新加载模型模型只初始化一次后续并发请求复用同一个 session。7.2 Web Worker 批量推理浏览器主线程不适合跑多层循环因为推理过程会阻塞 UI。批量任务建议放到 Web Worker 里。下面是一个“接收图片路径数组 - 逐张推理 - 返回结果数组”的通用 Worker 模板。// inference.worker.js import { pipeline } from huggingface/transformers; let classifier null; self.onmessage async (event) { const { task, model, dataList } event.data; if (!classifier) { classifier await pipeline(task, model); } const results []; for (const item of dataList) { try { const res await classifier(item); results.push({ item, result: res, status: success }); } catch (err) { results.push({ item, error: err.message, status: failed }); } } self.postMessage(results); };主线程调用const worker new Worker(./inference.worker.js); worker.onmessage (event) { console.log(批量结果:, event.data); }; worker.onerror (err) { console.error(Worker 异常:, err); }; worker.postMessage({ task: image-classification, model: Xenova/vit-base-patch16-224, dataList: Array.from({ length: 10 }, (_, i) ./images/img_${i}.jpg) });7.3 批处理队列设计在 Worker 里循环调用推理接口本质是一种“串行批处理”。如果模型 session 不支持并发推理串行是最稳的方案。真实项目里建议加上任务队列维护待处理图片路径分批发送给 Worker失败重试单次推理失败时记录错误信息不中断整个批次结果日志每处理一条就输出一条日志方便定位是哪张图片导致的问题内存限制当批次过大时分批清理dataList避免一次性把几百张图片全部载入内存。批次大小从 1 开始逐步调大比较稳妥。如果浏览器标签页崩溃优先减小批次、改用更小的模型或者切换量化版本。8. 资源占用与性能观察方法浏览器端 AI 的性能观察比 CLI 工具更直观但是很多人不知道看哪里。8.1 观察工具打开 Chrome DevTools用Performance Monitor面板可以实时观察 CPU 使用率。需要看 GPU 占用时在 Chrome 地址栏输入chrome://gpu检查 WebGPU 状态在任务管理器中打开“GPU 进程”列能看到浏览器 GPU 进程的内存和显存占用变化。实际操作时建议先打开 Performance Monitor再触发一次推理观察模型加载阶段CPU 使用率升高网络面板出现模型文件请求推理执行阶段GPU 进程占用升高说明走了 WebGPU 后端推理结束后CPU/GPU 占用回落内存不会马上释放这是浏览器常态。如果推理过程中 GPU 进程占用一直为 0大概率没有走 WebGPU 后端需要检查浏览器版本或者 onnxruntime-web 的执行后端配置。8.2 CPU 推理与 GPU 推理的差异同一模型WebGPU 后端和 WebAssembly 后端的差距在 Transformer 模型上通常很明显。WebAssembly 是纯 CPU 计算资源消耗稳定但上限有限WebGPU 把矩阵运算交给 GPU显存足够时速度快很多。不过 GPU 推理要付出启动成本模型第一次走 WebGPU 时算子需要编译首次推理延迟反而可能更高第二次开始才体现优势。8.3 影响性能的关键因素模型参数量和输入长度输入越长矩阵运算规模越大量化等级INT8 比 FP32 体积小、推理快但精度有损浏览器后台标签页浏览器会限制后台标签页的定时器和资源推理任务最好保持页面在前台同时打开的标签页数量其他页面的 GPU 绘制任务会竞争 GPU 资源系统电源策略笔记本节能模式下 GPU 频率受限性能波动明显。8.4 降低资源占用的方法尽量选择量化后的 ONNX 模型控制输入序列长度文本生成任务给max_new_tokens设置合理上限一次只保持一个模型 session不用的模型置为null并清理引用大数据量任务拆分批次避免一次性载入过多数据推理过程放在 Web Worker 中主线程只做结果渲染减少页面卡顿。9. 常见问题与排查方法浏览器端 AI 的坑比较集中下面这张表直接对应排查步骤。问题现象可能原因排查方式解决方案模型加载返回 404模型仓库里没有 ONNX 权重打开 Hugging Face 仓库确认文件结构换一个有 ONNX 权重的模型或先导出 ONNX页面提示 CORS 错误跨域加载 wasm 或模型文件打开控制台查看具体域名使用本地静态服务托管模型配置 wasm 路径检测不到 WebGPU浏览器版本过低或显卡驱动问题访问chrome://gpu检查 WebGPU 状态升级浏览器更新显卡驱动退回 CPU 推理页面标签页崩溃模型过大或批次数据过多Performance Monitor 观察内存曲线换量化模型减小批次减少同时加载模型数量推理速度很慢走了 WebAssembly 后端检查navigator.gpu和 GPU 进程占用升级浏览器确认 WebGPU 可用后重启页面模型输出是乱码tokenizer 文件缺失或任务类型不匹配查看控制台警告信息确认模型仓库包含 tokenizer 文件修正任务类型首次加载时间过长模型文件较大网络带宽有限网络面板查看下载大小使用 INT8 量化模型或把模型文件放到 CDN相同提示词结果不一致生成任务开启了采样检查do_sample参数取消采样使用do_sample: false得到确定性输出补充几个实际排查技巧模型文件缺失是最常见的启动问题。Hugging Face 仓库里不一定都有 ONNX 子目录有些模型只提供 PyTorch 权重。遇到 404先别改代码先去仓库确认文件结构。CORS 错误通常发生在 CDN 直接加载模型文件的场景。解决方法是把onnxruntime-web的 wasm 资源路径也指向同源地址import * as ort from onnxruntime-web; ort.env.wasm.wasmPaths /wasm/; const session await ort.InferenceSession.create(/models/model.onnx, { executionProviders: [webgpu, wasm] });如果不需要直接操作onnxruntime-web只用huggingface/transformers的 pipeline则优先确认模型路径是否可达、浏览器缓存是否被清空。标签页崩溃不是常态但一旦出现说明当前模型或数据量已经超出浏览器内存承受范围。此时最优解不是优化代码而是换更小的量化模型。10. Glaux 浏览器端 AI 最佳实践与使用建议从工程角度浏览器端 AI 项目有几个通用建议。10.1 模型选型优先考虑量化版本浏览器内存是稀缺资源。同一个模型FP32 版本和 INT8 版本在文件体积、加载时间、推理速度上差距很大但效果差异通常可控。建议固定一套评估流程先在服务端或用 FP32 模型确认效果上限再切换到 INT8 模型做浏览器端验证质量达到要求就固定使用 INT8。10.2 本地托管模型资源不要把线上 Hugging Face 原始域名作为唯一的模型来源。更稳妥的做法是把模型文件下载后放到自己的 CDN 或对象存储代码里使用相对路径或自定义域名。这样部署环境可预测不受外部访问稳定性影响也方便做内网部署。10.3 用 Web Worker 避免阻塞 UI所有推理任务都放到 Web Worker。主线程只负责渲染结果和处理用户输入。即使推理过程较长页面也不会卡死这是个“成本很低、收益明显”的工程决策。10.4 批量任务必须设计失败重试和日志浏览器端批量任务比后端更容易被资源限制打断。设计任务队列时每条数据记录状态推理失败自动跳过并记录错误重试次数不要超过 2 次避免死循环。批次大小从 1 开始调每次翻倍直到出现内存压力为止。10.5 隐私、版权与合规边界再次强调用户上传到浏览器的数据不被服务端记录但代码内部如果接入了第三方分析工具仍然可能外传数据模型 License 各不相同商用前必须逐一核对人脸识别、声音克隆、版权素材相关任务必须有明确的授权链路不授权不用发布到公网的应用要设置访问控制避免被刷量或滥用。11. 总结与下一步Glaux 这类浏览器端 AI 工具最值得尝试的点是把“安装环境、配置 CUDA、启动服务”的流程压缩成了“打开页面、选择模型、开始推理”。对一个前端开发者来说这是目前接触 ONNX 模型门槛最低的路径之一。拿到项目后建议按这个顺序验证先跑 WebGPU 检测脚本确认自己的浏览器和显卡走的是 GPU 路径还是 CPU 路径用一个小的文本分类或图像分类模型跑通整个加载和推理链路观察模型下载体积、首次推理耗时、内存占用和 GPU 进程占用再试一个你真实业务需要的模型确认输出格式是否符合预期。最容易踩的坑集中在三处模型仓库没有 ONNX 权重导致 404、跨域加载 wasm 资源导致 CORS 错误、模型过大导致浏览器标签页崩溃。这三个问题都可以通过“换模型、本地托管、换量化版本”解决。后续可以继续扩展的方向包括把推理接口封装成前端 SDK在 Electron 桌面应用里复用同一套模型加载逻辑接入 WebNN 后端在更多浏览器上获得更优的推理性能结合 Web Worker 和 IndexedDB 做一个离线优先的浏览器端模型工具箱。先拿一个小模型跑通 WebGPU 链路再逐步换更大的模型这条路走起来最稳。