浏览器扩展中的端侧AI推理:架构设计与工程实践
最近大半年我一直在折腾同一个方向:在浏览器扩展里直接跑端侧 AI 推理。以前做扩展,功能要么是请求云端接口,要么是纯本地规则判断;但这两年浏览器端能跑的模型越来越多,WebGPU 把 GPU 调度带进了网页,WASM 也能扛起更重的算子。我陆陆续续做了几个内部工具之后发现,真正难的不是“模型能不能跑”,而是“在扩展这个相对受限的宿主环境里,怎么把模型、引擎、消息通道、任务调度和缓存体系当成一个系统去设计”。这篇文章就是我个人在这套体系上的架构笔记,也是给自己的工程实现规范做一次沉淀。如果你正准备在 Chrome 或 Edge 的扩展里集成端侧模型,或者只是好奇这一切怎么运转,读完应该能少走不少弯路。
1. 为什么要在浏览器扩展里做端侧AI推理
1.1 云端推理的痒点与痛点
先泼盆冷水:现在市面上大多数“智能扩展”还是挂在云端接口后面,你选中一段文字,它发到服务器,服务器跑完模型返回结果。这种架构开发确实省心,但用起来有几个很现实的问题。
第一是数据出域。你在网页上选中合同、邮件、病历这类敏感内容,点击“智能提取”,内容就离开本地了。很多用户嘴上不说,心里是介意的。第二是延迟和成本。一次长网页摘要,上传可能要几十KB甚至几百KB,在弱网环境下转圈转得人心烦;API 按次计费,重度用户一个月下来不是小数目。第三是可用性。服务端一旦抖动、升级、限流,扩展就瘫痪。“你的号码正在等待排队”这种提示,放在浏览器插件里特别劝退。
端侧推理把这些痛点一次性按下去了:数据不出浏览器,推理发生在本地进程,不依赖网络,没有按次费用。隐私、延迟、成本、可用性四件事同时改善,所以它值得被认真对待。
1.2 浏览器扩展:端侧AI的“天然宿主”
为什么偏偏要选浏览器扩展,而不是单独做一个本地应用?因为扩展天然具备别的端没有的“上下文”优势。
我们平时说的“端侧AI”,普通网页也能跑,但网页受同源策略和安全沙箱限制,拿不到跨域页面内容;用户每次打开都要重新加载模型,刷新一下就全没了。扩展不一样,它由 Manifest V3 规范管理,拥有独立的后台服务环境(Service Worker),可以持久缓存模型文件,还能在主页面里通过 Content Script 读取当前正在浏览的页面 DOM。这意味着它既懂“用户正在看什么”,又能在本地完成推理,然后把结果回填到页面旁边。
同时浏览器扩展的生态又足够开放。Chrome 和 Edge 共享同一套扩展规范,写一套架构两边能用;Firefox 的差异也不大,无非是
browser
和
chrome
命名空间的区别。再加上 WebGPU、WebAssembly 这两年快速普及,端侧推理的性能瓶颈正在被持续推高。可以说,现在的扩展就是一个轻量级、有权限、有上下文、有原生 UI 承载的端侧 AI 运行壳。
1.3 这些场景适合放进扩展推理,哪些不适合
我踩过一些坑之后,总结了一个简单的判断标准: 推理结果是不是高频、小模型、强上下文相关 。满足这三点,就适合做扩展端侧推理。
适合做得比较顺的场景包括:
- 页面摘要:读取当前网页正文,本地生成摘要,不把全文传走;
- 翻译与术语解释:选中文本,本地翻译或解释,实时性比云端好;
- 表单与文本清洗:识别邮箱、电话、地址、错误命名实体;
- 轻量视觉任务:截图里的文字识别、二维码读取、图片主体分类;
- 个性化推荐排序:比如给浏览器书签、历史记录做本地 embedding,再算相似度。
不适合的也很明确:大参数对话模型、需要海量知识库支撑的问答、需要固定版本迭代的大型模型,都不适合塞进扩展。扩展的下载包体积、Service Worker 生命周期和内存上限,决定了它只能跑“小而快”的模型。硬塞大模型,用户下载体验极差,浏览器也会分分钟教你做人。
2. 端侧AI推理系统架构:别把所有逻辑塞进一个文件
2.1 四层架构先行:UI层、服务层、引擎层与模型层
很多初学者做扩展,习惯把“抓网页、调模型、显示结果”全写在
content.js
里。十分钟能跑通 demo,一个月之后维护起来会想哭。我后来一直用的是四层拆分:UI 层、服务层、引擎层、模型层。
UI 层负责与人交互,包括 Popup 页面、Options 配置页,以及 Content Script 渲染的浮窗。服务层是核心调度中枢,一般住在 Service Worker 里,负责接收请求、安排任务、广播进度。引擎层是推理引擎的封装,比如 Transformers.js 或 ONNX Runtime Web 的单例。模型层就是实际的权重文件、配置文件、tokenizer,以及模型元信息。
这四层我用一个生活化类比来理解:UI 层是餐厅的前厅点菜台,服务层是传菜间和调度员,引擎层是灶台,模型层是食材库和预制菜。前端传菜员不直接进灶台,调度员也不自己炒菜,各层之间只通过约定接口协作。这么结构化的原因很简单:扩展里发生异常时,你必须能快速定位问题出在哪一层。如果不分层,一旦模型加载报错或消息格式不对,你就要在几百行混杂代码里捞针。
2.2 核心模块职责划分:模型、调度、缓存各管一摊
在四层框架下,我进一步拆出了几个独立模块,每个模块只干一件事。
模型管理模块负责“模型有没有”“该不该更新”“什么时候加载”,它会记录本地模型版本,与扩展打包版本比对,决定是直接用内置模型还是从模型仓库下载。推理引擎模块是引擎层的门面,只暴露
init()
、
run()
、
dispose()
三个方法,内部什么细节都不往外漏。任务调度模块维护一个任务队列,处理并发请求、优先级、超时和取消。缓存模块负责模型文件和临时推理 IPC 的读写,优先用 Cache API 和 IndexedDB;最后还有一个消息协议模块,定义所有通信消息的格式和错误码,这是全系统的“通用语”。
我见过很多半途而废的扩展项目,问题大多出在模块边界模糊上。比如把模型下载逻辑写在 Popup 里,用户一关 Popup 下载就被中断;再比如把 tokenizer 初始化写在 Content Script 里,每个页面都要初始化一遍,内存直接爆掉。模块职责一旦划清楚,这些问题基本能从根上避免。
2.3 一次推理请求的生命周期:从页面点击到结果回填
架构不落地就是空话,所以我把一条完整的推理请求生命周期串一遍。
假设用户在页面里选中一段文字,点击扩展浮窗的“提取关键词”。这个动作先由 Content Script 捕获,它把选中文本和上下文信息封装成一个标准消息,通过
chrome.runtime.sendMessage
发给 Service Worker。Service Worker 收到后,先做基本的校验和优先级判定,把任务放进队列。如果队列前面还有任务,就等待并上报一个“排队中”的状态;轮到了之后,调度模块把任务交给推理引擎。
推理引擎先确认模型是否已加载到内存,没有就触发一次初始化。初始化完成后执行推理,拿到 embedding 或 token 序列,再按约定封装成
INFERENCE_RESULT
消息回给 Content Script。Content Script 收到结果后渲染浮窗。整个链路里,Model、Engine、Service、UI 四层各自只关心自己那一环。这样设计的好处是,哪一步慢了、哪一步错了,都能通过日志快速锁定层位置。
3. 推理引擎选型与模型集成实操
3.1 三大引擎怎么选:ONNX Runtime Web、Transformers.js、WebLLM
浏览器端能跑的推理引擎,目前主流就三个方向。第一个是 ONNX Runtime Web,它是把模型转成 ONNX 格式后,通过 WebAssembly 或 WebGPU 后端跑推理。它的优点是模型来源广,换模型不换引擎;缺点是 API 偏底层,需要自己处理 tokenizer、padding、后处理,工程量大。
第二个是 Transformers.js,它把 Hugging Face Transformers 的能力搬到了浏览器端,内置了文本分类、抽取、摘要、embedding、图像分类等 pipeline,直接用
pipeline()
一行调用。它底层其实也依赖 ONNX 格式和 WebGPU/WASM,但帮你把前后处理全包了。第三个是 WebLLM,主打浏览器里跑大语言模型,比如 4bit 量化后的 Llama、Phi 之类,能生成自然语言。
我自己的选型经验是:做 token 级的任务,比如 embedding、分类、实体抽取,优先 Transformers.js;手头已经有一堆 ONNX 模型,想在扩展里灵活加载,选 ONNX Runtime Web;要做端侧对话助手,并且接受几秒到几十秒的生成延迟,再看 WebLLM。选型时不要被“先进”忽悠,要看你最终想解决的任务类型。
3.2 我最终的选型路线:Transformers.js + WebGPU
我目前的主力方案是 Transformers.js 加 WebGPU 后端。选择它不是因为性能绝对最优,而是因为工程效率最高。它对扩展场景有几个天然加分项:模型参数通过
device: 'webgpu'
一行切换;内置了量化和缓存机制;不容易写错前后处理。
举个例子,做文本 embedding 发给向量数据库,传统 ONNX 方案要自己加载 tokenizer、手动构造 input_ids、attention_mask,然后处理 hidden state。而 Transformers.js 里就是一句:
import { pipeline } from '@xenova/transformers';
let extractor = null;
async function getEmbedder() {
if (!extractor) {
extractor = await pipeline('feature-extraction', 'Xenova/bge-small-en-v1.5', {
device: 'webgpu',
dtype: 'q8'
});
}
return extractor;
}
这段代码里,
device: 'webgpu'
让它优先走 GPU,
dtype: 'q8'
让它加载量化模型。第一次运行会慢一些,因为要下载模型并初始化;之后就是复用同一个
extractor
实例,不会再重复加载。
3.3 模型转换与量化:把几百MB下载体积打下来
扩展场景里,模型体积是生死线。你做一个 500MB 的扩展,用户连安装都嫌烦。所以模型一定要做转换和量化。
常规流程是这样的:先从模型仓库拿到原始 PyTorch 权重,通过
optimum-cli
转成 ONNX 格式,再做量化。以我常用的 BGE-small 模型为例,原始权重约 110MB,转成 ONNX 后大概也是 100MB 上下,量化为 int8(q8)后能压到 30MB 左右。这个体积对扩展来说基本可以接受,配合 gzip 或 brotli 压缩后还能再小一点。
量化精度损失要看任务。embedding 类任务我实测下来,q8 对检索效果的影响很小,也就 1% 到 2% 的分数浮动;分类任务也几乎无感。真正要小心的是摘要和生成类任务,量化太狠会让输出质量肉眼可见地下降,所以摘要任务我倾向用 fp16,而不是 q8。这个取舍,建议你把自己真实语料跑一遍再定。
3.4 引擎初始化与单例封装:写一个不崩的推理入口
很多扩展崩溃不是因为模型烂,而是初始化逻辑写得稀烂。最常见的问题是:每次弹窗打开都重新初始化一次模型,内存直接翻倍。我把推理入口封装成单例,同时处理 Service Worker 被回收后再创建的恢复逻辑。
一个简化版的骨架大概是这样的:
class InferenceService {
constructor() {
this.extractor = null;
this.initializing = null;
}
async getExtractor() {
if (this.extractor) return this.extractor;
if (!this.initializing) {
this.initializing = this.createExtractor().finally(() => {
this.initializing = null;
});
}
return this.initializing;
}
async createExtractor() {
const extractor = await pipeline(
'feature-extraction',
'Xenova/bge-small-en-v1.5',
{ device: 'webgpu', dtype: 'q8' }
);
this.extractor = extractor;
return extractor;
}
async run(text) {
const extractor = await this.getExtractor();
const output = await extractor(text, { pooling: 'mean', normalize: true });
return Array.from(output.data);
}
}
关键点是
this.initializing
这个 Promise 缓存。它保证并发请求只会触发一次初始化,避免重复加载;同时初始化失败后会把缓存清掉,下次还能重试。这套骨架我几乎每个端侧推理项目都复用,属于投入产出比极高的防御式写法。
4. 工程实现规范:从“能跑”变成“能上线”
4.1 权限最小化与CSP合规:先减小扩展的攻击面
浏览器扩展一旦集成模型,它要读取本地模型文件,要做网络请求下载模型,要在页面上下文执行脚本。权限边界要是模糊,不仅审核难过,也更难保证用户数据安全。
我的规范第一条是权限最小化。不要一把梭地申请
<all_urls>
、
webRequest
、
tabs
这种高权限。做页面摘要,一般只需要
activeTab
、
scripting
、
storage
三项;如果模型全部打包进扩展,甚至不需要网络权限。权限越少,用户越不慌,Chrome 商店审核也越顺利。
第二条是严格设置 CSP。MV3 默认禁止
eval
,但你要注意远程代码加载。模型仓库用 CDN 下发时,必须在
manifest.json
的 CSP 里白名单限域。我在不少项目里看到有人为了图方便关掉安全策略,这是非常危险的,扩展里的 Content Script 有页面权限,一旦被注入恶意脚本,后果远大于一个普通网页被 XSS。
4.2 消息通信协议:别再用随手起的消息名
内容脚本、弹窗、Service Worker 之间大量通信,如果消息名随手起,比如
sendMsg
、
getResult
,两个版本之后绝对会乱。我把消息协议当成一个小型 API 来设计。
统一消息结构是:
{
id: 'uuid-xxx', // 每次请求唯一
type: 'inf_req', // 消息类型枚举
payload: { task: 'embed', text: '...' },
ts: Date.now()
}
响应结构也要统一:
{ id, ok: true, result: {...} }
,失败时
{ id, ok: false, error: { code, message } }
。错误码不要随意用字符串,全部收敛成常量,比如
MODEL_NOT_READY
、
ENGINE_NOT_SUPPORTED
、
TASK_TIMEOUT
。
我给常用的消息类型做了个表,放在团队规范里:
| 消息类型 | 方向 | 说明 |
|---|---|---|
inf_req
| Content Script → Service Worker | 发起推理请求 |
inf_progress
| Service Worker → Content Script | 上报排队、加载、推理进度 |
inf_res
| Service Worker → Content Script | 返回推理结果 |
model_status
| 任意 → Service Worker | 查询模型加载状态 |
engine_error
| 任意 → Service Worker | 上报引擎异常 |
这样做的好处是,日志查起来特别舒服。线上出问题,翻开日志能明确看到哪个环节的类型不对、哪个 ID 没有关闭。
4.3 任务调度与并发控制:推理任务请排队
Service Worker 里的推理任务有个硬约束:它不能长时间存活,也不能同时在主线程上跑太多计算。我有一次踩坑,就是 Content Script 在十个页面同时发推理请求,结果十个任务齐头并进加载模型,几秒后内存飙到快 2GB,扩展直接崩溃。
后来我强制所有推理请求走队列,严格串行执行。任务队列内部要有几个状态:
pending
、
running
、
done
、
failed
,还要支持优先级插队。比如用户手动点选的请求,可以排到自动触发的请求前面。
简易队列代码:
const queue = [];
let running = false;
async function enqueue(task, priority = 0) {
return new Promise((resolve, reject) => {
queue.push({ task, resolve, reject, priority, ts: Date.now() });
queue.sort((a, b) => b.priority - a.priority || a.ts - b.ts);
pump();
});
}
async function pump() {
if (running || queue.length === 0) return;
running = true;
const { task, resolve, reject } = queue.shift();
try {
resolve(await task());
} catch (e) {
reject(e);
} finally {
running = false;
pump();
}
}
记得给每个队列任务加超时时间。推理引擎如果 30 秒还没返回,基本上就是模型加载卡死或引擎内部死锁,这时候主动 reject 掉,给用户一个“请重试”的反馈,比一直转圈好得多。
4.4 三级缓存策略:第二次打开扩展不再干等
模型加载慢,是端侧推理体验差的最大原因。用户第一次点击,看到三秒以上的加载转圈,可能就流失了。我试过把模型文件下到
storage.local
,但 MV3 里
storage.local
存大文件有性能问题;后来我改用 Cache Storage API,配合包内置模型做了一个三级缓存。
第一级是内存缓存,模型跑起来之后就驻留在内存里,后续请求直接调用。第二级是 Cache Storage,模型文件第一次从模型仓库下载后,写入 Cache Storage,后续加载从本地缓存读,不再走网络。第三级才是扩展包内置模型,那部分随扩展一起安装,适合体积小、必须可用的核心模型。
加载顺序是:有内存直接用内存,没有内存查 Cache Storage,没有缓存再读取内置包或请求网络。这一套下来,第二次打开扩展的加载时间能从十几秒降到一两秒,几乎是质变。
4.5 失败降级方案:不能让用户对着白屏发呆
端侧推理最坏的情况不是慢,而是彻底不可用。WebGPU 在老机器上可能不支持,模型下载也可能失败,甚至浏览器本身不支持某些 API。所以工程实现里必须设计多层降级。
我的降级顺序是:WebGPU → WebAssembly → 规则引擎。模型推理失败后,如果还有 WASM 版本的引擎,就切过去;WASM 也没有的话,扩展不能直接罢工,而是退回基于正则或关键词的简单规则处理结果。虽然结果粗糙,但至少用户在功能上还有回应。
所有降级路径都要给用户一个明确的提示,例如浮动角标显示“当前设备不支持 GPU,已切换 CPU 模式”。不要静默降级,那会让用户觉得功能不稳定。实际上大多数用户很宽容,他们能接受“这个功能需要高性能设备”的诚实说明。
5. 端到端实操:做一个人工智能页面摘要扩展
5.1 功能定义与流程设计
纸上谈兵没什么意思,我拿一个实际做过的页面摘要扩展当案例。功能需求很简单:用户点击扩展工具栏图标,扩展读取当前页面正文,在本地生成一段摘要和三个关键词。
交互流程我设计成四步。第一步,点击图标后 Popup 发起一个
summary_req
请求。第二步,Service Worker 通知 Content Script 抓取
article
或
main
标签下的正文文本,清理掉脚本、样式和无关链接。第三步,Service Worker 把文本交给推理引擎,调用摘要模型生成结果。第四步,结果回传 Popup 展示,同时支持复制到剪贴板。
这里有个细节:Content Script 抓正文不能全部一股脑发给模型。模型输入长度有限,通常要先做截断或分段处理。我习惯取前面 8000 字符,超过部分按段落截断丢弃;如果页面有标题和 meta description,会一起传进去作为补充。
5.2 从manifest到推理调用:关键代码怎么落
Manifest V3 的基础配置大约长这样:
{
"manifest_version": 3,
"name": "Smart Page Summarizer",
"version": "1.0.0",
"permissions": ["activeTab", "scripting", "storage"],
"background": {
"service_worker": "src/background.js",
"type": "module"
},
"content_scripts": [
{
"matches": ["http://*/*", "https://*/*"],
"js": ["src/content.js"]
}
],
"action": {
"default_popup": "popup.html"
},
"web_accessible_resources": [
{
"resources": ["models/*", "wasm/*"],
"matches": ["http://*/*", "https://*/*"]
}
]
}
后台拿到正文后,调用摘要模型的代码大致是:
import { pipeline } from '@xenova/transformers';
const summarizer = await pipeline(
'summarization',
'Xenova/distilbart-cnn-6-6',
{ device: 'webgpu', dtype: 'q8' }
);
const result = await summarizer(text, {
max_length: 120,
min_length: 40,
do_sample: false
});
max_length
和
min_length
控制摘要长度。这套配置在普通办公本上,一段 5000 字的网页正文,推理耗时大约 3 到 6 秒。对于摘要这种非实时交互场景,是可以接受的。
5.3 实测性能与资源占用
我实测过几台机器的数据,差异很大,这里给个参考范围。
| 环境 | GPU支持 | 首次冷启动 | 推理耗时 | 峰值内存增量 |
|---|---|---|---|---|
| Win 11 + RTX 3060 | WebGPU | 8~12s | 2~3s | 300MB+ |
| MacBook M1 | WebGPU | 6~10s | 3~4s | 350MB+ |
| 老旧Win10本(核显) | 不支持,回落WASM | 12~18s | 8~15s | 500MB+ |
可以看到,WebGPU 支持与否直接决定体验上限。所以我在工程规范里加了一条: 正式发布前,一定要在无 GPU 的设备上跑一遍降级路径 。这个很容易被开发时的主力机掩盖掉。
6. 踩坑实录与调试技巧
6.1 我踩过的四个坑
第一个坑是 Service Worker 被冻结。MV3 的 Service Worker 不干活就会被回收,我早期测试时,配好所有代码,把 Popup 关掉再打开,发现推理请求根本没送达,排查半天才发现是 Service Worker 已经“休眠”,需要点击扩展图标重新激活。现在我的处理方式是:所有请求都带上唤醒逻辑,且在 Service Worker 里不依赖全局状态,而是每次从缓存和 IndexedDB 恢复。
第二个坑是 WebGPU context 丢失。页面切后台、电脑休眠、GPU 驱动重置,都可能让 WebGPU 上下文失效。推理引擎抛出异常后,如果不重建 pipeline,后续所有请求都会失败。所以我给引擎封装加了一层错误监听,异常后自动
dispose()
并重建实例。
第三个坑是模型文件路径写错,导致加载了旧的缓存模型。模型升级后用户可能还在用旧缓存,行为和结果都对不上。现在我的模型管理模块会把模型版本号写进 Cache Storage 的 key 里,例如
bge-small-q8-v3
,版本变了就自然失效。
第四个坑是内存持续增长。调试时发现,每次调用
pipeline
都会在 WASM 堆里留下内存,不显式释放的话,几十次推理后占用高到吓人。换成单例之后问题基本消失,但如果你在同一个页面频繁创建短生命周期的
pipeline
,一定要用
env.backends.onnx.wasm.proxy
等机制仔细管理。
6.2 调试扩展推理的实用组合拳
调试扩展里的推理,比普通前端麻烦,但也有一套实用打法。
首先是
chrome://extensions
页面,找到你的扩展,点击 Service Worker 链接,能打开独立的 DevTools,这里能看到后台日志、网络请求、存储内容。其次是
chrome://gpu
,可以确认当前浏览器是否启用了 WebGPU、图形处理器型号和特性支持情况。这能帮你区分“引擎代码问题”和“硬件不支持问题”。
第三是针对模型加载链路打点。我用
performance.mark('model-load-start')
和
performance.mark('model-load-end')
在关键节点打点,再用
performance.measure
统计耗时,把数据上报到调试面板。另一个隐性技巧:在扩展里开启 verbose 日志开关,把
env.ONNX_LOG_LEVEL
调整到 info,能直接看到 WASM 后端的执行日志,非常有助于判断算子是否走了 CPU fallback。
6.3 常见问题速查表
| 问题现象 | 可能原因 | 快速排查方向 |
|---|---|---|
| 推理结果返回 undefined | 引擎没有初始化成功 |
在 Service Worker 日志里看
pipeline
是否报错;检查模型文件是否加载
|
| WebGPU 不可用,强制回落 WASM | 浏览器版本或显卡驱动不支持 |
打开
chrome://gpu
看 WebGPU 状态;升级浏览器
|
| 模型下载到一半失败 | 网络波动或缓存 Key 冲突 | 清掉 Cache Storage 对应 key 后重试;给下载加断点续传 |
| 扩展重载后推理全部失效 | Service Worker 全局状态丢失 | 不在顶层缓存 extractor,改为按需懒加载;用 Cache API 恢复 |
| 扩展内存占用持续上涨 | 重复创建 pipeline,或未释放中间结果 |
强制单例化;避免在循环里调用
pipeline()
|
这套表我直接放在扩展仓库的 README 里,线上用户反馈问题时,我第一句话一般是“打开 Service Worker 的 Console,把报错复制给我”。有这张表兜底,大部分问题靠日志就能快速定位,不用下载用户环境逐台复现。
最后说点个人体会。这套东西如果让我重新做一次,我会把接口契约和模型版本管理放在最前面,先画好消息协议再写代码,先把模型体积压到最小再谈功能。做端侧 AI 扩展,就像经营厨房:菜刀锋利、灶台稳定、食材新鲜,前厅再忙都不会乱。浏览器扩展不是一个装模型的黑盒,而是一套有生命周期、有权限边界、有资源约束的应用系统;端侧 AI 推理也不该是“临时调个接口”的玩具,它值得按基础设施的标准来建设。如果这篇笔记能帮你少踩几个版本的坑,那我这几个月的折腾就没白费。
更多推荐
所有评论(0)