浏览器扩展端侧AI推理工程化：从Service Worker到Offscreen Document

我去年年中接了个活儿：做一个浏览器扩展，用户划词时调用本地模型快速判断“这段话是不是广告软文”，是就标个记号，全程不出浏览器、不上传文本。听着不难，结果一上来我把 ONNX Runtime Web 塞进 Service Worker 打算直接跑推理，随即被 Chrome 教做人——Service Worker 在推理进行到一半时被回收，模型加载三次崩一次。后来我把整个架构推倒重来，才意识到一个核心问题：现代浏览器扩展环境下的端侧 AI 推理，从来不是“塞个模型进去”那么简单。它牵扯到扩展生命周期、推理引擎选型、跨上下文通信、内存控制、降级策略等一系列系统架构与工程实现规范问题。这篇文章就打算把这些约束、取舍、踩坑和经验一次性讲透，适合想在 Chrome/Edge 扩展里做本地摘要、翻译、敏感信息识别、图像分类、语音转文字等功能的开发者。

1. 扩展环境为什么不适合直接跑推理：四个真实约束

很多人第一次在扩展里跑端侧 AI，都是拿普通网页的思路套。普通页面里，<script>加载一个 Transformers.js 或者 ONNX Runtime Web，await一个pipeline()，然后推理，完事。扩展环境完全不是这样，至少有四个约束会直接影响你的架构设计。

1.1 Service Worker 生命周期：短命且会被随时回收

Manifest V3 之后，扩展的后台逻辑统一跑在 Service Worker 里。Chrome 对它的策略是“按需唤醒、空闲回收”：事件处理完大约 30 秒后，浏览器就有权把整个 Worker 杀掉，释放内存。如果你在 SW 里直接加载一个几百 MB 的模型，加载过程本身要花好几秒甚至十几秒，中间只要有一次事件没续住，整个进程就被回收，下次再进来又得重新加载。

而且扩展 Service Worker 里跑长任务，Chrome 的节流机制会介入。早期版本 5 秒不处理事件就可能被杀，现在虽然放宽到 30 秒，但模型推理一个样本可能就要几十秒（比如大一点的语音模型），你根本没有办法保证它能在 SW 内跑完。结论：Service Worker 不是跑推理的地方，它是管调度的地方。

1.2 上下文隔离：扩展不是“一个页面”

一个普通扩展同时存在好几种执行环境：popup 弹窗、content script 内容脚本、background service worker、option 页面，如果主动创建，还有 Offscreen Document（离屏文档）和 Web Worker。它们各有各的 DOM、各有各的全局对象，彼此之间只能用postMessage或chrome.runtime.sendMessage通信。

这意味着模型只能放在某一个上下文里，然后所有“想用 AI 的模块”都得通过消息跟它交互。你没法像普通网页那样一个import完事。上下文之间传数据还有序列化开销，Float32Array在某些情况下会被拷贝而不是转移，卡起来真要命（后面第 6 章详细说）。

1.3 CSP 和扩展权限限制

扩展默认的 Content Security Policy 很严格，eval、new Function这类动态执行基本被禁，远程代码也默认不允许。很多 AI 库在初始化时喜欢动态生成代码或加载远程 wasm 片段，在扩展里会被拦。另外，如果你用的是<webview>或者想跨域拉模型文件，都需要在host_permissions里显式声明，否则请求直接失败。

1.4 内存预算：扩展不是浏览器的主人

一个扩展的可用内存不是一个常量，但浏览器对扩展的预算远没有对普通页面那么大方。尤其是当你同时开着多个标签页、每个页面都注入 content script、每个 content script 又各自持有一份模型时，内存瞬间就爆了。端的本质是“用户设备本地跑”，但设备资源和浏览器资源都不是无限供应的。

所以在扩展里做端侧推理，第一件事不是选模型，而是先确认边界：模型放哪个上下文？谁负责加载？谁负责推理？谁负责卸载？谁负责报告失败？这些不先定好，后面每加一个功能都是在给自己埋雷。

2. 推理引擎与模型选型：先定路线再写代码

有了边界，下一步是选路线。我在这个项目里同时对比过几条主流方案，最后选了“ONNX Runtime Web 为主、WebGPU 优先、WASM 兜底”的组合。下面把这套选型逻辑拆开讲。

2.1 推理后端对比：WebGPU、WebNN、WASM 怎么选

端侧推理的底层执行主要看后端（backend）。我把它们放在一起测过一轮，结果如下：

如果你只面向 Chrome/Edge 用户，WebGPU 是性价比最高的。注意 WebGPU 有一个很恶心的特性：GPU 上下文可能因为驱动重置、系统内存压力、切换分辨率等原因丢失（context lost）。扩展里一旦发生，你的模型权重可能全部作废，必须重新初始化。所以架构上必须把“重新初始化”当成一等公民来支持。

2.2 运行时库：别直接裸调底层 API

• Transformers.js：封装度高，HuggingFace 生态的模型基本都能跑，适合快速验证。但封装度高也意味着你不太好精细控制生命周期，而且它默认从 HF Hub 拉权重，扩展离线场景要自定义env.localModelPath。
• ONNX Runtime Web：底层引擎，提供InferenceSession，可以精细管理模型加载、输入输出、后端切换。适合做生产级扩展，缺点是代码量大一些。
• WebLLM：主打 LLM 流式生成，走 WebGPU，适合做本地对话、文档问答，模型体积大，内存压力也大。
• MediaPipe Tasks：适合纯视觉或音频任务，和文本模型生态割裂。

我的选择逻辑很简单：如果你的任务是“模型需要灵活换、参数需要调”，直接用 ONNX Runtime Web 自己封装一层。如果你要快速出 Demo，先用 Transformers.js 验证准确率，再在公司里换成 ONNX Runtime Web 做工程化。不推荐先散兵游勇地用一堆库，最后每个库各自加载一份 runtime，内存直接翻倍。

2.3 模型格式与量化：q8 是一个甜点

模型格式优先选 ONNX。开源生态里很多模型已经转好了，如果没有，可以用optimum-cli或者onnxruntime工具链把 PyTorch 权重转成 ONNX。参数规模建议控制在 100M-500M 之间，扩展场景几乎不要想着跑 7B 级别的模型，加载时间和内存开销都不现实。

量化级别我做了几组实测：

q8 在内存和质量之间最平衡。我做广告识别时从 f16 切到 q8 之后，准确率只掉了约 0.3%，但内存从 620MB 降到 330MB，体感非常明显。

另一个细节：模型输出也要看是 Dense 还是 Sparse。分类任务输出一个向量，没问题；但如果是抽取式 QA、序列标注，输出尺寸和输入序列长度挂钩，你需要把模型设计成固定最大长度，比如max_seq_len=512，否则动态 shape 会让扩展的内存峰值不可控。

2.4 模型从哪来：本地打包还是远程拉取

扩展有一个很现实的问题：Chrome Web Store 对包体有要求，模型大了之后必须考虑远程获取。我的方案是“小模型随扩展包走，大模型远程按需下载”。

• 随包走：模型文件放在models/目录，用chrome.runtime.getURL()拿地址。离线可用，安装即用，体验最好。
• 远程拉取：放自己的对象存储或 GitHub Releases，第一次用得等下载。这里必须做两个事：一是SHA-256 校验，防止文件损坏或被篡改；二是版本管理，模型文件要带版本号，扩展更新时不能因为缓存导致新旧模型混用。

提示：远程模型千万别裸用 CDN，万一你改版了模型或 CDN 回源有问题，用户端的推理结果会变得不可复现。至少加一层version字段和校验和。

3. 扩展应用架构：三层解耦 + 消息协议设计

选定引擎后，我把扩展架构明确分成三层，这也是目前我觉得最适合扩展环境的模式。

3.1 三层职责划分

• 表现层（Popup / Content Script / 页面 UI）：只负责用户交互和页面 DOM 处理。Content Script 挖到文本后，封装成一个“任务”发给后台，不在自己这里加载模型。
• 控制层（Service Worker）：负责生命周期管理、消息路由、任务队列、模型版本管理。它不跑推理，但决定“什么时候加载 Offscreen Document”“什么时候卸载”。
• 执行层（Offscreen Document + Worker）：真正的推理温床。Offscreen Document 负责持有 WebGPU 上下文和 UI 无关的 DOM 能力，Worker 负责跑 ONNX Runtime 的 CPU/GPU 计算。为什么不直接让 Offscreen Document 跑？因为推理循环里如果有长时间同步计算，会卡住 Offscreen Document 的事件循环，导致它无法响应心跳消息。多套一层 Worker，能保证生命周期诊断和管理通道永远畅通。

数据流大概是这样：Content Script 捕获到用户划词 → 构造任务（{taskId, type, text}）→ 发给 Service Worker → SW 检查执行层是否就绪 → 就绪后将任务转发给 Offscreen Document → Offscreen Document 把结果回传 → 最终原路返回给 Content Script 渲染标记。

3.2 消息协议：给任务一个“生命周期”

扩展里最容易乱的是消息满天飞，每个模块各写各的。我建议把所有推理消息统一成一个带状态的协议：

任务有pending、running、done、failed四个状态。每个请求带唯一的requestId，任何一层都只管处理对应状态的事件。这样出错时能快速定位是“没发出去”“被 SW 丢弃”“GPU 初始化失败”，还是“模型结果异常”。

对于流式推理（比如本地生成式摘要），协议要支持推送，不能让调用方干等一个Promise挂半小时。用事件通道：inference:progress、inference:complete、inference:error。这一层做好之后，后续加语音识别、图像分类等功能都只是加任务类型，不用重写通信。

3.3 关键代码：Offscreen Document 的创建与 Worker 挂载

Offscreen Document 不是普通页面，得有理由才能创建。Chrome 在后续版本里新增了chrome.offscreen.Reason.WORKERS，正好可以用于挂载 Worker 跑推理。

// background/service_worker.ts import { Reason } from "chrome-types"; async function ensureOffscreenDocument() { const existing = await chrome.offscreen.hasDocument(); if (existing) return; await chrome.offscreen.createDocument({ url: "offscreen.html", reasons: [Reason.WORKERS], justification: "Host the on-device inference worker and WebGPU context", }); }

Offscreen Document 内部的 Worker 初始化逻辑：

// offscreen.ts const worker = new Worker("inference-worker.js", { type: "module" }); worker.onmessage = (event) => { const { requestId, status, payload } = event.data; if (status === "ready") { postMessage({ type: "offscreen-ready" }); } // 将结果原路转发回 Service Worker chrome.runtime.sendMessage({ requestId, status, payload }); };

这里有个细节：Offscreen Document 和 Service Worker 之间通信，优先用postMessage而不是chrome.runtime.sendMessage，因为 runtime 消息要过浏览器内部序列化，延迟高、对大数据量不友好。如果你的执行层在 Offscreen Document 里，SW 可以直接postMessage给document的引用，链路短一截。

4. 模型生命周期管理与内存控制的实战策略

生命周期问题在普通网页里几乎不用考虑——页面关了模型自然释放。扩展里不行，SW 会被回收、Offscreen Document 可能被浏览器判定为“无用途”而关闭、GPU 上下文可能丢失。所以必须主动设计。

4.1 加载策略：懒加载 + 预热

模型不要一上来就加载，扩展安装后立刻加载 300MB 模型，用户会明显感觉到浏览器变卡，严重时直接被 Chrome 标记为“拖慢启动”。

我采用的策略是：

1. 首次触发才加载：用户第一次实际触发推理任务时，SW 检查执行层状态，没有就创建 Offscreen Document、加载模型。
2. 加载期间任务排队：把并发任务放进 FIFO 队列，加载完成后再逐个执行，避免在加载过程中又来一次请求导致二次初始化。
3. 高频场景预热：如果是翻译、摘要这类高频功能，用户首次交互后立即在后台加载模型，不等待用户真正提交内容。预热的时机选在浏览器空闲时段，用requestIdleCallback或 SW 里监听访问历史后延迟 5 秒触发。

4.2 卸载策略：不使用的模型就是负债

模型加载后如果不卸载，一个 300MB 的 q8 模型会一直占着内存，用户多开几个标签页直接卡爆。需要设计两个层面的卸载：

• 模型级卸载：连续 10 分钟没有推理请求，就session.release()释放模型。再触发时重新加载。
• 执行层卸载：模型释放后，关闭 Offscreen Document 和 Worker，让 WebGPU 上下文、WASM 内存彻底还给系统。

听起来简单，真正难的是“什么时候判定不使用了”。浏览器没有直接给扩展一个“用户空闲”的完美信号。我给了一个折中方案：以最后一次推理完成时间为基准，超过阈值就降级到“未初始化”状态。下次再推理时，用户会多等一次加载，但换来的是日常使用的流畅。

提示：如果你做了自动卸载，一定要在 UI 上给用户可见的状态。我就遇到过一个 bug：用户第二天回来第一次点按钮，界面白转了 8 秒，因为模型在卸载后重新加载。后来我在 popup 上加了一个“首次加载可能稍慢”的提示，就没人抱怨了。

4.3 推理并发与 Worker 池

端侧模型，尤其是跑在 GPU 上的，并发数是 1 最好。同一个 WebGPU 上下文里两个推理请求同时跑，要么排队，要么互相抢占显存，没有任何收益。我的做法是 SW 里维护一个全局任务队列，执行层永远只处理当前一个任务。推理中如果有新请求进来，直接排队。

如果你的扩展要同时跑两个不同类型的小模型（比如文本分类 + 关键词提取），可以考虑维护两个 Worker 实例，各自加载一个小模型。但记住：不要为每个任务都 new 一个 Worker，Worker 的启动成本和模型加载成本都比任务本身贵得多。

4.4 内存观测与泄漏排查

扩展里查内存泄漏非常痛苦，因为你不能像普通页面那样打开 DevTools 的 Memory 面板看每个堆快照。我现在用的方式：

1. 定期采样performance.memory.usedJSHeapSize（Chrome 支持），每秒记一次，存到内存环形队列里。
2. 推理前后对比：每次推理完成，记录模型内存快照和推理后内存快照，如果峰值持续增长而不是回到基线，说明有泄漏。
3. 监听异常事件：webgpu context lost、worker error都要上报，很多时候泄漏不是 JS 的问题，是 GPU 上下文没释放。

我用这套方法抓住过一个真泄漏：最初我在每次推理后都主动session.release()，但 WebGPU 的 pipeline cache 没有被释放，连续推理 20 次后显存占用爬升了 200MB。后来改成“保留 session、释放输入输出 Tensor”，并且每隔 30 分钟重建一次执行层，内存曲线才算稳定。

5. 工程实现规范：构建、打包、降级与测试

架构和生命周期定好之后，剩下的就是工程实现规范。这一章偏向“工业化”，但恰恰是很多人做扩展 AI 时最容易忽略的部分。

5.1 推荐目录结构

我用 Vite + TypeScript + wxt 搭建，目录最终长这样：

extension-ai/ ├── src/ │ ├── entrypoints/ │ │ ├── background/ │ │ │ └── index.ts # Service Worker 控制层 │ │ ├── content/ │ │ │ └── index.tsx # 页面内容提取与标记 │ │ ├── popup/ │ │ │ └── index.tsx # 用户面板 │ │ └── offscreen/ │ │ ├── index.html │ │ ├── offscreen.ts # Offscreen Document 宿主 │ │ └── worker.ts # 推理 Worker │ ├── core/ │ │ ├── types.ts # 任务协议类型 │ │ ├── message.ts # 消息路由工具 │ │ └── taskQueue.ts # 任务队列 │ ├── engines/ │ │ ├── onnx.ts # ONNX Runtime Web 封装 │ │ └── fallback.ts # WASM 降级路径 │ └── models/ │ ├── ad-classifier-q8.onnx │ └── tokenizer.json ├── wxt.config.ts ├── package.json └── tsconfig.json

最关键的是core/types.ts和core/message.ts。它们定义了任务的协议边界，所有入口文件都从这两个模块导消息类型，避免在 SW、Content、Popup、Offscreen 四个地方各自维护一份消息结构。

5.2 构建与打包的几个坑

• WASM 文件要单独处理：ONNX Runtime Web 的.wasm文件在构建时容易被打包器忽略。需要在构建配置里把ort-wasm-simd-threaded.jsep.wasm这类文件复制到最终产物目录，否则运行时 404。
• 不依赖远程 CDN：扩展的 CSP 默认不允许远程脚本，而且端侧推理本来就有离线场景。把 runtime 的 wasm 和模型全部打成本地文件。
• 包体超限怎么办：Chrome Web Store 对扩展包体有限制，模型过大时建议拆分成“核心扩展（几 MB）+ 模型按需下载包”的方式。远程下载模块要做断点续传和完整性校验。

5.3 降级与兼容：WebGPU 不可用时的优雅回退

你永远不知道用户用的是什么年代的设备。有些 Windows 老机器 WebGPU 支持很差，甚至扩展跑在 Chrome 112 及以下版本。所以，必须设计降级链。

我的降级链是：

1. 首选 WebGPU（ort.env.backendFlags开启webgpu）。
2. 如果初始化失败或 context lost 多次，切到 WASM SIMD + Threads。
3. 如果 WASM 也失败（比如老设备内存不足），干脆禁用 AI 功能，只在 UI 上告诉用户“当前设备不支持本地推理”。

降级不能光靠 catch 错误，要主动做特性检测：

async function detectCapability() { // 1. 检测 WebGPU if (navigator.gpu) { const adapter = await navigator.gpu.requestAdapter(); if (adapter) return "webgpu"; } // 2. 检测是否支持 WebAssembly threads if (WebAssembly.SIMD) return "wasm"; return "unsupported"; }

注意navigator.gpu存在不意味着真的能用，requestAdapter()可能返回 null。这个检测结果要缓存到chrome.storage.session，每次扩展启动或 Offscreen 重启后重新检查一次，不要每次推理都查。

5.4 测试与监控：验证正确性比性能更重要

端侧推理在扩展里有个隐性问题：相同模型在不同后端上输出可能有微小差异。WebGPU 的算子实现和 WASM 不同，float 累加顺序不同，最终 logits 可能有细微差别。这不影响分类，但对置信度阈值敏感的任务影响就会显现。

我的测试规范是：

• 差异性测试：同一组输入，分别跑 WASM（当基准）和 WebGPU，对比输出向量最大误差。如果误差超过 1e-2，说明 GPU 实现有问题，要换算子配置。
• 集成测试：用 Playwright 加载扩展，模拟真实用户划词，断言最终 DOM 标记是否出现。
• 内存回归：每次发版前跑一轮“连续 50 次推理”的自动化脚本，观察内存是否符合基线曲线。

监控方面，我把推理耗时、后端类型、模型版本、失败原因用chrome.storage.local做成环形日志（只保留最近 200 条）。用户反馈“AI 不好用”时，我能远程拉这些日志定位，而不是靠猜。

6. 我在扩展里跑模型踩过的三个坑：完整排查链路

最后分享三个印象最深的坑。每个都不是文档里直接写清楚的，排查过程也很有代表性。

6.1 Service Worker 被杀，推理任务直接消失

现象：功能偶尔可用，偶尔不可用。用户反馈“点了一下没反应，再点一下就好了”。我本地用 DevTools 调试时永远复现不了，因为 DevTools 打开时 SW 不会被杀。

排查过程：

1. 先在 SW 里加日志，记录所有事件的时间线。
2. 发现推理任务发出后，没有任何inference:done或inference:error事件。
3. 怀疑是消息丢了，检查chrome.runtime.sendMessage的返回Promise，发现一直 pending。
4. 最后在 SW 里加console.log配合chrome://serviceworker-internals看进程状态，发现进程在推理开始后约 20 秒被杀。

根因：当时我把模型加载和推理全写在 SW 里，占用的 CPU 时间太长，Chrome 判定 SW 没有在合理时间内完成事件处理，强制回收。

解决：把所有推理逻辑迁到 Offscreen Document + Worker。迁移后问题从“随机失效”变成“可预期加载时长”，再也没被 SW 回收。

6.2 Offscreen Document 的 WebGPU 上下文丢失

现象：用户全屏看视频时，扩展推理会偶发报错。重启浏览器后恢复，过一阵又出现。

排查过程：

1. 错误信息只有WebGPU context lost，没有堆栈。
2. 最初以为是代码里 WebGPU 上下文创建参数不对，反复尝试不同powerPreference无效。
3. 加了一个contextlost事件监听，发现事件触发在用户切换显示器分辨率之后。
4. 同时注意到，很多设备的内存压力过大时，浏览器会主动重置 GPU 上下文。

根因：WebGPU 上下文是一个脆弱的资源，系统层面（显卡驱动重置、显存不足）和应用层面都可能让 GPU 进程重启。扩展必须把它当“会随时断开的连接”来对待。

解决：设计“恢复”机制——监听contextlost，一旦触发，释放旧的 Offscreen Document，重新创建执行层，重新加载模型。当前正在跑的任务标记为failed并返回给上层“请重试一次”。

const canvas = document.createElement("canvas"); const adapter = await navigator.gpu.requestAdapter(); const context = canvas.getContext("webgpu"); context.addEventListener("contextlost", (event) => { event.preventDefault(); onContextLost(); // 重建执行层 });

经验：以后凡是涉及 WebGPU 的扩展功能，第一版就要把恢复逻辑写进去，因为你永远不知道用户会在什么样的情况下使用你的扩展。

6.3 大数组跨上下文传递导致页面卡顿

现象：Content Script 做文本处理时，页面滚动明显变卡，尤其是选中大段文字后。

排查过程：

1. 单独测推理 Worker 本身的耗时，完全正常。
2. 在 Content Script 里测postMessage之后的耗时，发现发送一个 20000 维的浮点数组到后台，竟然卡了 800ms。
3. 查 MDN 才发现：postMessage的第二个参数如果没用transfer，浏览器会对数据进行结构化克隆（structured clone），相当于深拷贝。数据越大越慢，而且在大页面主线程上执行，直接卡 DOM。

根因：我的 Content Script 拿到了模型输出的完整Float32Array，然后原样传回 Content Script 做可视化。这个传输过程是拷贝，不转移。

解决：两个优化。第一，推理结果只返回 Top-K 结果（比如 Top 5 分类标签）而不是全量向量，数据量从 20000 降到 5。第二，确实需要回传大数组时，使用transfer转移所有权：

worker.postMessage({ requestId, data: floatArray.buffer }, [floatArray.buffer]);

经验：扩展架构里，能少传数据就少传数据。跨上下文的每一条数据都有真实成本，不只是网络带宽那种成本，是同时占用两个上下文内存和主线程时间的成本。设计消息协议时，第一原则是“最小载荷”。

最后的体会

从前面的踩坑经验里，我自己的体会是：在扩展里做端侧 AI，本质上是把“模型服务”的整套运维问题搬到浏览器里重做一遍——生命周期、健康检查、版本管理、降级、监控，一个都不能少。前期多花一天把架构边界画清楚，后期至少省一周排查疑难杂症。另外一个小技巧：模型版本和扩展版本千万不要绑死，模型单独带版本号，出现问题时先把模型回滚到旧版本，而不是逼用户升级扩展。这套架构后来我又复用到了本地摘要、关键词提取、违规内容标记等多个功能上，基本只写任务处理逻辑，不重做基础设施。如果你正准备在扩展里上端侧模型，建议照着这个思路先画清楚边界、定义消息、写死降级链，再碰模型代码。