Transformers.js Gemma 4 浏览器助手

关于此扩展

一款完全运行在浏览器中的端侧 AI 助手，基于 WebGPU 与 Transformers.js 构建。这款 Chrome 扩展提供一个智能体，能够理解自然语言指令，并通过一组专用工具与你的浏览器交互。

所有处理均在你的设备本地完成，数据不会发送到外部服务器，确保完整的隐私保护。

它能做什么？

该 AI 智能体可调用多个工具，帮助你控制和导航浏览器：

标签页管理

智能体可以通过自然语言管理你的浏览器标签页：

• get_open_tabs：列出所有已打开的标签页，包括标题、URL 和描述
• go_to_tab：通过 ID 切换到指定标签页
• open_url：在后台或前台标签页中打开新的 URL
• close_tab：关闭指定标签页

网站交互（RAG）

该扩展使用检索增强生成来理解网页内容并与之交互：

• ask_website：基于语义相似度从当前网页中搜索并提取相关信息。内容脚本会提取结构化内容（标题、段落、列表），使用 all-MiniLM-L6-v2 生成嵌入，并根据你的查询返回最相关的部分。
• highlight_website_element：在页面上以视觉方式高亮特定元素。智能体可以通过高亮并滚动到相关部分，引导你关注特定内容。

浏览历史向量数据库

该扩展维护一个支持语义搜索的历史数据库：

• find_history：使用自然语言查询搜索浏览历史，而不是精确关键词。系统会在 IndexedDB 中存储页面标题、描述和 URL 的向量嵌入，支持基于时间过滤的语义搜索。

安装

前提条件

• 支持 WebGPU 的 Chrome 浏览器（Chrome 113+）
• 支持 WebGPU 的现代 GPU

设置

1. 克隆仓库：

git clone <repository-url>
cd tfjs-agentgemma-extension

2. 安装依赖项：

pnpm install

3. 构建扩展：

pnpm run build

4. 在 Chrome 中加载：
   • 打开 chrome://extensions/
   • 启用“开发者模式”
   • 点击“加载已解压的扩展程序”
   • 选择 dist 文件夹

开发模式

用于需要自动重新构建的活跃开发：

pnpm run dev

使用

1. 点击扩展图标，打开侧边栏面板
2. 首次使用时，模型会自动下载（仅需一次）
3. 加载完成后，即可通过聊天界面与 AI 智能体交互

权限

该扩展需要以下权限：

• sidePanel：显示聊天界面
• activeTab：访问当前标签页内容
• storage：保存设置和模型缓存
• scripting：注入内容脚本
• tabs：用于读取标签页 URL
• host_permissions：访问所有 URL 的网页内容

---

Gemma 4

该扩展使用来自 Hugging Face 的指令微调模型 onnx-community/gemma-4-E2B-it-ONNX：

• 模型卡片：https://huggingface.co/onnx-community/gemma-4-E2B-it-ONNX
• 格式：ONNX（针对浏览器推理优化，结合 Transformers.js + WebGPU 使用）

---

扩展架构

该扩展展示了一种将 Transformers.js 集成到浏览器扩展中的高效架构。设计上将职责划分到三个核心组件中，每个组件都针对特定任务做了优化。

后台脚本：AI 引擎

后台 Service Worker 承载 Transformers.js 模型，作为集中的 AI 引擎。

为什么这样设计：

• 模型常驻加载：模型只需加载一次，并在所有标签页、侧边栏和内容脚本之间共享。这一点至关重要，因为反复加载数 GB 的模型并不现实。
• Service Worker 生命周期：在活跃的 ML 处理期间，Service Worker 可以保持存活，这对于可能需要数秒的推理任务十分关键。
• 集中处理：多个组件都可以向同一个后台工作进程发送推理请求，从而实现高效的资源共享与协调。
• 高负载任务：ML 推理需要较高计算资源。后台上下文专门用于处理这类负载，同时避免阻塞用户交互。

它的作用：加载模型、执行推理、调用工具，并处理特征提取。

侧边栏：用户界面

侧边栏提供持久化的聊天界面，用于与智能体交互。

为什么这样设计：

• 状态持久：与用户点击别处就会关闭的弹出窗口不同，侧边栏在整个浏览会话期间保持打开，能够保留对话上下文。
• 更好的用户体验：为对话提供更充足的屏幕空间，并始终可与网页并行访问。
• 异步通信：通过 chrome.runtime.sendMessage 和 chrome.runtime.onMessage.addListener 与后台脚本通信，实现与 AI 引擎的非阻塞交互。
• 会话连续性：用户可以在提问、浏览标签页之后再回到对话，而不会丢失上下文。

它的作用：

• 展示使用 React 构建的聊天界面
• 将用户消息发送到后台智能体
• 渲染智能体响应和工具执行结果
• 维护对话历史

内容脚本：页面交互

内容脚本在网页上下文中运行，能够直接访问 DOM。

为什么这样做可行：

• DOM 访问：内容脚本是扩展中唯一能够访问并操作网页实际 DOM 的组件，这对 RAG 功能至关重要。
• 恰当的安全边界：在隔离上下文中运行，既保持浏览器安全，又实现强大的页面交互。
• 页面专属操作：每个标签页的内容脚本负责处理对应页面的内容提取和高亮显示。

它的作用：

• 从网页中提取结构化内容（标题、段落、列表）
• 当智能体请求时，高亮显示特定元素
• 将提取的内容发送给后台脚本，用于生成 embedding
• 响应用户对高亮内容的交互

通信流程

User Input (Side Panel)
    ↓
    chrome.runtime.sendMessage
    ↓
Background Script (AI Agent)
    ↓
    Processes with Transformers.js
    ↓
    Executes tools (e.g., ask_website)
    ↓
    chrome.tabs.sendMessage
    ↓
Content Script (if needed)
    ↓
    Extracts/highlights page content
    ↓
    Returns to Background
    ↓
    chrome.runtime.sendMessage
    ↓
Side Panel (displays response)

Transformers.js 的关键优势

该架构尤其适合基于浏览器的机器学习：

1. 资源效率高：模型只需加载一次，推理集中执行
2. 响应式 UI：繁重的机器学习处理不会阻塞界面
3. 可扩展性：可同时处理来自多个标签页的请求
4. 安全性：在启用强大功能的同时，保持浏览器安全模型
5. WebGPU 加速：后台脚本可利用 WebGPU 实现快速推理