我做划词翻译扩展的时候,一开始图省事直接接的云端翻译API,结果被两件事教做人:一次是在弱网环境下的会议室演示,延迟直接飙到让人尴尬;另一次是用户直接把一份带保密标识的文档截图丢进来想翻译,我连解释“数据会上云”的勇气都没有。那之后我开始认真评估在浏览器扩展里做端侧AI推理,把所有逻辑都压在本地跑。这个方向确实能解决延迟、隐私、成本、离线四大问题,但代价是——你要重新设计整套系统的架构和工程规范,沿用普通前端项目的惯性思维一定会翻车。

我先说结论:浏览器扩展不是普通网页,“端侧AI推理”也不是在页面里 import 一个模型库就跑那么简单。扩展环境有严格的生命周期管理、多上下文通信约束、内存配额和CSP限制,推理引擎的加载、调度、生命周期、错误恢复都必须按一套专门的规范来设计。这篇文章就是我从零搭建这套系统的完整记录,包括架构分层、运行时选型、消息协议、状态机、性能优化和实测踩坑,适合那些想在Chrome扩展(以及以Chromium为核心的各类浏览器)里跑本地模型、或者被端侧推理折腾过的前端工程师参考。

1. 为什么非要在浏览器扩展里做端侧推理

1.1 云端方案的三个致命伤:延迟、隐私和离线失效

很多人觉得“在扩展里调API不就行了”,先把这个问题彻底聊透。云端推理链路是:浏览器发起请求 → 到边缘节点 → 鉴权 → 排队 → GPU推理 → 返回,这中间每次都要过一轮完整RTT。划词翻译这种高频小任务,用户感知延迟在100~300ms可以接受,但一旦排队或者网络抖动,直接飙到1秒以上,体感上是灾难。

隐私是更硬的约束。扩展的场景很特殊:用户选中一段文字时,这段文字可能是源码、邮件、合同、论文甚至未公开的公告。你把它发到云端,即使API提供方不存日志,合规上也说不清楚。我遇到的那个用户后来直接告诉我:他所在的企业不允许向外部发送任何包含内网标识的文本。这类需求一旦出现,云端方案在架构上就是死路。

离线失效就更直接了:扩展装在本地,用户在高铁、飞机、地下室时,云端API全挂,扩展的功能就变成了一个摆设。而端侧推理不同——模型在本地,推理在本地,理论上断网状态和联网状态没有区别。把这三件事叠在一起看,端侧推理不是一个“更酷”的方案,而是这类场景下的必然选择。

1.2 端侧推理适合什么,不适合什么

这里必须先泼一盆冷水:不是所有AI功能都能端侧化。我自己的判断标准是四看:模型参数量、单次推理的算力需求、内存预算和延迟容忍度。给你一张我整理过的边界表:

业务场景 典型模型规模 端侧可行性 原因
划词翻译、命名实体识别 50M~500M参数 高 前向推理单次毫秒级,内存可控
网页正文摘要(短文本) 500M~1B参数 中高 需要量化到int8,单次要几百毫秒
长文档问答/全文生成 7B以上参数 低 内存占用数GB,生成速度完全不可用
实时视频分析 小模型+连续帧 中 算力峰值高,发热明显,需严格降帧
大规模向量检索 模型小但索引大 中 索引常驻内存,但扩展常被回收,要持久化

我的建议是:优先做单次前向、短输入、结果可离散化的任务(翻译、分类、抽取、向量化),谨慎做大段生成类的任务。生成任务不是不能做,而是你要准备好处理“慢”和“内存高位”两件事,架构设计要为此留足空间。判断标准落到一句话——用户是否愿意为了隐私和离线,多等半秒。

1.3 扩展为什么是端侧推理的理想宿主

扩展这个宿主形态其实被很多人低估了。它跟纯网页相比有三个特殊红利:第一,用户通过安装动作已经给了你后台运行、跨域请求、存储等权限,你不必像网页那样小心翼翼地申请权限或用隐私窗口兜底;第二,扩展的入口足够轻,用户调用AI的场景是零散的、小粒度的,不需要常驻一个页面,适合按需加载模型;第三,扩展的UI短平快——popup、右键菜单、划词浮窗,AI能力可以嵌入在用户原本的操作流里,而不是强迫用户打开一个新标签页交互。

当然有利就有弊,最大的弊就是生命周期和内存约束,这块我会在下一章展开。你只需要先记住一个底层认知:扩展端AI的核心矛盾,在于“模型这种大而重的东西”和“后台环境轻而多变的状态”之间的冲突。整个系统架构设计,本质上就是围绕这个矛盾做对抗。

2. 浏览器扩展环境与传统网页的架构差异:这是所有设计的前提

2.1 Manifest V3:后台页面退出历史舞台,Service Worker成了新战场

如果你写过Manifest V2时代的扩展,一定熟悉一个常驻的 background page——你可以在里面保持一个全局对象,加载完模型后一直热着,想什么时候推理就什么时候推理。但现代浏览器扩展强制Manifest V3之后,后台脚本变成了事件驱动的 Service Worker,它可以被浏览器随时停掉:空闲约30秒回收,内存紧张时优先回收扩展的Service Worker。

这意味着你不能再写这样的代码:

// 错误示范:依赖常驻后台保存模型实例
let model = null;
chrome.runtime.onMessage.addListener(async (msg, sender, sendResponse) => {
  if (!model) model = await loadModel();
  const result = await model(msg.text);
  sendResponse(result);
});

这段代码的问题在于:模型加载完,Service Worker一旦被回收,model变量就没了;下次用户再来消息,Service Worker被重新唤醒,代码从头执行,model是null,重新加载一次模型。用户感知到的就是“第一次用很慢、隔一会儿不用又很慢”,甚至直接推理中断。

正确思路是:把“模型实例”当成一个可以随时销毁和重建的临时资源,把“模型文件”“推理进度”“任务状态”这些可持久化的信息放到Storage或IndexedDB里。Service Worker只负责事件响应和任务调度,真正干重活的推理容器要分开。

2.2 Service Worker生命周期是端侧推理最大的敌人

我踩过的最深的一个坑,就是模型加载到一半Service Worker被杀。场景是这样的:用户打开扩展,我立即在后台加载一个300MB的量化模型,加载大概要十几秒。用户中途去点了别的标签页,扩展的Service Worker因为“不再活跃”被回收,加载直接中断,索引文件损坏,下次唤醒后只能从头再来。

后来我把模型加载的职责从Service Worker里彻底拆了出去,让加载动作发生在独立的页面上(具体来说,是MV3提供的Offscreen Document或者扩展自己打开的隐藏页面)。这类页面只要活着,加载就不会中断;加载完成的产物写入IndexedDB或Cache Storage,Service Worker只负责读取这些持久化的产物。

这里有一个特别反直觉的点:Service Worker不能常驻,但你可以用“心跳”让它尽量活着。MV3对Service Worker的限制是“空闲回收”,不是“硬性时间限制”——只要持续有事件触发,它就能一直跑。所以你可以用chrome.alarms设置一个25秒的定时器,每隔一段时间发一个空事件给Service Worker,让它“忙”起来。但我建议不要滥用这个技巧:浏览器会审计扩展的CPU和内存使用,你一直保活一个800MB的模型,很容易被判定为资源滥用,影响上架。

我的最终方案是:默认不保活,模型按需加载,加载过程中如果发现Service Worker即将进入空闲,就用上面说的25秒心跳撑过加载窗口。加载完成、写入持久化存储之后立刻停掉心跳,让系统恢复轻量。

2.3 三端通信:popup、content script与后台服务如何协作

MV3扩展至少有三种可运行代码的上下文:popup页面(用户点图标弹出的界面)、content script(注入到普通网页里的脚本)、扩展后台Service Worker。三者之间不能共享变量,只能靠消息传递。消息传递虽然是异步的,但有长度限制(单条消息JSON序列化后大约几十MB级别,超大对象会直接失败)和序列化开销。

我给这套系统定的通信规范只有三条:

  • 所有重量级数据(模型二进制、嵌入向量、图片像素)一律不直接过消息,先写入IndexedDB,消息里只传存储ID。
  • 所有跨上下文调用都封装成Promise风格的RPC,禁止在content script里直接调用后台的局部变量。
  • content script只做“采集输入和渲染输出”,不做任何推理逻辑。推理必须要放在后台或独立推理页面,否则网页的DOM环境会拖累推理速度。

举个具体例子:用户在网页上划选了一段文字,content script把选中文本发到后台。后台把文本写入IndexedDB,返回一个任务ID。推理完成后再通过消息把结果推给content script。全程消息体里只有字符串和ID,干干净净,不会因为序列化大对象导致崩溃。

3. 推理运行时选型:Transformers.js、ONNX Runtime Web和自研路线的取舍

3.1 三个候选方案的实际能力对比

浏览器端跑推理,主流的运行时就这么几个。我直接给你一张对比表,省得你一个一个去翻文档:

运行时 底层加速 模型格式 生态成熟度 扩展适配难度
Transformers.js WASM / WebGPU ONNX(含量化) 高,HuggingFace生态直接拉模型 低,封装好,开箱即用
ONNX Runtime Web WASM / WebGPU ONNX 高,跨端通用 中,需要自己处理模型分片和EP切换
TensorFlow.js WebGL / WASM TF SavedModel / Keras 中,维护节奏变慢 中
自研WASM内核 WASM / SIMD 自定义 低 极高,一般不建议

我最终选择了Transformers.js,原因有三:它对中文NLP模型的支持非常直接,HuggingFace上大部分模型都能无缝加载;它内置了模型分片、量化、KV Cache管理,省掉了我自己去实现这些繁琐逻辑的工程量;它的API设计得很克制,前端开发者上手成本极低。

ONNX Runtime Web也是完全可行的路线,如果你要跑的模型不是HuggingFace上的标准模型,或者需要接入自己训练/导出的自定义ONNX模型,ORT会更灵活。但代价是你要自己处理EP的选择(WebGPU优先还是WASM兜底)、模型文件的切割和加载进度、缓存过期策略等细节。我的建议是:标准模型用Transformers.js,自定义模型用ORT,不要为了“底层一点”去自研运行时——在扩展这种资源受限的环境里,基础设施的成熟度比技术上的炫技重要得多。

3.2 执行后端:WebGPU、WASM还是混合降级

搞浏览器扩展的端侧推理,执行后端的选择会直接影响模型能不能跑起来。目前的主流选择是WebGPU和WASM(WebAssembly),你可能会听人提WebGL,但那基本是旧时代的妥协,性能天花板太低,现在的新项目不建议入坑。

WebGPU的优势是能调用GPU做矩阵运算,对大模型的性能提升显著。比如跑一个1B参数的量化模型,单次生成token的速度在WebGPU下可以做到100ms以内,WASM下可能要200ms开外。但WebGPU有兼容性问题:Chrome从113版本开始默认支持,Firefox至今支持不完整,Safari在较新版本才加入。而且,WebGPU在扩展环境里偶尔会遇到设备丢失问题(GPU上下文被系统回收),必须有重建上下文的恢复逻辑。

WASM的优势是兼容性极好,几乎任何现代浏览器都能跑,而且WASM运行时是纯CPU计算,稳定、不挑硬件。缺点是速度上限明显低于WebGPU。

我的工程策略是“双后端自动降级”:启动时检测当前浏览器是否支持WebGPU,支持就优先用WebGPU执行推理;不支持或推理中途设备丢失,就自动切回WASM。降级过程用户无感,顶多是在日志里记一条性能降级事件。这里有个容易忽略的细节:WebGPU和WASM加载的模型权重格式可能不一样(同一个模型可能拆成不同分片),所以我的模型管理器会同时缓存两份分片配置,按当前执行后端切换加载路径。

3.3 模型文件放哪:扩展包内置、远程加载还是IndexedDB缓存

模型动辄几百MB,放哪是个系统工程问题。三种路径我都试过,直接说结论:

  • 小模型(小于50MB):直接打进扩展包。优点是安装即用、离线可用、无CORS问题;缺点是扩展包体积膨胀,上架审核时有些商店会对包大小有限制,用户体验也从“装完就能用”变成“装完还在下载扩展包”。
  • 中大型模型:首次使用按需从远程加载,下载完成后缓存在扩展的IndexedDB里。远程加载必须走HTTPS且服务端允许CORS,否则扩展的请求会被拦截。这个方案最灵活,但你要处理好“下载进度展示”“断点续传”“缓存版本管理”三件事。
  • 混合策略:把“保证核心功能可用的最小模型”内置,把“完整增强模型”远程加载。比如扩展内置一个50M的轻量摘要模型保证基本可用,用户需要高质量翻译时再下载300M的专业模型。

我最终用的是混合策略。核心逻辑在模型管理器里体现为一个简单版本号协议:IndexedDB里存了一个manifest对象,记录了模型名、版本、分片列表、哈希值。每次启动时,如果IndexedDB里的版本与远程manifest一致,就直接本地加载;不一致或缺失,则走远程加载流程。哈希校验必须做——我遇到过CDN边缘缓存造成模型文件损坏,推理结果变成乱码的怪问题,加了SHA-256校验之后才彻底排除。

4. 推理系统的分层架构:业务、调度与推理内核完全解耦

4.1 三层模型:UI业务层、调度层和推理内核层

我在动手写代码前就把架构定成了三层,并且强制规定依赖方向只能自上而下:UI业务层 → 任务调度层 → 推理内核层。UI业务层不关心模型是什么、量化没量化、引擎是WebGPU还是WASM,它只知道“我发了一个任务,等你回调”。调度层不关心业务语义,只管排队、并发控制、优先级和超时。推理内核层只做一件事:接收一个张量输入,吐出一个张量输出,对外暴露一个无状态的推理接口。

为什么一定要拆开?因为浏览器扩展里这三个层级的生命周期完全不同。UI可以瞬间开合;调度层要能持久化(任务列表在Service Worker被杀重起后还能恢复);推理内核层要能随时重建(模型实例可以销毁重建)。如果你把这三件事写在一个模块里,一旦遇到生命周期切换,就不得不把整个逻辑重写一遍。

更实际的好处是测试:推理内核不需要浏览器环境也能测,在Node.js里跑起来毫无压力;调度层可以Mock掉推理内核做纯逻辑测试;UI层只依赖调度层的抽象接口。这就让大型扩展项目有了“可测试性”这种奢侈品。

4.2 调度层核心:任务队列、并发限制与优先级策略

推理任务不是无节制执行的。WebGPU同一时刻只能跑一个计算任务,多个任务并发提交会直接报错;WASM多线程虽然能并行,但扩展的内存吃不消。所以调度层必须实现一个队列。

我给出一个经过裁剪但可用的任务队列实现(TypeScript),它包含前三件事:入队、并发限制、优先级:

type TaskPriority = 'high' | 'normal' | 'low';

interface InferenceTask<TInput, TOutput> {
  id: string;
  priority: TaskPriority;
  input: TInput;
  resolve: (value: TOutput) => void;
  reject: (reason?: unknown) => void;
}

class InferenceTaskQueue {
  private queues: Record<TaskPriority, InferenceTask<any, any>[]> = {
    high: [],
    normal: [],
    low: [],
  };
  private running = 0;
  private readonly maxConcurrency = 1;

  enqueue<TInput, TOutput>(
    input: TInput,
    priority: TaskPriority = 'normal'
  ): Promise<TOutput> {
    return new Promise<TOutput>((resolve, reject) => {
      this.queues[priority].push({ id: crypto.randomUUID(), priority, input, resolve, reject });
      this.drain();
    });
  }

  private drain(): void {
    if (this.running >= this.maxConcurrency) return;
    const nextTask = this.queues.high[0]
      ?? this.queues.normal[0]
      ?? this.queues.low[0];
    if (!nextTask) return;

    this.running++;
    this.queues[nextTask.priority].shift();
    this.execute(nextTask);
  }

  private async execute(task: InferenceTask<any, any>): Promise<void> {
    try {
      const result = await this.runInference(task.input);
      task.resolve(result);
    } catch (err) {
      task.reject(err);
    } finally {
      this.running--;
      this.drain();
    }
  }

  private async runInference(input: unknown): Promise<unknown> {
    // 实际接入推理内核,见4.3
    throw new Error('Not implemented');
  }
}

优先级策略要结合业务场景。我的规则是:用户主动触发的操作(划词翻译、点击按钮)标记为high,立刻插队;低优先级任务(后台预取标题摘要、页面空闲时的全文理解)标记为low,只在队列空闲时执行。不然就会出现一个很蠢的场景:用户狂点翻译,后台却一直在跑一条没用的自动摘要任务,导致交互卡死。

另一个容易被忽略的点是防抖合并。用户划词时鼠标一抖,可能同一个词触发三次翻译请求。调度层要做“相同入参合并”:如果wo5秒内队列中已有完全相同的输入任务,直接复用其结果,不要重复推理。这能省掉至少1/3的无效算力开销。

4.3 推理内核层:模型实例的管理与无状态RPC接口

推理内核层我的核心思路是“无状态化”。内核不知道业务,也不知道任务的来源,它只提供四个方法:initialize(初始化引擎)、loadModel(加载模型)、infer(执行推理)、dispose(释放模型)。所有状态都封装在内部,外部只能通过任务调度的抽象接口调用。

一个内部关键问题是多模型共存时的内存分配。扩展的内存非常金贵,你不能同时热着五个模型。我维护了一张模型注册表,记录每个模型的大致内存占用和最后使用时间。当内存预算接近阈值,调度层会请求内核卸载最久未使用的模型。卸载不是简单置null,而是要等正在执行的推理任务处理完,避免任务执行到一半模型被释放。

实际代码中,推理内核通过一个名为InferenceEngine的接口暴露能力:

interface InferenceEngine {
  initialize(): Promise<void>;
  loadModel(modelId: string, options: ModelLoadOptions): Promise<ModelHandle>;
  infer(handle: ModelHandle, input: TensorInput): Promise<TensorOutput>;
  dispose(handle: ModelHandle): Promise<void>;
}

业务层永远只拿到一个字符串类型的descriptor,不会直接触达引擎实例。这个设计的最大好处是下一步你可以无缝替换底层引擎——今天是Transformers.js,明天换成ONNX Runtime Web,业务层一行代码都不用改。

5. 工程实现规范:模块边界、消息协议与模型状态机

5.1 模块边界:依赖方向必须单向流动

工程规范的第一件事就是定死目录结构和依赖方向。我采用这样的分层目录:

src/
  core/          // 纯逻辑:队列、协议、状态机、类型定义,不依赖浏览器API
  runtime/       // 推理引擎适配层:Transformers.js / ORT的封装
  background/    // Service Worker入口:消息路由、任务调度
  content/       // 内容脚本:输入采集、结果渲染
  ui/            // popup与options页面
  model/         // 模型管理:manifest、下载、缓存、哈希校验

依赖方向是:ui和content可以依赖background提供的消息客户端;background依赖runtime和model;runtime和model依赖core;core不依赖任何上层模块。禁止反向依赖。这个规则我用ESLint的import/no-restricted-paths做了硬性约束,谁要是写了一条反向依赖,CI直接报错。

你可能觉得这有点过度设计,但扩展代码一旦长到几千行,没有边界约束,最后就是一团乱麻。尤其是模型管理这种全局性模块,谁都想直接用,如果每个业务模块都直接去操作IndexedDB,缓存策略和并发控制就全废了。

5.2 统一消息协议:从混沌到有序的关键一步

跨上下文的通信必须有协议约束,不然content script和后台各写各的,字段名一不一致都难说。我定义了一套基于 discriminated union 的消息协议,用type字段区分消息类型,用requestId关联请求和响应。

type RuntimeMessage =
  | { type: 'InferenceRequest'; requestId: string; taskType: 'translate' | 'summary'; payload: { text: string } }
  | { type: 'InferenceResponse'; requestId: string; ok: true; result: string }
  | { type: 'InferenceError'; requestId: string; ok: false; code: string; message: string }
  | { type: 'ProgressEvent'; requestId: string; stage: 'download' | 'load' | 'infer'; percent: number };

规则:所有消息都必须包含requestId;所有响应都必须携带对应的requestId;错误响应必须用错误码而不是裸throw。这样调试的时候一翻log就能把一次推理的完整链路串联起来,从content script发出请求到推理内核返回结果,路径清晰得跟流水线一样。

发送方封装成一个客户端类,所有上下文用同一套API。内容脚本里调用的代码如下:

class InferenceClient {
  async translate(text: string): Promise<string> {
    const requestId = crypto.randomUUID();
    const response = await chrome.runtime.sendMessage({
      type: 'InferenceRequest',
      requestId,
      taskType: 'translate',
      payload: { text },
    });
    if (!response.ok) {
      throw new Error(`${response.code}: ${response.message}`);
    }
    return response.result;
  }
}

这套协议还有一个被低估的好处:你可以把消息内容直接落日志,做问题复现。因为消息体是纯JSON,不包含任何大对象,日志体积可控,而且可以脱敏后上报(比如只记taskType不记文本内容),把隐私风险降到最低。

5.3 模型生命周期状态机:别再只用布尔值

模型加载过程不是简单的“加载中/加载完”两个状态,它有一段很长的生命周期,我强烈建议用状态机来管理。状态定义和转换条件如下:

状态 触发条件 退出条件
UNLOADED 初始状态 收到加载请求 → DOWNLOADING
DOWNLOADING 模型文件缺失或版本过期 下载完成且校验通过 → LOADING;校验失败 → FAILED
LOADING 本地文件就绪,开始初始化引擎 初始化完成 → READY;初始化失败 → FAILED
READY 模型可用,可以推理 收到释放请求 → UNLOADING;引擎崩溃 → FAILED
UNLOADING 内存回收或不再需要 资源清理完成 → UNLOADED
FAILED 任意环节出错 用户重试或达到重试上限 → UNLOADED

状态机用代码写出来不是一堆if-else,而是清晰的状态转换表:

const TRANSITIONS: Record<ModelState, ModelState[]> = {
  UNLOADED: ['DOWNLOADING'],
  DOWNLOADING: ['LOADING', 'FAILED'],
  LOADING: ['READY', 'FAILED'],
  READY: ['UNLOADING', 'FAILED'],
  UNLOADING: ['UNLOADED'],
  FAILED: ['UNLOADED'],
};

export function transitionState(current: ModelState, target: ModelState): ModelState {
  if (!TRANSITIONS[current].includes(target)) {
    throw new Error(`非法状态转换: ${current} -> ${target}`);
  }
  return target;
}

这个状态机引发的最大好处是,所有UI界面都只需要订阅这个状态,不用各自的逻辑去猜“模型现在能不能用”。进度条、错误重试按钮、降级提示,全部根据状态自动渲染。没有状态机的时候,我至少写过三处互相矛盾的isModelLoading布尔值。

5.4 错误处理与降级:把失败变成可恢复事件

端侧推理的错误场景比云端多得多:网络下载失败、磁盘空间不足、OOM、引擎崩溃、设备丢失。我的错误处理规范是这样的:

  • 所有错误都分类并映射为面向用户的文案,不直接抛内部栈。用户看到的是“模型下载失败,请检查网络后再试”,而不是一段Uncaught TypeError。
  • 每个推理请求最多自动重试一次,重试前必须确保模型状态回到READY而不是直接复用坏掉的实例。
  • 端侧推理失败后,必须给出业务降级选项。比如翻译任务失败了,弹一个小提示“本地模型不可用,是否切换到在线翻译?”,用户同意后才发云端请求。绝不未经同意偷偷把数据发出去——这是合规底线。
  • 推理内核崩溃时,自动重置整个模型栈并重新加载,但保留任务队列,等模型恢复后自动重排未完成的任务。

我把错误码定成了一套枚举:NETWORK_ERROR、MODEL_LOAD_ERROR、OOM_ERROR、ENGINE_CRASH、DEVICE_LOST。这五个错误,分别对应五个恢复策略。实际运行中最常见的还是OOM_ERROR,通常发生在设备内存不够或者多个标签页同时开着的时候。应对策略就是我之前说的内存预算和LRU卸载。

5.5 测试与可观测性:端侧推理系统的“体检设备”

最后一条工程规范是测试和监控。测试方面,我跑了两层:

  • 单元测试:针对调度队列、状态机、消息协议编解码,这些纯逻辑可以直接在Node.js里跑,速度极快。
  • 集成测试:用Transformers.js加载一个10MB以内的小模型(比如一个简单的NER模型),在测试环境里跑完真实推理流程,验证下载→加载→推理→卸载全链路。

可观测性方面我没用重型APM,而是自定义了一套轻量埋点。每个推理任务记录:模型加载耗时、排队等待耗时、推理耗时、Token生成速度(生成类任务)、输入长度、内存占用增量。这些指标以采样方式记录在扩展的IndexedDB里,每50次推理上报一次聚合数据(只含脱敏指标,不含用户文本)。这套数据帮我定位了一个困扰了接近一周的“偶发卡顿”:不是模型变慢了,而是高峰期任务排队过长,有用户一次点了20个词,全部排进了队列。后来加了合并策略,问题立刻消失。

6. 性能、内存与用户体验的平衡术

6.1 模型加载优化:分片、量化与加载进度

模型加载是扩展用户体验的第一道关卡,也是最容易失败的地方。首先,所有模型文件必须做分片处理。Transformers.js默认支持分片(把一个模型拆成若干个几十MB的bin文件),这样下载时可以并行拉取、出错了只重试失败的分片,还能显示精确到1%的下载进度。

第二是量化。相同模型,FP16转INT8体积缩小约一半,推理速度提升30%~50%,内存占用也大幅下降。代价是精度损失,但对翻译、摘要这类任务,INT8的质量下降基本无感。如果你的模型基于解码器架构(生成类任务),还可以用4bit量化进一步压缩到1/4体积,但内存和速度上要谨慎评估。我个人建议:生成类任务先做INT8,实在跑不动再考虑4bit。

第三是加载时机。我的策略是“懒加载+空闲预取”:用户第一次触发推理前不下载模型;但在扩展安装完成后,如果检测到浏览器闲置超过10秒(用requestIdleCallback或者chrome.idle检测),就静默预下载模型。这样既不会让安装过程因为下载模型而变得难熬,又能在用户真正需要时实现“秒级启动”。

6.2 推理速度与交互体验:流式输出和加载占位

做了生成类任务的人都有体会:等一整个回答出来才渲染,用户心理等待感极强;按token流式渲染,虽然总耗时一样,但用户体感快得多。Transformers.js支持生成式模型的token流式回调,我在调度层的返回值设计里专门预留了stream接口:

// 流式推理调用
const stream = await client.generateStream({ prompt: text, maxTokens: 256 });
for await (const token of stream) {
  renderText(token); // 逐token渲染到popup或浮窗
}

流式输出的另一个好处是“可取消”。用户看完开头觉得不对,直接点停止,调度层就向推理内核发一个取消信号,释放GPU资源,而不是让生成任务默默跑完。长文生成场景如果没有取消机制,一旦误触发,几百MB内存就要白白占用十几秒。

非生成类任务(翻译、分类)的体验重点是“加载中”状态的设计。我专门设计了多阶段反馈:下载阶段显示百分比,加载阶段显示“模型初始化中”,推理阶段显示“解析中”。用户看到的不再是一个转圈图标,而是能感知当前卡在哪一步,这大大减少“是不是卡死了”的焦虑和卸载率。

6.3 内存管理:在有限内存里“腾挪闪转”

浏览器扩展的内存额度没有明确的API限制,但实际受设备和标签页影响极大。我的内存管理原则是两条:

  • 所有模型常驻内存的总和不超过设备内存的10%,且最多不超过2GB。
  • 冷备用模型的优先级默认低于用户当前激活页面的性能体验。

定期用performance.memory(Chrome专用)或chrome.processes.getProcessInfo(需要额外权限)做内存采样。当模型占用的内存接近阈值,触发LRU卸载策略:把最久未使用的模型实例dispose掉,断开所有引用,并主动触发一次垃圾回收请求(性能允许时用ArrayBuffer置空来加速释放)。这个东西听起来玄乎,其实核心就是让你在设计时就记住:加载模型是“有代价的占有”,不是“一次性消费”。

还有一个被很多人忽略的内存坑:Transformers.js加载模型时如果不指定设备,可能会同时创建多个WASM线程池的备份,每个线程都有自己的内存副本。我在初始化时显式指定device: 'webgpu'或device: 'wasm',并调整wasm线程数,避免默认配置下后台悄悄多占用几百MB。

6.4 后台推理与前台交互:怎么做到“互不干扰”

推理是高CPU/GPU占用任务,如果在前台页面跑,用户会觉得整个浏览器都卡。解决方案是把我之前提过的推理容器单独拎出来:让推理发生在Offscreen Document(MV3专用离屏文档)里,它不在用户的标签页列表里,也不影响当前激活页面的渲染。

给个具体的调度细节:推理内核在Offscreen Document中运行,后台Service Worker只负责把任务消息转发进去。这样页面滚动、点击、输入跟推理并行不悖。实测下来,同样是跑一个200M模型的翻译推理,放在扩展后台直跑时,页面滚动帧率掉到30fps以下;挪到Offscreen Document后,交互基本无感,推理速度还因为避开了渲染进程的争抢而提升了约20%。

但Offscreen Document也有个硬限制:一次只能创建有限数量的离屏文档,并且不能保持无限期存活。所以我会把Offscreen Document的创建和销毁也纳入状态机管理:需要推理时创建,模型卸载后关闭。这个“按需创建离屏推理容器”的做法,是这套系统性能体验的根基之一。

7. 实战踩坑记录:那些文档里不会写的坑

7.1 Service Worker被回收导致推理中断:我的恢复设计

这是最经典的一课,我前面反复提到了,这里把实战链路完整讲一遍。现象是:模型加载中或者推理刚跑到一半,Service Worker被浏览器回收,整个任务失败了。第一次遇到时,我第一反应以为是代码里模型加载失败,看了半天日志才发现是SW被杀。

解决链路分三步:第一,所有推理任务在入队时先写入IndexedDB持久化,记录任务参数和阶段;第二,推理容器(Offscreen Document)持有模型实例和任务进度,不依赖SW存活;第三,如果SW被回收后重启,先从IndexedDB读回任务列表,主动向推理容器查询状态,已完成的返回结果,未完成的继续执行。

这套恢复机制解决的不只是SW被杀,还把“用户关掉弹出窗口再重开”这种场景也一并覆盖了。用户重新打开扩展时,上一个任务的结果已经准备好了,直接展示,而不是再算一遍。

7.2 CSP与WASM:扩展页面里的隐型绊脚石

Manifest V3默认的CSP对扩展页面非常严格,禁止eval和unsafe-eval。WASM在多数情况下不受CSP的eval限制,但Transformers.js早期版本依赖Web Worker和一些动态代码生成,我遇到过在扩展页面里跑不起来、在普通网页却能跑的情况。

排查出来的原因是:某些版本的WASM初始化代码里用了Function构造函数,被扩展的CSP拦截。解决方法是升级到支持CSP安全的版本,并且在初始化时通过Safari的WebAssembly.validate做一次预检查,提前发现WASM执行环境不可用,而不是等加载到一半才崩。另外提醒一句:不要在扩展包里手写.wasm文件并用import导入,路径和MIME处理起来极其痛苦,交给打包工具处理才是正解。

7.3 大模型在后台跑时页面卡顿:从根上解决问题

有用户反馈“扩展一翻译,整个浏览器都掉帧”。一开始我以为是GPU被占满,后来用Profiler一查,发现是Transformers.js的WASM后端在主线程初始化了多线程池,每开一个标签页,内存就多占一截。GPU可能确实没闲着,但更主要的是主线程被WASM计算抢占,导致所有页面渲染都受影响。

修这个问题的核心是两条:一是把所有计算迁到Offscreen Document或Web Worker中,彻底离开主线程;二是把WASM线程数从默认值改小(在我的场景里设置成4线程就够了),避免线程池抢CPU。改完之后,推理期间的交互流畅度回来了,推理速度虽然略有下降,但用户几乎察觉不到,这个取舍非常值。

7.4 浏览器兼容性差异:同一套架构在不同终端的表现

Chromium系的Chrome和Edge基本一致,逻辑上不用单独适配。真正让我花时间的是Firefox和Safari。Firefox对WebGPU的支持一直不完整,我的降级逻辑在这里就派上用场了——检测到WebGPU不可用自动走WASM,只是推理速度慢一些,功能不丢失。Safari对MV3的部分API支持滞后,比如Offscreen Document在Safari里不可用,我不得不做一个特殊分支:没有Offscreen Document时,退化为在Service Worker里直跑推理(承受被回收的风险),或者干脆提示用户当前浏览器不支持后台推理。

我的最终兼容性策略是:能力检测优先于浏览器检测,不硬编码UA;把WebGPU、Offscreen Document、IndexedDB、CacheStorage这些能力项做一次启动探测,然后由系统决定最终的执行方案。这样即便未来浏览器版本升级,代码的逻辑也无需大改,只是能力矩阵变了。这也是为什么我强烈建议从第一天起就要把“推理后端”和“容器宿主”都设计成可替换的抽象层,否则到兼容性阶段,你会被每一处if (browser === 'firefox')逼疯。

这套系统从我第一次在扩展里跑通端侧翻译,到现在稳定服务了几万次推理,中间踩过的坑远不止上面这些。每次遇到问题我都先回到那几张图和几个规范上找原因:消息协议对不对、状态机转换是否合规、内存预算是否超限、依赖方向有没有污染。架构的价值不在于一开始设计得多么宏大,而在于它能帮你在真实环境下把复杂的算力、内存、生命周期和交互问题拆解成可以逐个击破的小问题,然后每一个都有章可循。这套分层和规范,是我目前找到的、在浏览器扩展里做端侧AI推理最稳的一条路,你可以直接拿去作为参考起点,再根据你自己的业务场景去裁剪。

Logo

聚焦RDK与具身智能,汇集机器人开发教程、开源案例和技术交流

更多推荐