浏览器扩展这个赛道这两年因为Manifest V3的强制迁移正在经历一次彻底的重构。以前大家写扩展逻辑很简单内容脚本抓DOM后台脚本发请求完事。但现在情况变了——越来越多的场景要求数据不出端比如文档摘要、图片处理、语音转写、实时翻译这些需求如果还走云端API延迟、成本、隐私三座大山压下来产品根本跑不通。于是端侧AI推理被推到了前台而浏览器扩展恰好是承载它的一个天然容器用户装完即用不需要额外装客户端模型跟着扩展走推理在本地跑。但问题也来了。浏览器扩展的运行环境跟原生应用、Node服务完全不是一回事。Service Worker有生命周期随时可能被干掉WebGPU虽然能用但不同浏览器的支持程度参差不齐ONNX Runtime Web的WASM后端在扩展的CSP策略下经常加载失败。这些坑我在过去一年里几乎踩了个遍有些是文档里压根没写的有些是官方示例跑通了但实际项目一上就崩的。这篇文章就把这套东西从头到尾拆一遍讲清楚在Manifest V3的约束下怎么把端侧AI推理系统稳稳当当地跑起来。1. 为什么端侧推理在扩展里是个真需求1.1 云端推理的三笔账算不过来先说最直接的动机。假设你做一个网页内容摘要扩展用户点一下按钮把当前页面正文提取出来生成一段200字的摘要。如果走云端流程是内容脚本抓正文→发给后台→后台调API→等返回→渲染结果。这里面有几个隐性成本。第一是延迟。一次网络往返加上服务端排队和推理时间保守估计1.5到3秒。用户点完按钮盯着屏幕等三秒体验已经很差了。如果遇到网络抖动五秒以上也正常。端侧推理用WebGPU跑一个量化后的小模型同样的摘要任务首次加载模型可能要两三秒但后续每次推理可以压到200到500毫秒这个差距是数量级的。第二是成本。云端API按token计费一个日活一万的扩展每人每天用五次每次输入输出加起来算1000 token一天就是五千万token。这个量级下每个月的API账单足够养活一个小团队。端侧推理的边际成本是零模型下载一次后面随便跑。第三是隐私。用户浏览的网页内容很多是工作文档、内部系统、个人笔记。把这些内容发到第三方服务器本身就是个合规风险。端侧推理数据不出设备这一条在B端场景里几乎是硬性要求。1.2 扩展作为端侧推理容器的独特优势有人会问端侧推理为什么不做成桌面应用或者原生插件答案是分发成本。浏览器扩展的分发链路极短用户从商店点一下安装几秒钟就能用上。桌面应用要下载安装包、过安全软件、处理更新每一步都在流失用户。而且扩展天然跟浏览器上下文绑定能直接访问当前页面、标签页、书签、历史记录这些能力在端侧AI场景里非常值钱。另一个优势是跨平台。同一套扩展代码在Windows、macOS、Linux、ChromeOS上都能跑底层推理后端由浏览器统一抽象。你不需要为每个平台单独编译模型运行时WebGPU和WASM帮你屏蔽了大部分差异。当然这个屏蔽是有代价的后面会详细讲。1.3 哪些场景适合端侧哪些不适合不是所有AI功能都适合塞进扩展里。我总结了一个简单的判断标准场景特征适合端侧适合云端模型参数量小于1B量化后小于500MB大于1B延迟要求小于1秒可接受2秒以上数据敏感度高不能出端低可脱敏调用频率高频每次交互都用低频偶尔触发任务复杂度分类、摘要、翻译、OCR复杂推理、长文本生成举个具体例子。划词翻译这个功能用端侧跑一个量化后的翻译模型虽然质量比大模型差一点但胜在即时、免费、离线可用。而如果是让AI帮你分析一份50页的PDF并生成报告这种任务端侧跑不动还是得走云端。2. Manifest V3给端侧推理套上的三道枷锁2.1 Service Worker的短命特性与模型加载的冲突Manifest V3最大的变化是用Service Worker替代了原来的后台页面。Service Worker是个事件驱动的环境没有DOM而且会在空闲时被浏览器回收。官方文档说空闲30秒后可能被终止实际测试下来不同浏览器、不同负载下这个时间从十几秒到几分钟不等。这对端侧推理是致命的。你想想加载一个几百MB的ONNX模型从磁盘读取、解压、初始化推理会话这个过程本身就要好几秒。如果Service Worker在模型加载到一半的时候被回收了下次事件来了又得从头来。更麻烦的是WebGPU的device上下文在Service Worker重启后会丢失所有GPU资源都要重新申请。我最初的方案是把模型加载放在Service Worker的全局作用域里用一个Promise缓存。结果发现只要用户超过半分钟没操作Service Worker一挂缓存全没了。后来改成用chrome.storage存模型文件的ArrayBuffer每次Service Worker启动时重新创建推理会话。这个方案能跑但每次冷启动都要重新初始化首次推理延迟很难看。2.2 CSP策略对WASM和WebGPU的加载限制Manifest V3对扩展页面的内容安全策略做了严格限制。默认情况下扩展的CSP是script-src self; object-src self这意味着你不能从远程加载任何脚本包括WASM文件。ONNX Runtime Web的WASM后端需要加载一个.wasm文件如果你把这个文件放在扩展包里用相对路径引用是可以的。但如果你图省事想从CDN加载直接就被CSP拦了。WebGPU的情况稍微好一点它不需要加载外部脚本但需要确保扩展的manifest里声明了正确的权限。另外在Service Worker里使用WebGPU需要在manifest的background字段里指定type为module否则import语句会报错。还有一个容易忽略的点如果你用了WebAssembly的SharedArrayBuffer来做多线程推理需要设置跨域隔离头。扩展页面默认是不满足跨域隔离条件的需要在manifest里配置cross_origin_embedder_policy和cross_origin_opener_policy。这两个配置在MV3里是通过manifest的content_security_policy字段间接控制的写起来比较绕。2.3 扩展包体积与模型分发的矛盾Chrome Web Store对扩展包体积有硬性限制单个包不能超过2GB但实际上传超过100MB审核就会变慢用户安装时也会犹豫。而一个可用的端侧模型量化后通常也在几十MB到几百MB之间。这就产生了一个矛盾模型太大包体积超标模型太小效果不行。我的做法是把模型拆成两部分一个基础的小模型放在扩展包里保证安装后核心功能可用一个增强的大模型放在远程用户首次使用时按需下载存到IndexedDB里。这样既控制了初始包体积又给了用户选择权。但这里有个坑从远程下载模型文件MV3的CSP允许吗答案是允许的因为模型文件不是脚本是二进制数据。你可以用fetch下载ArrayBuffer然后存到IndexedDB。但要注意下载的域名需要在manifest的host_permissions里声明否则fetch会被拦截。3. 推理后端的选型WebGPU、WASM还是WebNN3.1 三种后端的实测性能对比ONNX Runtime Web支持多种执行后端最常用的是WASM和WebGPU。WebNN是新兴的标准目前支持度还很低。我在同一台机器上M1 MacBook ProChrome 120跑了一个量化后的MiniLM模型输入长度128对比结果如下后端首次推理耗时稳定后单次推理内存占用兼容性WASM (单线程)800ms120ms180MB全平台WASM (多线程)600ms45ms220MB需跨域隔离WebGPU1500ms18ms350MBChrome/Edge 113WebNN未跑通--实验性这个数据很说明问题。WebGPU的首次推理最慢因为要编译shader、申请GPU资源但一旦跑起来单次推理速度是WASM的6倍以上。所以如果你的场景是高频调用WebGPU是唯一选择如果只是偶尔用一下WASM的多线程版本反而更划算因为启动快、内存小。3.2 WebGPU在扩展里的初始化陷阱WebGPU在普通网页里用起来很简单navigator.gpu.requestAdapter()然后requestDevice()就完事了。但在扩展的Service Worker里这套流程有几个坑。第一个坑是adapter的获取可能返回null。在Service Worker环境下某些浏览器对GPU访问有限制requestAdapter可能直接返回null。这时候你需要fallback到WASM后端。我的做法是写一个探测函数在Service Worker启动时先试WebGPU失败就标记为WASM模式。第二个坑是device lost的处理。WebGPU的device可能会因为驱动更新、系统休眠等原因丢失。一旦丢失所有已创建的buffer和pipeline都失效。在扩展里这个问题更严重因为Service Worker本身就可能被回收device lost和worker重启叠加在一起排查起来很痛苦。我的方案是监听device.lost事件一旦触发就重建整个推理会话同时给用户一个正在重新初始化的提示。第三个坑是shader编译的耗时。WebGPU的推理会话初始化时ONNX Runtime会把模型的计算图编译成WGSL shader。这个过程在首次运行时可能耗时一两秒如果放在Service Worker里同步执行会阻塞其他事件处理。我后来改成在offscreen document里做初始化Service Worker只负责转发消息这样不会阻塞主线程。3.3 WASM多线程的跨域隔离配置WASM多线程依赖SharedArrayBuffer而SharedArrayBuffer要求页面处于跨域隔离状态。在扩展里配置这个需要在manifest.json里加两个字段{ cross_origin_embedder_policy: { value: require-corp }, cross_origin_opener_policy: { value: same-origin } }加了这两个之后扩展页面就满足跨域隔离条件了SharedArrayBuffer可以正常使用。但要注意这会影响扩展内所有资源的加载策略如果扩展里有引用外部图片或字体可能会被COEP拦截。解决办法是给这些资源加上Cross-Origin-Resource-Policy头或者干脆把资源打包进扩展。另外WASM多线程的线程数不是越多越好。ONNX Runtime Web默认会用navigator.hardwareConcurrency作为线程数但在扩展环境里这个值可能不准。我实测下来4到8个线程是比较合理的区间再多的话线程调度开销会抵消并行收益。4. 模型工程从训练产物到扩展可用的资产4.1 量化策略的选择与精度损失评估端侧模型的第一个工程决策就是量化。FP32的模型太大FP16在WebGPU上支持还行但在WASM上没优势INT8是性价比最高的选择。ONNX Runtime提供了动态量化和静态量化两种方式。动态量化不需要校准数据集直接对权重做INT8量化激活值在推理时动态计算scale。这种方式简单但精度损失相对大一些。静态量化需要一批校准数据提前算好激活值的scale精度更好但流程麻烦。我的经验是对于Transformer类模型动态量化后精度损失通常在1%到3%之间具体取决于模型和任务。如果任务对精度敏感比如涉及数值计算建议做静态量化或者对敏感层保持FP16。ONNX Runtime的量化工具支持混合精度可以把某些层排除在量化之外。还有一个细节量化后的模型在WebGPU上的表现和在WASM上不一样。WebGPU对INT8的支持是通过模拟实现的实际计算时可能转成FP16或FP32。所以如果你主要用WebGPUFP16量化可能是更好的选择模型体积比INT8大一点但省去了转换开销。4.2 模型分片加载与IndexedDB缓存策略前面提到大模型不适合直接打包进扩展。我的方案是把模型切成多个分片每个分片几MB用户首次使用时按需下载。分片的好处是可以并行下载而且如果某个分片下载失败只需要重试那一个。下载完成后模型数据存到IndexedDB。IndexedDB在扩展环境里是持久化的除非用户清除扩展数据否则不会丢。但IndexedDB的读写速度比内存慢很多所以每次Service Worker启动时需要把模型从IndexedDB读到内存里再创建推理会话。这个读取过程对于几百MB的模型来说可能要一两秒。为了优化这个体验我做了一个预热机制在用户安装扩展后后台静默下载模型并存入IndexedDB。等用户第一次使用功能时直接从IndexedDB读省去了下载时间。另外如果模型不大小于50MB可以考虑存在chrome.storage.local里读取速度比IndexedDB快但有容量限制。4.3 模型版本管理与增量更新模型不是一成不变的你可能需要更新模型来修复bug或提升效果。如果每次更新都让用户重新下载整个模型体验很差。我的做法是给模型文件加版本号更新时只下载变化的文件。具体实现上我把模型拆成配置文件描述模型结构、输入输出、预处理参数和权重文件。配置文件很小每次更新都重新下载权重文件按层或按块分片用哈希值做版本比对只下载变化的片。这样一次小更新可能只需要下载几MB而不是几百MB。版本管理还有一个坑如果用户正在使用旧版本模型后台悄悄更新了模型文件可能会导致推理结果不一致。我的方案是双缓冲新模型下载到临时目录等当前推理会话结束后再切换。切换时给用户一个提示避免困惑。5. 扩展架构设计Service Worker、Offscreen与内容脚本的协作5.1 为什么推理要放在Offscreen DocumentService Worker里跑推理有两个问题一是生命周期短二是没有DOM某些库可能依赖DOM API。Offscreen Document是MV3引入的一个隐藏页面生命周期跟扩展绑定不会因为空闲被回收而且有完整的DOM环境。我的架构是Service Worker负责事件分发和状态管理Offscreen Document负责模型加载和推理执行内容脚本负责页面交互和数据采集。三者之间通过chrome.runtime.sendMessage通信。这个架构的好处是职责清晰。Service Worker被回收了没关系Offscreen Document还在模型不用重新加载。Offscreen Document里可以用完整的Web API包括WebGPU、WebAssembly、IndexedDB不受Service Worker的限制。但Offscreen Document也有代价。它本质上是一个隐藏的网页会占用内存。如果模型很大Offscreen Document的内存占用可能达到几百MB。对于内存紧张的设备需要做降级处理比如在低内存设备上只用WASM单线程或者干脆走云端。5.2 消息传递的序列化开销与优化Service Worker、Offscreen Document、内容脚本之间的通信底层是结构化克隆。如果你传递的是大对象比如图片的ImageData或者模型的中间结果序列化和反序列化的开销不可忽略。我实测过传递一个1MB的ArrayBuffer序列化加传输加反序列化大概要5到10毫秒。如果推理结果本身就是几MB的向量这个开销会累积。优化方案有几个一是用Transferable Objects把ArrayBuffer的所有权直接转移避免拷贝二是把大结果存到IndexedDB只传一个引用ID三是用MessageChannel建立专用通道减少消息路由开销。Transferable Objects在扩展的sendMessage里支持有限不是所有浏览器都实现了。我目前用的是IndexedDB方案推理结果先存到IndexedDB然后发一个ID给内容脚本内容脚本再根据ID去读。这样虽然多了一次读写但避免了消息通道的阻塞。5.3 推理任务的队列管理与优先级调度用户可能同时触发多个推理任务比如一边划词翻译一边做页面摘要。如果这些任务都往Offscreen Document里塞会互相争抢GPU资源导致所有任务都变慢。我的做法是在Service Worker里维护一个任务队列按优先级排序。交互式任务比如划词翻译优先级最高后台任务比如页面摘要优先级低。同一时刻只执行一个推理任务其他的排队。如果队列太长直接拒绝低优先级任务给用户一个提示。队列管理还有一个细节任务超时。如果某个推理任务卡住了比如模型加载失败或者GPU hang不能让队列一直堵着。我给每个任务设了超时时间交互式任务10秒后台任务30秒超时就取消并释放资源。6. 性能调优与踩坑实录6.1 首次推理延迟的拆解与优化首次推理延迟是端侧AI体验的最大杀手。我把这个延迟拆成几部分模型加载从磁盘或IndexedDB读、会话创建ONNX Runtime初始化、shader编译WebGPU、预热推理。模型加载这块如果用IndexedDB读取速度大概在100MB/s左右一个200MB的模型要2秒。优化方法是把模型文件用gzip压缩存储读取时解压虽然多了CPU开销但IO时间减少总体更快。另外可以用Streams API边读边解压减少内存峰值。会话创建和shader编译是WebGPU特有的开销大概1到2秒。这部分很难完全消除但可以提前做。我的方案是在Offscreen Document创建后立即开始初始化不等用户触发。这样等用户真正用时模型已经准备好了。预热推理是指用一个小输入跑一次推理触发所有懒加载的资源和shader编译。这一步能把后续推理的延迟降低30%以上。预热可以在初始化完成后立即做用户无感知。6.2 内存泄漏的常见来源与排查方法端侧推理是内存大户稍不注意就泄漏。我遇到过的泄漏来源有几个一是ONNX Runtime的session没有正确释放。每次创建InferenceSession都会分配GPU和CPU内存如果旧的session不释放内存会持续增长。解决方法是显式调用session.release()并且在创建新session前确保旧session已经释放。二是WebGPU的buffer和texture没有销毁。WebGPU的资源需要手动destroy否则即使JavaScript对象被回收GPU内存也不会释放。我写了一个资源管理器统一跟踪所有创建的GPU资源在会话结束时批量销毁。三是事件监听器没有移除。在Offscreen Document里如果给window或document加了监听器页面关闭时不会自动移除。虽然Offscreen Document生命周期跟扩展绑定但频繁创建销毁会导致监听器累积。排查内存泄漏Chrome DevTools的Memory面板是主要工具。可以拍堆快照对比不同时间点的对象数量。对于GPU内存可以用chrome://gpu页面查看或者用WebGPU的API查询。6.3 不同浏览器下的兼容性差异Chrome和Edge对WebGPU的支持最好版本113以上就默认开启。Firefox从版本141开始支持WebGPU但在扩展环境下的表现还不稳定我测试时遇到过device创建失败的情况。Safari从版本18开始支持WebGPU但只限于macOS Sonoma以上而且扩展环境下的支持更晚。WASM的兼容性最好所有现代浏览器都支持。但WASM多线程需要跨域隔离Safari对跨域隔离的支持比较晚而且配置方式跟Chrome不一样。我的兼容性策略是优先尝试WebGPU失败则降级到WASM多线程再失败降级到WASM单线程。降级过程对用户透明但会在设置页面显示当前使用的后端方便排查问题。还有一个坑是模型格式的兼容性。ONNX Runtime Web在不同浏览器上对算子支持不一样某些算子在WebGPU上支持但在WASM上不支持反之亦然。我建议在模型导出时做一次算子兼容性检查把不支持的算子替换掉或者用自定义实现。7. 从开发到上架的工程化实践7.1 本地开发调试的完整工作流扩展的开发调试比普通网页麻烦因为涉及多个上下文。我的工作流是这样的首先用Vite或者Webpack做构建把TypeScript编译成JavaScript把模型文件复制到dist目录。开发模式下开启source map方便调试。然后在Chrome里加载未打包的扩展打开Service Worker的DevTools、Offscreen Document的DevTools、内容脚本的DevTools。这三个DevTools是独立的需要分别打开。我习惯把三个窗口并排方便观察消息传递。调试推理性能时用Chrome的Performance面板录制可以看到WebGPU的kernel执行时间。如果WASM后端可以用console.time手动打点。还有一个技巧在Offscreen Document里暴露一个全局对象把推理会话、模型、缓存都挂上去方便在DevTools里直接查看和操作。这个对象只在开发模式下暴露生产环境要移除。7.2 模型文件的打包与按需加载配置打包配置的核心是把模型文件排除在主包之外作为独立资源。如果用Vite可以把模型放在public目录构建时自动复制到dist。然后在manifest的web_accessible_resources里声明这些文件让Offscreen Document可以访问。按需加载的配置需要指定模型的远程地址和本地缓存策略。我一般把模型放在自己的CDN上配置好CORS头然后在扩展里用fetch下载。下载时显示进度条让用户知道在干什么。如果模型文件很大可以考虑用Range请求分片下载。这样即使网络中断也能从断点续传。但Range请求需要服务器支持配置起来稍微麻烦。7.3 商店审核中容易卡住的几个点Chrome Web Store的审核对权限很敏感。如果你的扩展申请了host_permissions审核员会仔细看你要这些权限干什么。端侧AI扩展通常需要访问所有网站的权限因为用户可能在任意页面触发功能。这个权限申请的理由要写清楚最好在隐私政策里说明数据不出端。另一个容易卡住的是远程代码。MV3明确禁止执行远程代码包括eval和new Function。ONNX Runtime Web的某些版本可能内部用了eval需要确认清楚。如果用了WASMWASM是允许的但WASM文件必须打包在扩展里不能从远程加载。还有一点是模型文件的版权。如果你用的模型是开源的要在扩展的描述里注明来源和许可证。如果是自己训练的要确保训练数据没有版权问题。8. 几个真实场景的落地案例拆解8.1 划词翻译低延迟要求的极致优化划词翻译对延迟极其敏感用户期望是点完就出结果。我的优化方案是模型用最小的量化版本小于20MB后端优先WebGPU预热推理在扩展启动时就做。输入文本先做长度截断超过50个字符的直接走云端因为端侧模型处理长文本会慢。实测下来从用户松开鼠标到翻译结果出现平均延迟在300毫秒左右其中推理本身只占50毫秒剩下的是消息传递和渲染。这个体验已经接近原生应用了。8.2 页面摘要长文本的分块与流式输出页面摘要的输入是整篇网页正文可能几千字。端侧模型的处理长度有限需要分块。我的做法是按段落切分每块不超过模型的最大输入长度然后逐块推理最后合并摘要。流式输出是个提升体验的好办法。虽然端侧推理是一次性出结果但可以在推理完成后把结果按句子逐步渲染到页面上模拟流式效果。用户看到文字一个个蹦出来感知延迟会低很多。8.3 图片OCRWebGPU的纹理上传优化图片OCR的瓶颈在图片预处理。一张1080p的图片从ImageData转成模型需要的张量格式涉及大量的数据搬运。用WebGPU的话可以把图片直接上传为GPUTexture在GPU上做resize和归一化避免CPU和GPU之间的数据往返。这个优化做下来预处理时间从200毫秒降到了20毫秒。但要注意WebGPU的纹理格式和模型期望的输入格式可能不一致需要写shader做转换。这部分代码比较底层调试起来要有耐心。9. 端侧推理在扩展里的边界与未来9.1 当前方案的性能天花板在哪里以目前的技术条件端侧推理在扩展里的性能天花板大概是模型参数量1B以内量化后500MB以内单次推理延迟100毫秒以内WebGPU内存占用1GB以内。超过这个范围要么体验崩坏要么设备扛不住。这个天花板不是固定的随着WebGPU的成熟和硬件的发展会逐步抬高。但短期内端侧推理还是适合做轻量级任务重任务交给云端。9.2 模型小型化与推理加速的演进方向模型小型化是端侧AI的核心驱动力。从BERT到DistilBERT到TinyBERT再到现在的各种1B以下的小模型效果越来越好体积越来越小。量化技术也在进步从INT8到INT4甚至二值化网络都在探索中。推理加速方面WebGPU的shader优化空间还很大。ONNX Runtime Web的WebGPU后端还在快速迭代每次版本更新都有性能提升。另外WebNN标准如果落地会提供更底层的硬件加速接口性能可能比WebGPU更好。9.3 什么情况下应该果断放弃端侧方案端侧不是万能的。如果遇到以下情况我会果断放弃端侧模型超过1B参数、任务需要多轮复杂推理、设备内存小于4GB、用户对精度要求极高。这些情况下云端方案虽然成本高但体验有保障。还有一个现实问题端侧推理的调试和维护成本很高。不同浏览器、不同设备、不同模型版本组合起来是个巨大的测试矩阵。如果团队没有足够的工程资源建议先从云端做起等产品验证了再考虑端侧。我在实际项目里的体会是端侧推理在扩展里的价值不在于替代云端而在于补充云端。把高频、轻量、敏感的任务放在端侧把低频、重量、非敏感的任务放在云端两者配合才能做出体验和成本都说得过去的产品。这个平衡点需要根据具体场景反复调试没有一刀切的答案。