浏览器扩展端侧AI推理实战：架构设计与工程落地

做浏览器扩展里的端侧 AI 推理和做服务端推理完全是两个物种。服务器场景里你能随便开几百兆内存、默认 GPU 随便用但进了扩展环境你面对的是 Service Worker 的休眠机制、标签页之间互相挤占资源、以及用户随时可能关掉页面跑路的事实。我最近把一个“页面内容理解 摘要生成”的完整推理链路塞进了一个扩展模型跑在本机浏览器里从捕获页面内容到推理结果渲染除了首次加载模型的等待之外后续调用基本都在秒级以内完成全程没有上传任何用户数据。这篇文章我会把从架构设计到工程落地的完整思路、参数权衡和我实际踩过的坑都摊开写适合想在扩展里加端侧 AI 能力、或者正在被“扩展一重新加载模型就被清掉”这种问题折磨的人。1. 整体架构设计把浏览器扩展当成微型分布式系统来拆1.1 先分清四个角色的职责再谈其他很多人写扩展里的 AI 功能时习惯把所有代码一股脑塞进background.js监听消息、加载模型、跑推理、回传结果甚至更新 UI 也放那里。数据量小的时候能用一旦模型体积上去、并发请求变多基本必然翻车。原因很简单扩展的各个部分在浏览器里是被隔离的权限、生命周期、执行环境都不一样硬要把它们揉成一个整体等于自己给自己下套。我习惯把扩展拆成四个角色Popup / 页面 UI负责用户交互展示状态和结果。它的生命周期随用户点击而存在用户一关 Popup里面的状态就全没了所以绝对不能作为数据或模型的所有者。Content Script负责跟具体页面接触读取 DOM、捕获页面选择内容、截取可见区域图像。它跟页面共享 DOM但同时又是一个隔离环境不合适做重计算。Background / Service Worker整个扩展的调度中心负责消息路由、状态汇总和任务分发。它不会长期驻留但所有模块之间要通信都得经过它来统一协调。Inference Worker真正跑模型和推理的地方。用 Web Worker 隔离避免长时间推理阻塞 UI 线程模型加载、推理 session、预处理资源都放这里。这四个角色的关系很像分布式交换机架构里的“控制面 / 数据面”分离逻辑。Service Worker 是控制面只负责指挥Inference Worker 是数据面只负责把推理任务跑完Content Script 相当于各个端口的接入层负责把外部信号采集进来。把控制面和数据面混在一起后续想优化并发或者提高内存利用率都会变得很难。1.2 消息流转与调度逻辑一次典型推理请求会这样走用户在页面里点了“分析这个区域”Content Script 采集 DOM 信息和截图数据。Content Script 把数据通过chrome.runtime.sendMessage打包发给 Service Worker。Service Worker 收到请求后把任务塞进一个请求队列并转发给 Inference Worker。Inference Worker 调用端侧推理引擎完成模型推理把结果回传给 Service Worker。Service Worker 再把结果返回给 Content Script由 Content Script 在页面里渲染。这套链路里最容易被忽略的是“队列”。很多人直接做同步转发消息一到就塞给推理引擎结果多个标签页同时触发任务时推理引擎内部还在处理上一个任务新的请求就排不上队最后要么超时要么直接丢消息。所以我在 Service Worker 里维护一个带优先级的任务队列比如用户手动触发的任务优先级高于页面自动检测产生的任务同一标签页的请求尽量合并处理。实现这个队列本身不复杂但它决定了突发请求下整个扩展还能不能有条理地工作。2. 动手之前先做“体检”能力探测与运行时选型2.1 设备能力探测清单做服务端推理时你通过查机器配置文档就能知道有多少 CPU、多少显存。端侧推理完全不一样用户的设备差异可能比服务器集群还大而且你没法预知目标设备跑在什么浏览器、什么操作系统上。要解决这个问题第一步不是写推理代码而是给用户设备做一次“体检”。这就好比在 Ubuntu 上准备部署环境先敲一句uname -m看系统架构再用lscpu看核心数和指令集几分钟就能确定目标平台特性。浏览器端没有 lscpu 这个命令但有对等的“体检 API”我会在扩展启动时统一探测一次。我在项目里实际用的探测清单长这样// capabilities.ts function detectCapabilities() { const webgpuSupported !!globalThis.navigator?.gpu; const wasmSupported typeof WebAssembly ! undefined; const cores navigator.hardwareConcurrency ?? 4; const deviceMemory (globalThis.navigator as any).deviceMemory ?? 4; // 单位 GB const isMobile /Android|iPhone|iPad/.test(navigator.userAgent); return { webgpuSupported, wasmSupported, cores, deviceMemory, isMobile, }; }这里有两个容易踩的细节。第一deviceMemory只有 Chromium 系浏览器会返回其他浏览器可能没有这个字段所以必须给默认值而且可以保守一点比如给 4GB。第二能力探测不等于真实可用后面真正调用navigator.gpu.requestAdapter()依旧可能失败比如驱动被禁用、隐私模式、或者浏览器版本有兼容问题。所以“探测”只用于初步决定候选策略真正选择哪个运行时还要在初始化时做一次真实尝试。2.2 推理后端选型与回退策略端侧推理引擎到了浏览器里现实就是没有银弹。常见后端主要就这几类WebAssembly SIMD 多线程兼容性最好哪儿都能跑。速度受限于 CPU但对中小模型比如几十 MB 的视觉模型或文本分类模型体验完全够用。通过 SharedArrayBuffer 可以把多核用起来。WebGPU能调用 GPU 加速推理速度比 WASM 快上一个档次尤其适合图像和 Transformer 这类计算密集的模型。但 WebGPU 在不同浏览器之间的适配进度差异很大同一台设备换个浏览器可能直接从“可用”变成“不可用”。WebGL历史遗留方案能跑但精度和兼容性处理成本高除非维护旧项目否则新代码不推荐直接选它作为主力。我的策略是默认首选 WebGPU初始化失败自动回退到 WASM 多线程再失败回退到单线程 WASM。整个过程在扩展的 warm-up 阶段完成不要让用户在一个失败窗口里干等。选型时我建议别自己直接调底层 API尽量还是在 ONNX Runtime Web 或 Transformers.js 这一层做后端切换。它们把 WebGPU、WASM、CPU 后端的切换封装得比较完善自己造轮子的收益不大。尤其是 Transformers.js 做文本类任务的 API 很顺手模型预下载、tokenizer 处理、pipeline 输出都帮你解决了。2.3 模型大小与内存预算端侧推理最大的敌人往往不是算力是内存。浏览器扩展的内存配额虽然不像手机端那么死板但你让一个扩展常驻 500MB 内存用户迟早会因为卡顿把你卸载。所以动手前先算一笔账。模型参数的基本计算方式是参数量 × 每个参数字节数 ≈ 模型文件大小。如果我用 B 表示十亿参数的数量一个 1.4B 的模型用 fp32 存储是 4 字节每参数就是大约 5.6GB量化到 int8 是 1 字节每参数变成 1.4GB量化到 int4 大约是 0.7GB。这还只是参数本身没算推理时的中间激活值、KV Cache、预处理临时缓冲区。在实际浏览器端侧1B 以上的模型能跑起来已经很不容易内存很容易翻一倍以上。所以我建议分档管理。扩展首次安装时先用能力探测结果给用户一个“预期档位”内存 8GB 以上且 WebGPU 可用的设备可以跑 3B 以下的小型模型量化到 int8 或 int4普通设备只跑几十 MB 到几百 MB 的专用小模型比如 OCR、文本分类、向量嵌入这些离散任务内存紧张的设备就只开 CPU 单线程推理甚至允许用户关掉自动分析功能。档位信息存进chrome.storage.local之后推理调度直接按档位决定这只设备最多能加载多大的模型避免用户设备被直接跑爆。3. 工程实现规范模块边界、生命周期和协议设计3.1 别和 Service Worker 的休眠机制对抗用过 Manifest V3 的人应该都吃过这个教训后台 Service Worker 空闲几十秒就会被浏览器杀掉。以前 MV2 的常驻后台页可以长期挂在一个页面里跑任务现在不行了。如果你把加载模型、跑推理这个流程整个放在 Service Worker 里很可能推理还没跑完Worker 就被休眠了整个流程就断了。几种思路可以绕开这个问题。轻量任务直接在推理 Worker 里完成Service Worker 只做任务转发和状态记录如果你有持续的、较重的任务比如视频帧流式分析就需要引入 Offscreen Document 这类“常驻后台页”的方案。它本质上是一个隐藏页面能绕过 Service Worker 的休眠限制但需要用户手势触发并且在 Manifest 里配置权限。工程上的核心原则是把 Service Worker 当成调度器用不要放任何重量级状态。模型实例只能保存在 Inference Worker 里因为 Worker 有独立的完整生命周期不会因为 Service Worker 销毁就被回收。Service Worker 被休眠之后再次唤醒它只负责重新找到对应的 Worker 并恢复连接状态都在 Worker 端这样就能避免“扩展每次重载之后模型就要重新下载”的尴尬场景。3.2 消息协议设计一次性消息还是长连接一次性消息chrome.runtime.sendMessage用起来最简单但它有个天然局限没法主动推送中间状态也没法做增量结果。端侧推理这个场景里模型加载可能要十几秒推理可能要几秒界面总需要“排队中”“正在推理”“已完成”这类状态反馈。如果只用一次性消息去模拟这种过程只能靠定时轮询体验差且逻辑乱。所以我更推荐用runtime.Port建立长连接。请求方发一个“启动推理”的事件Worker 把状态分阶段推回来界面上可以画进度条也支持取消操作。消息结构本身要统一我在项目里用类似这样的字段interface InferenceRequest { requestId: string; type: ocr | summarize | embedding; source: { tabId: number; url?: string }; payload: any; // 具体业务数据 }一条消息必须带上唯一requestId这是整个异步错误排查的基础。服务端返回结果时也带requestId前端无论什么时候收到响应都能知道是哪一次请求的没有 requestId 时多个并发请求的返回结果无法区分页面上的结果互相覆盖排查起来让人崩溃。这个细节看着小实际项目里遇到一次就再也忘不掉了。3.3 并发控制和回压端侧推理引擎通常不是为“无限并发”设计的。多个请求同时进来如果全部直接塞给模型内存会瞬间涨起来推理时间也会明显变长。我在 Service Worker 里做了两层并发控制第一层按任务类型分流OCR、摘要、嵌入各自维护队列互不干扰第二层每个队列内部最多并发 1 个推理任务其他请求排队。单并发设计看起来很保守但对端侧推理来说收益反而最明显。浏览器里的推理任务一般很短几十到几百毫秒单个队列顺序执行用户几乎感觉不到排队延迟。更重要的是单并发能让推理 Worker 复用同一个 session避免反复创建和销毁带来的高昂初始化开销。如果某个模型确实很慢再考虑单独开 worker 池那是后话没必要在一开始就过度设计。回压处理同样要想清楚。队列无限堆积用户等不到结果时会觉得扩展卡死。所以队列长度超过一定阈值后新请求直接拒掉或者做合并。比如 OCR 任务排队超过 5 个就丢弃最老的帧只保留最新一帧。这类策略用一个简单函数就能实现但在实际体验里的价值远超想象。3.4 用可转移对象和 SharedArrayBuffer 管理内存端侧推理的性能瓶颈很多时候不在模型本身而在数据拷贝。比如页面截图是一张 ImageDataByte 量级可能在好几兆如果用普通消息传给 Worker默认会做结构化克隆内存拷贝一次图像再处理一次开销一下子就上去了。更合理的做法是使用 Transferable 对象的transfer参数把 ArrayBuffer 的所有权直接转移给 Worker实现零拷贝。worker.postMessage( { requestId, imageBuffer: imageArrayBuffer }, [imageArrayBuffer] // 转移所有权 );SharedArrayBuffer 在扩展环境里用起来限制比较多需要跨源隔离条件Manifest V3 的跨域策略和 CSP 都可能拦它。我的建议是如果目标用户主要在 Chromium 系浏览器可以先查扩展的 CSP 配置能不能支持不能支持就用 Transferable 方案也足够解决大部分性能问题别强行上共享内存。4. 推理核心模块的关键实现4.1 引擎接入Transformers.js 与 ONNX Runtime 的初始化我现在的项目里文本类模型用 Transformers.js视觉类模型走 ONNX Runtime Web。两个都有各自的 pipeline API接入方式很接近。以文本摘要为例// inference-worker.ts import { pipeline } from xenova/transformers; let summarizer; async function init() { summarizer await pipeline(summarization, Xenova/distilbart-cnn-6-6); // 预热跑一次空输入让模型填充缓存 await summarizer(warmup, { max_length: 50 }); }这段代码背后有几个工程细节需要注意第一模型名要精确到repo/model-nameTransformers.js 默认从 Hugging Face 拉权重你需要在扩展的host_permissions或 CSP 里放行对应域名否则下载请求会直接失败。第二首次加载很慢但我不建议让用户感知到完整的下载等待。可以在扩展安装后利用chrome.alarms或 Offscreen Document 在后台静默预下载一次模型这样用户真正使用的时候模型可能已经在本地缓存里了。第三pipeline返回的是同一个 session后续请求要复用同一个实例不要每次推理都重新创建。4.2 前处理和后处理的取舍端侧推理的前处理藏着大量性能坑最典型的就是图像缩放。页面截图像素普遍在 1920×1080直接塞给模型既占内存又慢合理的做法是在 Content Script 里先缩放到模型输入尺寸而且把缩放放在 Canvas 或 WebGPU 的纹理通道里完成不要先取到 CPU 像素数组再缩放那样会产生一次不必要的内存拷贝。文本任务的后处理也经常被忽略。模型解码出来的 token 列表如果直接展示用户看到的是一段没有标点、没有分段的原始序列。所以我在 Worker 里做后处理把推理结果变成结构化的 JSON摘要文本、关键短语、置信度、耗时。UI 层只负责渲染 JSON不负责解析模型输出。这样业务层和推理层之间就有一层稳定边界后续换模型只需要改 Worker 内部实现UI 层完全不用动。4.3 推理 session 的缓存与预热模型推理最贵的时间基本花在首次加载和首次推理上。首次加载要下载权重、初始化 session首次推理要暖缓存、触发编译优化。这个问题不处理用户在第一次使用时会等十几秒甚至几十秒体验直接劝退。我的方案是两步安装后预下载 预热推理。预下载把“网络下载”的等待时间转移到“安装后静默阶段”真正使用时的模型加载会直接读本地缓存快很多。预热推理则是把初始化的编译开销提前跑掉让第一个用户可见请求直接走已经热好的 pipeline。实测下来不预热时首次推理可能需要 2 到 3 秒预热之后由于缓存的优化路径已就位实际首推时间能降到几百毫秒以内体感差距非常明显。4.4 模型的版本管理与分发如果你把模型作为扩展资源打包扩展一更新模型就得重新分发安装包体积会直接失控。如果你在用户端动态下载就要处理“模型版本更新”这件事否则用户可能长期用旧版本。我采用的办法是在扩展里放一个models.config.json记录每个模型的目标 URL 和版本号。扩展启动时先读配置文件和本地缓存版本对比不一致才重新下载。用户端缓存放在IndexedDB不要放在chrome.storage因为chrome.storage的单条存储有大小限制模型权重动辄几十 MB 根本放不进去。缓存文件要按文件名分区保存下载中断要支持续传。这一套逻辑其实跟下载类扩展的任务调度很像比如你在常见下载管理器的浏览器扩展里看到的任务队列、断点续传、完整性校验模型分发本质上就是一个受限版本的下载系统完全可以借鉴这类成熟方案的思路。5. 常见问题与排查速查表这一节我把实际开发中反复遇到的典型问题整理成一个速查表后面再挑三个印象最深的细节展开讲。症状可能根因排查顺序推理请求发出后没有返回十几秒后超时Service Worker 休眠或消息丢失查 Service Worker 日志确认是否收到请求查请求队列是否堆积扩展页面变卡内存涨到 300MB 以上推理 session 重复创建或模型量化精度不到位打开任务管理器看扩展进程内存检查 worker 是否每次请求都重建 session首次推理特别慢每次都要再等一遍预热未执行或模型缓存未命中检查首次加载日志确认预下载流程是否完整WebGPU 设备提示requestAdapter failedadapter 探测失败驱动或浏览器兼容问题单独调用navigator.gpu.requestAdapter()查浏览器版本页面截图数据传不到 WorkerImageData 被结构化克隆内存翻倍尝试转成 ArrayBuffer 并transfer确认 CSP 是否允许扩展在部分浏览器上直接白屏代码直接用navigator.gpu未做保护给能力探测加默认值回退方案必须有兜底Service Worker 休眠导致的丢请求。这个坑非常隐蔽。我在扩展里挂了一个定时任务想每两分钟触发一次自动摘要结果经常没反应。排查半天才发现 Service Worker 空闲时间一长就被杀掉定时任务触发时 Worker 还在“唤醒”过程中消息发出去没有人接收。解决办法是把这类周期性任务放到 Offscreen Document 或独立 Worker 中Service Worker 只做消息桥接。WebGPU 适配性崩溃。用户反馈扩展在 Chrome 上能跑但在某些浏览器上一点就崩。排查后发现是navigator.gpu.requestAdapter()返回了 null而我没处理这个情况后续创建 buffer 的地方全都抛异常。修复很简单返回 null 时直接走 WASM 回退而且回退要在初始能力探测阶段就准备好不要等到崩溃之后再补救。CSP 导致的模型加载失败。扩展的 CSP 默认很严格从外部域名加载模型文件容易被拦截。如果模型权重域名不在host_permissions允许列表里或者没配置正确的 connect-src加载请求会被静默失败。排查这类问题时不要只看网络面板还要看控制台里的 CSP 报错。前置把允许域名写在配置里比事后到处加白名单省事得多。6. 从浏览器扩展到更大的端侧推理版图写了这么多我想把一句话说透浏览器扩展里的端侧推理真的不是被压缩的云服务它更接近嵌入式系统里的推理约束。比如你在 STM32 这类 MCU 上做端侧推理要考虑的是 FLASH 容量、RAM 上限、功耗和实时性到了浏览器扩展里约束换成了 Service Worker 生命周期、WASM 内存上限和 GPU 兼容性但思考方式是相通的——先约束能力边界再把任务拆成可调度的单元最后用回退策略兜住各种异常。这个思路不是某一种框架能教给你的它是把工程抠出细节之后沉淀下来的东西。我自己比较喜欢的一个验证方法是新扩展版本上线前先在低配设备上开“仿生模式”测试。把 CPU 核数调低、禁用 WebGPU、限制内存看系统在回退路径下是不是还能给出一个可用的最小功能。能用才上线不能就继续修。这个过程虽然花时间但每次都能发现几个平时想不到的边界问题。最后分享一个小做法把推理相关的所有日志打点集中在同一个地方记录请求 ID、耗时、内存变化和最终状态。哪怕是用户反馈扩展失灵拉一条日志按 requestId 一链就能定位到到底卡在采集、加载、推理还是 UI 渲染。别小看这个习惯后期排查的时间能省掉一大半。端侧 AI 推理系统也正因为有了这样的可观测性才真正变成一个可以被维护的工程系统而不是一个黑盒脚本。