如何在Chrome扩展中使用Transformers.js
本文详细介绍了在Manifest V3 Chrome扩展中集成Transformers.js的架构设计与实践，包括服务工作者托管模型、侧边栏聊天UI、内容脚本页面交互、消息通信、工具调用循环以及数据持久化策略。
文章情报
要点
- 采用MV3架构，后台服务工作者托管模型推理，侧边栏和内容脚本作为轻量级客户端。
- 使用Gemma 4 E2B进行文本生成，MiniLM生成嵌入向量，所有推理集中在后台。
- 通过清晰的工具调用循环将模型输出转化为可执行操作，状态按生命周期分开存储。
为什么重要
这条新闻值得关注，因为采用MV3架构，后台服务工作者托管模型推理，侧边栏和内容脚本作为轻量级客户端。
技术影响
可能影响模型选型、推理成本、产品能力和评测基准。
最近，Hugging Face团队发布了一个基于Transformers.js和Gemma 4 E2B的Chrome扩展演示，旨在帮助用户浏览网页。在构建过程中，他们遇到了Manifest V3运行时、模型加载和消息传递方面的实际挑战，并分享了宝贵的经验。
**目标读者与构建内容** 本指南面向希望在Chrome扩展中运行本地AI功能的开发者，尤其是面临Manifest V3约束的场景。最终架构包括一个后台服务工作线程（托管模型）、一个侧边栏聊天UI，以及一个用于页面操作的内容脚本。
**MV3架构设计**
扩展的manifest.json定义了三个入口点：后台服务工作线程（background.js）、侧边栏（sidebar.html）和内容脚本（content.js）。后台作为控制平面，负责代理生命周期、模型初始化和工具执行；侧边栏处理用户交互；内容脚本负责DOM提取和页面高亮。这种分离避免了重复加载模型，保持了UI响应性，并遵守Chrome的安全边界。
所有消息通过类型化的枚举进行通信，后台是唯一的协调器。典型的请求流程是：侧边栏发送AGENT_GENERATE_TEXT，后台追加消息并运行推理，然后通过MESSAGES_UPDATE更新侧边栏。
**Transformers.js集成**
扩展使用了两个模型角色：gemma-4-E2B-it-ONNX用于文本生成（q4f16量化），all-MiniLM-L6-v2-ONNX用于生成嵌入向量（fp32）。所有推理在后台运行，避免了多个标签页重复加载模型。缓存位于扩展源下，所有会话共享。模型生命周期包括检查/初始化（带进度反馈），完成后复用实例。权限方面请求了sidePanel、storage、scripting、tabs和主机权限，以支持页面操作。
**代理与工具执行循环**
工具调用基于变换器格式，模型输出特殊标记指示工具调用。项目通过归一化层和解析器将模型输出转换为确定性执行。Agent.runAgent循环将内部模型消息与用户可见的聊天消息分离：用户输入添加到chatMessages，流式生成助手回复，解析工具调用并执行，结果反馈回模型，重复直至无工具调用。
**数据持久化**
状态按生命周期分割：会话状态保存在后台内存中，工具偏好使用chrome.storage.local，语义历史向量使用IndexedDB，提取的页面内容缓存在后台。
**构建与打包** 使用Vite的多入口构建，确保每个运行时对应一个工件，并放在manifest期望的位置。
**总结** 清晰的关注点分离是项目的核心：后台拥有状态和模型执行，UI界面保持轻薄，内容脚本处理页面访问。相同的架构可以扩展到弹出式、侧边栏甚至混合UI场景。