浏览器扩展端侧AI推理实战：Manifest V3与WebGPU架构指南-北京尧图网络

1. 端侧推理为何突然成了浏览器扩展的刚需浏览器扩展这个行当过去十年基本就是干三件事改页面样式、拦网络请求、往页面里塞按钮。逻辑简单打包出来几百KB扔到应用商店就完事。但从去年开始我明显感觉到风向变了——越来越多的需求开始往扩展里塞模型而且是那种动辄几十MB甚至上百MB的模型。这个变化的推手其实很实在。一方面用户对隐私的敏感度上来了把数据传到远端服务器再拿结果很多人心里不踏实尤其是涉及截图、文档、聊天记录这类内容。另一方面端侧硬件确实争气现在的笔记本和手机NPU、GPU 的算力放在五年前是不可想象的跑个几亿参数的小模型完全够用。再加上 WebGPU 在主流浏览器里逐步铺开扩展这个原本只能做做 DOM 操作的沙盒环境突然有了直接调用图形算力的能力。但真动手做你会发现坑比想象中多得多。Manifest V3 把后台页面换成了 Service Worker这东西随时可能被浏览器回收你没法像以前那样在后台常驻一个推理会话。扩展的各个运行环境——content script、service worker、offscreen document、popup——彼此隔离模型放哪、算力在哪、结果怎么传每一步都要重新设计。我见过不少团队模型在本地跑得好好的一塞进扩展就各种内存溢出、会话丢失、首帧延迟爆炸。这篇东西就是把我这段时间踩过的坑、验证过的方案、以及一些不太方便写在官方文档里的经验系统地捋一遍。核心围绕浏览器扩展、端侧 AI 推理、Manifest V3、WebGPU、ONNX Runtime这几个关键词展开。不管你是刚打算在扩展里加个翻译、摘要、图像处理功能还是已经在做但被性能问题卡住应该都能从里面找到能直接抄的作业。我尽量说人话把每个选择背后的账算清楚而不是甩一堆 API 名字让你自己猜。2. 整体架构设计模型到底该放在哪个运行环境2.1 先搞清楚扩展里到底有几个房间做端侧推理第一件事不是选模型而是想清楚模型住在哪。浏览器扩展不是一个单一进程它更像一套合租房每个房间的权限、生命周期、能访问的资源都不一样。你得先摸清这套房子的户型才能决定把床模型放哪。主要房间有这么几个Service Worker后台Manifest V3 里的后台脚本负责事件调度、消息中转。它最大的问题是不常驻浏览器觉得你闲着就把你干掉下次事件来了再唤醒。你没法在这里维持一个长时间的推理会话。Content Script内容脚本注入到网页里的脚本能直接操作 DOM但运行在页面的上下文里权限受限而且每个标签页一份模型重复加载会要命。Offscreen Document离屏文档这是 Manifest V3 专门为这类需求开的口子。它本质上是一个隐藏的 HTML 页面有完整的 DOM 和 Web API 访问权限生命周期比 Service Worker 稳定得多可以常驻。端侧推理的主力环境基本就是它。Popup / Side Panel弹窗/侧边栏用户交互界面生命周期跟着用户操作走开开关关很频繁不适合放重资源。Web Worker可以挂在 offscreen document 下面把推理计算从主线程剥离避免卡 UI。我一开始图省事把 ONNX Runtime 的会话直接建在 Service Worker 里结果测试的时候好好的用户用一会儿就报会话已销毁。后来才反应过来Service Worker 被回收了会话自然就没了。这个坑非常典型几乎每个新手都会踩。2.2 推荐的分层架构经过几轮折腾我目前比较稳定的架构是这样的层级运行环境职责是否常驻交互层Popup / Side Panel用户输入、结果展示否调度层Service Worker消息路由、任务队列、权限校验否推理层Offscreen Document模型加载、会话管理、推理执行是计算层Web Worker张量预处理、后处理、耗时计算是注入层Content Script页面数据采集、结果回填否这个分层的核心逻辑是把重资源和长生命周期的东西集中在 offscreen document把轻量的、事件驱动的东西放在 Service Worker把纯计算放在 Web Worker。为什么这么分因为 Service Worker 被回收是浏览器的既定行为你对抗不了只能顺应。把模型和会话放在 offscreen document它不会被随意回收推理的连续性就有保障。而 Web Worker 负责把 CPU 密集的预处理比如图像 resize、tokenize从主线程挪走避免 offscreen document 的 UI 线程被阻塞。2.3 通信链路的设计要点分层之后通信就成了关键。扩展里各个环境之间只能靠chrome.runtime.sendMessage和chrome.runtime.connect通信前者是一次性的后者是长连接。推理这种场景我强烈建议用长连接Port原因有两个一是推理请求往往需要流式返回结果比如逐 token 输出一次性消息满足不了。二是长连接能感知对方是否还活着Service Worker 被回收时端口会断开你可以据此做重连和状态恢复。具体做法是offscreen document 启动时主动向 Service Worker 建立一个命名端口比如叫inference-port。Service Worker 收到请求后通过这个端口转发给 offscreen。结果也走同一个端口回来。这样即使 Service Worker 中途被回收offscreen 这边的端口断开后可以重新发起连接模型会话不受影响。注意offscreen document 的创建有数量限制一个扩展同时只能有一个。所以别想着给每个任务开一个 offscreen老老实实做任务队列。3. 模型选型与 ONNX Runtime 的落地细节3.1 为什么是 ONNX Runtime Web端侧推理的运行时选择其实不少TensorFlow.js、WebLLM、ONNX Runtime Web 都能用。我最后选 ONNX Runtime Web主要基于几个现实考量。第一是模型格式的通用性。ONNX 已经成了模型交换事实上的中间格式PyTorch、TensorFlow 训练出来的模型都能导出成 ONNX。这意味着你的模型供应链不会被某个框架绑死今天用 HuggingFace 上的模型明天换成自己微调的导出流程基本一致。第二是后端切换的灵活性。ONNX Runtime Web 支持 WebGPU、WebGL、WASM 三种执行后端而且可以在运行时根据环境能力动态选择。用户机器支持 WebGPU 就用 GPU 加速不支持就退回 WASM兼容性和性能兼顾。第三是算子覆盖和社区活跃度。我实测下来主流的 Transformer 类模型、CNN 类模型ONNX Runtime Web 的算子支持都比较完整遇到不支持的算子也能通过自定义算子扩展。TensorFlow.js 的问题在于模型转换链路相对封闭WebLLM 则偏向大语言模型场景通用性不如 ONNX Runtime。当然这只是我的选择你要是只做 LLMWebLLM 也值得考虑。3.2 模型体积与量化策略扩展是要分发到用户机器上的模型体积直接决定了安装包大小和首次加载体验。一个 FP32 的 BERT-base 大概 400MB这显然不现实。量化是必须的。我一般按这个顺序做量化决策FP16体积减半精度损失极小WebGPU 原生支持首选。INT8体积再减半精度损失可控适合对体积敏感的场景但要注意 WebGPU 对 INT8 的支持不如 FP16 成熟可能需要走 WASM 后端。INT4体积最小但精度损失明显只适合对精度要求不高的场景比如简单的文本分类。实测数据供参考一个 1.1 亿参数的模型FP32 约 440MBFP16 约 220MBINT8 约 110MB。对于扩展来说超过 100MB 的模型就要慎重了用户下载和加载的耐心是有限的。我的建议是优先 FP16在 WebGPU 上跑性能和精度平衡得最好。如果模型实在太大再考虑 INT8但要接受可能退回 WASM 后端的性能损失。3.3 模型加载的时机与缓存模型加载是端侧推理最耗时的环节几百 MB 的文件从磁盘读进来、解析、初始化会话冷启动几秒到十几秒都正常。这个体验必须优化。我的做法是懒加载缓存。扩展安装后不立即加载模型等用户第一次触发推理功能时再加载。加载完成后会话保持在 offscreen document 里后续请求直接复用。同时利用浏览器的 Cache API 把模型文件缓存起来第二次启动就不用重新下载了。// offscreen document 中的模型加载逻辑 async function loadModel(modelUrl) { const cache await caches.open(model-cache-v1); let response await cache.match(modelUrl); if (!response) { response await fetch(modelUrl); // 只缓存成功的响应 if (response.ok) { await cache.put(modelUrl, response.clone()); } } const modelBuffer await response.arrayBuffer(); const session await ort.InferenceSession.create(modelBuffer, { executionProviders: [webgpu, wasm], graphOptimizationLevel: all }); return session; }这里有个细节executionProviders数组的顺序很重要ONNX Runtime 会按顺序尝试WebGPU 不可用就自动退回 WASM。这样你不需要自己写环境检测逻辑。实操心得模型文件建议放在扩展包外通过chrome.runtime.getURL或者远端 CDN 加载。放在扩展包里会导致安装包巨大而且应用商店审核对包体积有要求。但放远端就要考虑首次加载的网络延迟所以缓存策略必须做好。4. WebGPU 加速的实操与性能调优4.1 WebGPU 在扩展里的可用性现状WebGPU 是这一轮端侧推理性能提升的关键。它让扩展能直接调用 GPU 做通用计算而不像 WebGL 那样要绕着图形渲染的弯子走。但它的可用性有几个现实约束你得心里有数。首先是浏览器版本。Chrome 从 113 开始默认开启 WebGPUEdge 跟进得也快Firefox 和 Safari 相对滞后。所以你的扩展必须做好降级不能假设所有用户都有 WebGPU。其次是扩展环境的限制。WebGPU 在 offscreen document 里是可以用的但在 Service Worker 里不行。这也是为什么推理必须放在 offscreen document 的另一个原因。最后是硬件差异。不同 GPU 对 WebGPU 的支持程度不一样有些老显卡虽然浏览器版本够但驱动层面支持不完整跑起来可能比 WASM 还慢。所以运行时探测动态降级是必须的。4.2 运行时能力探测我一般用这段代码做探测async function detectWebGPU() { if (!navigator.gpu) return false; try { const adapter await navigator.gpu.requestAdapter(); if (!adapter) return false; // 检查是否支持推理需要的特性 const device await adapter.requestDevice(); return !!device; } catch (e) { return false; } }探测通过就用 WebGPU不通过就退回 WASM。这里要注意requestAdapter和requestDevice都是异步的而且可能因为权限或资源问题失败所以一定要包在 try-catch 里。4.3 性能调优的几个关键点WebGPU 跑起来之后性能调优主要围绕这几个方向批处理大小batch size。端侧推理和服务器不一样服务器追求吞吐端侧追求延迟。批处理太大会增加单次推理延迟太小又浪费 GPU 算力。我的经验是交互式场景 batch size 设为 1后台批处理场景可以设到 4 或 8具体要看模型和硬件。输入形状固定化。WebGPU 对动态形状的支持不如静态形状好如果模型输入形状经常变化会触发重新编译性能断崖式下跌。所以尽量把输入 padding 到固定长度比如文本模型统一 pad 到 128 或 256。显存管理。GPU 显存是有限的模型权重、中间激活值、输入输出张量都占显存。如果显存不够WebGPU 会报错或者悄悄退回 CPU。我遇到过一个大模型在 4GB 显存的机器上跑batch size 稍微大一点就崩最后只能限制 batch size 并做显存监控。避免频繁的 CPU-GPU 数据搬运。每次把数据从 CPU 传到 GPU 或反过来都有开销。所以预处理尽量在 GPU 上做或者至少把多次小传输合并成一次大传输。4.4 一个真实的性能对比我在一台配备集成显卡的笔记本上做过对比测试模型是一个 1.1 亿参数的文本分类模型输入长度 128后端首次推理后续平均内存占用WASM (单线程)3.2s850ms420MBWASM (多线程)2.8s420ms480MBWebGPU1.5s95ms620MB可以看到 WebGPU 在后续推理上有数量级的优势但首次推理因为要编译着色器优势没那么明显而且显存占用更高。这个数据说明如果你的场景是高频推理WebGPU 收益巨大如果是低频、一次性的WASM 也够用还省显存。5. Manifest V3 生命周期管理的坑与解法5.1 Service Worker 被回收的真实影响Manifest V3 最让人头疼的就是 Service Worker 的短生命周期。浏览器会在空闲 30 秒左右回收它有事件来了再唤醒。这个机制对普通扩展没影响但对推理场景是致命的。我遇到过的具体问题包括推理任务进行到一半Service Worker 被回收消息通道断开结果丢失模型会话状态存在 Service Worker 的全局变量里回收后状态清零定时任务被中断批处理队列丢失。这些问题的根源都是把不该放 Service Worker 的东西放进去了。解法就是前面说的分层架构把状态和会话放到 offscreen documentService Worker 只做无状态的消息中转。5.2 保活策略的正确姿势有人会想那我让 Service Worker 一直活着不就行了网上确实有一些保活技巧比如定时发消息、播放静音音频、开 WebSocket 长连接。但我要泼盆冷水这些方法要么已经被浏览器封堵要么违反应用商店政策风险很大。正确的做法不是对抗回收而是设计成可恢复的。具体来说所有推理状态持久化到chrome.storage.session或 IndexedDBService Worker 唤醒后能恢复。消息通道断开后offscreen document 主动重连。任务队列用持久化存储Service Worker 重启后继续处理未完成的任务。这样即使 Service Worker 被回收一百次用户体验也不受影响。5.3 offscreen document 的生命周期管理offscreen document 虽然比 Service Worker 稳定但也不是永远活着。它会在扩展被禁用、浏览器关闭时销毁。而且创建它有明确的理由限制Manifest V3 规定只有特定原因才能创建 offscreen document比如DOM_PARSER、BLOBS、WORKERS等。推理场景一般用WORKERS这个理由因为你要在里面跑 Web Worker。创建代码如下async function ensureOffscreenDocument() { const existingContexts await chrome.runtime.getContexts({ contextTypes: [OFFSCREEN_DOCUMENT] }); if (existingContexts.length 0) return; await chrome.offscreen.createDocument({ url: offscreen.html, reasons: [WORKERS], justification: Run AI inference in a persistent context }); }注意getContexts这个 API 是较新版本才有的老版本要用clients.matchAll或者自己维护标志位。我建议用新 API然后对老版本做兼容。踩坑记录offscreen document 创建是异步的而且可能因为并发调用创建出多个。一定要加锁或者用单例模式我见过因为并发创建导致两个 offscreen 同时跑推理内存直接爆掉的案例。6. 常见问题排查与实战避坑清单6.1 推理结果不稳定或报错这是最常见的问题原因通常有几类模型输入格式不对。ONNX 模型对输入张量的形状、类型、名称都有严格要求。我建议在加载模型后先打印session.inputNames和session.outputNames确认输入输出的名称和顺序再构造输入张量。很多人栽在输入名称对不上报错信息又很隐晦。数据类型不匹配。ONNX 模型期望的输入类型可能是float32、int64、int32你传错了就会报错或者结果异常。特别是int64JavaScript 里没有原生 64 位整数要用BigInt64Array这个很容易忽略。张量形状动态变化。前面提过WebGPU 对动态形状支持不好。如果输入形状每次都不同会反复触发编译。解法是固定形状或者用 ONNX Runtime 的动态形状支持但性能会打折。6.2 内存泄漏与崩溃端侧推理是内存大户稍不注意就泄漏。我总结的几个高发点会话未释放。每次创建InferenceSession都会占内存如果反复创建不释放很快就爆了。会话应该复用实在要重建先调用session.release()。张量未释放。ONNX Runtime 的张量是手动管理的用完要tensor.dispose()。虽然现在有自动回收机制但显式释放更保险。事件监听器未移除。在 offscreen document 里注册的监听器如果组件销毁时没移除会一直持有引用导致内存泄漏。我一般会在开发阶段用 Chrome 的 Memory 面板做堆快照对比跑几十次推理后看内存是否持续增长。如果增长基本就是上面几个问题之一。6.3 首帧延迟过长用户第一次用功能等十几秒才出结果体验很差。优化方向有几个模型预热。扩展启动后在后台悄悄加载模型并跑一次空推理把着色器编译、内存分配这些一次性开销提前做掉。用户真正用时就是热启动快很多。分阶段加载。如果模型很大可以先加载一个小的、能快速响应的模型同时后台加载大模型大模型就绪后切换。这样用户至少能立刻看到反馈。进度反馈。加载过程中给用户明确的进度提示哪怕只是正在加载模型 45%也比干等着强。进度可以通过fetch的Content-Length和已读字节数计算。6.4 常见问题速查表现象可能原因排查方向解决方案会话创建失败模型文件损坏或格式不对检查 ONNX 文件完整性重新导出模型验证 opset 版本推理结果全为 0输入未正确归一化检查预处理逻辑按模型要求做归一化WebGPU 报错退回 WASM显存不足或驱动问题查看控制台 GPU 错误降低 batch size 或改用 WASMService Worker 频繁重启空闲被回收查看扩展后台日志状态持久化设计成可恢复内存持续增长张量或会话未释放堆快照对比显式 dispose复用会话首帧延迟超过 10s模型太大或未预热测量各阶段耗时预热分阶段加载进度反馈6.5 几个不太方便写在文档里的经验别在 content script 里做推理。content script 运行在页面上下文每个标签页一份模型重复加载会拖垮浏览器。而且页面可能随时关闭推理中途被打断。所有推理都应该在 offscreen document 里做content script 只负责采集数据和回填结果。模型版本管理要提前规划。扩展更新时模型可能也要更新。如果模型缓存在用户本地要考虑版本兼容和清理策略。我一般给模型 URL 带上版本号比如model-v2.onnx新版本用新 URL旧缓存定期清理。测试要覆盖低端设备。开发机往往配置很好跑得飞快但用户的设备可能很老。我建议至少在一台 4GB 内存、集成显卡的机器上测一遍看看会不会崩、会不会卡。很多问题只有在这种设备上才暴露。注意应用商店的政策。不同商店对扩展包体积、远端代码加载、权限申请都有要求。端侧推理涉及大模型和 WebGPU可能触发额外审核。提前了解政策别等提交了被打回来。7. 写在最后的一点个人体会这套架构我前后迭代了三四版从最初把模型塞 Service Worker 的天真方案到现在分层清晰、可恢复、可降级的稳定实现中间踩的坑基本都写在上面的章节里了。如果只让我留一句话给准备入坑的人那就是端侧推理在浏览器扩展里的核心矛盾不是算力不够而是生命周期不可控。把这个问题想明白架构就顺了。另外提一个后续可以扩展的方向现在这套方案是单模型的如果你要做多模型协同比如一个小模型做粗筛、一个大模型做精排可以在 offscreen document 里维护多个会话用任务队列调度。这个我还在试验阶段等跑稳了再单独写一篇。

浏览器扩展端侧AI推理实战：Manifest V3与WebGPU架构指南

相关推荐

PC输入法怎么选？微信、Rime、豆包三套方案横向对比与配置指南

Python+Hadoop+Spark构建零售大数据可视化系统实战

FTC调查AI安全与Gemini 4受限开放：开发者如何应对监管与模型接入挑战

更多资讯

Oracle 11g实战源码包：可调试、可验证、开箱即用的活体教材

时序场景生成：Copula理论与工程实践

医疗知识图谱工程实战：从Excel到可扩展问答系统

Oracle 11g可执行脚本教学包：建库/调优/备份一体化实战

Redis实战：缓存三兄弟与分布式锁解决方案

具身智能：从概念到应用的核心技术与挑战

今日更新

猫狗目标检测数据集：VOC/COCO/YOLO三格式一体化实战包

HDU2017多校标程复现：算法竞赛工程化真题沙盒

Codex Sandbox 隔离环境拆解：AI Agent 的临时实验室如何运作

本周精选

防幻觉智能体架构：电源硬件设计中的大模型编排与工具化实践

OpenGL面试核心考点：渲染管线、矩阵变换与性能排查全解析

全国计算机二级C语言真题PDF高效刷题指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？