跳到正文
Hugging Face Blog·· 2026-04-23精選AI 評分62

如何在 Chrome 擴充功能中使用 Transformers.js:Manifest V3 架構指南

How to Use Transformers.js in a Chrome Extension

AI 導讀

Hugging Face Blog 提供 Transformers.js 在 Chrome Manifest V3 擴充功能中運行本地 AI 的實作指南。範例將模型初始化、推理和工具執行集中在背景 service worker,側邊欄提供聊天介面,content script 負責網頁內容擷取及元素標記。

推薦理由

文章拆解 Manifest V3 擴充功能內模型推理、對話狀態與頁面操作的分工,並説明背景 service worker 如何協調模型載入、工具執行與介面訊息。

正文 · 繁體中文

我們最近推出一款 Transformers.js 示範瀏覽器擴充功能,由 Gemma 4 E2B 驅動,協助用戶瀏覽網頁。

開發過程中,我們發現 Manifest V3 執行環境、模型載入和訊息傳遞方面有幾項值得分享的實用觀察。

適用對象

本指南適合希望在 Manifest V3 限制下,於 Chrome 擴充功能中使用 Transformers.js 執行本機 AI 功能的開發者。

完成後,你會建構出本項目採用的相同架構:託管模型的背景服務工作者、側面板聊天介面,以及執行頁面層級操作的內容指令碼。

本指南會建構甚麼

本指南會參照已發布的擴充功能,並以開源程式碼作為實作藍圖,重建 Transformers.js Gemma 4 Browser Assistant 的核心架構。

1) Chrome 擴充功能架構(MV3)

開始前先説明範圍:本文不會深入探討 React UI 層或 Vite 建置設定,而會聚焦於高層架構決策:每種 Chrome 執行環境負責甚麼,以及如何協調各部分。

如果你不熟悉 Manifest V3,請先閲讀這篇簡短概覽: 甚麼是 Manifest V3?。

1.1 執行環境和進入點

在 MV3 中,架構從 public/manifest.json 開始。本項目定義了 3 個進入點:

背景服務工作者亦會處理 chrome.action.onClicked,為目前分頁開啟側面板。 另一個值得認識的進入點是 popup:你可使用 action.default_popup 定義快顯視窗,適合快速操作。本項目以側面板提供持續聊天功能,但協調模式相同。

1.2 各部分的執行位置

關鍵設計決策是讓繁重的協調工作留在背景執行環境,UI 和頁面邏輯則保持精簡。

  • 背景(src/background/background.ts)是控制平面:負責代理程式生命週期、模型初始化、工具執行,以及特徵擷取等共用服務。
  • 側面板(src/sidebar/*)是互動層:負責聊天輸入/輸出、串流更新及設定控制。
  • 內容指令碼(src/content/content.ts)是頁面橋接層:負責 DOM 擷取和標示重點。

這種劃分的一個實際結果是,對話記錄亦留在背景執行環境(Agent.chatMessages):UI 會傳送 AGENT_GENERATE_TEXT 等事件,背景接着加入訊息、執行推論,然後傳送 MESSAGES_UPDATE 回側面板。

這種分工可避免重複載入模型、維持 UI 流暢回應,亦符合 Chrome 對 DOM 存取的安全界線。

1.3 訊息傳遞契約

各執行環境分開後,訊息傳遞便成為整體架構的骨幹。本項目透過 src/shared/types.ts 中的列舉型別,為所有訊息定義型別。

  • 側面板 -> 背景(BackgroundTasks):
    • CHECK_MODELS、INITIALIZE_MODELS
    • AGENT_INITIALIZE、AGENT_GENERATE_TEXT、AGENT_GET_MESSAGES、AGENT_CLEAR
    • EXTRACT_FEATURES
  • 背景 -> 側面板(BackgroundMessages):
    • DOWNLOAD_PROGRESS、MESSAGES_UPDATE
  • 背景 -> 內容指令碼(ContentTasks):
    • EXTRACT_PAGE_DATA、HIGHLIGHT_ELEMENTS、CLEAR_HIGHLIGHTS

協調規則很簡單:背景是唯一協調者;側面板和內容指令碼則是專門的工作單元,負責請求操作及呈現結果。

常見請求流程:

  1. 側面板傳送 AGENT_GENERATE_TEXT。
  2. 背景把訊息加入 Agent.chatMessages,並執行模型/工具步驟。
  3. 背景發出 MESSAGES_UPDATE。
  4. 側面板根據更新後的訊息清單重新呈現內容。

2) Transformers.js 整合細節

2.1 模型與職責

在 src/shared/constants.ts 中,此擴充功能使用兩種模型角色:

刻意把兩者分開:Gemma 4 負責推理和工具決策,而 MiniLM 則為 ask_website 和 find_history 中的語義相似度搜尋生成向量嵌入。

2.2 推論在哪裡執行

所有推論均在背景執行環境(src/background/background.ts)中進行:

  • 文字生成使用 pipeline("text-generation", ...),並透過新增的 DynamicCache 類別持續啟用 KV Caching
  • 嵌入生成使用 pipeline("feature-extraction", ...),並進行向量正規化

這樣所有分頁/工作階段便共用單一模型宿主,避免重複佔用記憶體,並保持側面板 UI 流暢回應。由於模型從背景服務工作者載入,模型檔案會快取在擴充功能來源(chrome-extension://<extension-id>)下,而非各網站來源,因此整個擴充功能安裝只會共用一份快取。

MV3 生命週期提示:服務工作者可能會暫停並重新啟動,因此模型執行階段狀態應視為可復原,並在有需要時重新初始化。

2.3 下載與快取生命週期

模型生命週期有明確流程:

權限和私隱是架構的一部分,不是最後才勾選的項目。本項目在 public/manifest.json 中要求 sidePanel、storage、scripting 和 tabs 權限,並設定 host_permissions,其值為 http(s)://*/*:

  • sidePanel:開啟和控制側面板體驗所需。
  • storage:跨工作階段保存工具/設定狀態所需。
  • tabs + scripting:分頁感知工具和頁面操作所需。
  • host_permissions 設為 http(s)://*/*:內容擷取和重點標示功能的設計目標是適用於任意網站,因此需要此權限。

為何要限制權限範圍:權限會影響用戶信任及 Chrome Web Store 審核風險。只應申請功能實際所需的權限,並清楚説明推論在擴充功能執行環境中本機進行,讓用戶瞭解其資料在哪裡處理。

3) 代理程式和工具執行循環

3.1 工具調用基礎(為何需要這一層)

在瞭解執行循環前,先理解模型如何調用工具會有所幫助(這是任何智能體工作流程的基礎)。你會傳入訊息和工具結構描述(name、description 和 parameters),Transformers.js 再根據這些輸入,使用模型的聊天範本格式化實際提示。由於聊天範本因模型而異,具體工具調用格式取決於所用模型。使用 Gemma 4 風格的範本時,模型決定調用工具便會輸出一個特殊的工具調用 token 區塊。

import { pipeline } from "@huggingface/transformers";

const generator = await pipeline(
  "text-generation",
  "onnx-community/gemma-4-E2B-it-ONNX",
  {
    dtype: "q4f16",
    device: "webgpu",
  },
);

const messages = [{ role: "user", content: "What's the weather in Bern?" }];

const output = await generator(messages, {
  max_new_tokens: 128,
  do_sample: false,
  tools: [
    {
      type: "function",
      function: {
        name: "getWeather",
        description: "Get the weather in a location",
        parameters: {
          type: "object",
          properties: {
            location: {
              type: "string",
              description: "The location to get the weather for",
            },
          },
          required: ["location"],
        },
      },
    },
  ],
});

生成期間,模型可能會輸出如下內容:

<|tool_call>call:getWeather{location:<|"|>Bern<|"|>}<tool_call|>

因此,本項目需要正規化層(webMcp)和解析器(extractToolCalls):必須把模型輸出轉換為確定性的工具執行。

3.2 本項目的工具介面

src/background/agent/webMcp.tsx 會把擴充功能工具正規化為模型易於使用的形式:

  • name、description、inputSchema、execute

工具例子包括 get_open_tabs、go_to_tab、open_url、close_tab、find_history、ask_website 和 highlight_website_element。

3.3 循環設計(Agent.runAgent)

這裡的核心設計選擇,是分開處理模型內部訊息和麪向 UI 的聊天訊息:

  • 模型內部對話記錄(messages):供 generator(...) 使用的 system/user/tool/assistant 對話輪次。
  • UI 對話記錄(chatMessages):用戶看到的內容,包括串流中的 assistant 文字、工具執行中繼資料(tools)和效能指標。

執行流程:

  1. 把用戶輸入加入 chatMessages,建立 assistant 訊息佔位符,並開始串流 token。
  2. 使用 extractToolCalls.ts,把串流/最終模型輸出解析為 { message, toolCalls }。
  3. 保持用戶可見的 assistant 訊息為純文字,工具調用則在背景執行。
  4. 把工具結果加入 assistant 工具中繼資料,並將結果作為下一輪提示傳回。
  5. 重複執行,直至沒有剩餘工具調用,然後完成 assistant 內容及效能指標。

這樣用戶溝通內容便保持清晰,同時在背景保留確定性的工具循環。

4) 資料界線和持久化

在 MV3 中,狀態放置位置也是非常重要的架構決策。本實作會按生命週期和存取模式分開管理狀態:

  • 對話狀態:儲存在背景記憶體(Agent.chatMessages),以便快速逐輪協調。
  • 工具偏好設定:使用 chrome.storage.local,讓設定能跨工作階段保存。
  • 語義歷史向量:使用 IndexedDB(VectorHistoryDB)儲存較大型的本機檢索資料。
  • 擷取的頁面內容:儲存在背景快取(WebsiteContentManager),並以目前 URL 作為索引鍵。

如 1.2 節所述,把對話記錄放在背景執行環境,可在 UI 更新之間維持唯一標準狀態。這讓短期狀態留在記憶體、持久設定留在擴充功能儲存空間,而大型檢索資料則放在本機資料庫。

5) 建置和封裝注意事項

你不需要複雜的建置設定,但 MV3 要求為每個執行環境提供可預期的輸出。

目標很簡單:每個 Chrome 進入點各有一個成品,並放在 public/manifest.json 指定位置。

總結

讓整個項目得以實現的架構選擇很明確:清楚劃分職責。背景負責協調和模型執行,UI 層保持精簡,而內容指令碼則處理頁面存取。

本項目使用側面板,但同一做法亦適用於其他架構:

  • 以 popup 為主的助理:使用 action.default_popup 進行快速互動,並由背景管理對話狀態和模型執行。
  • 側面板副駕:在持續顯示的面板中保留長時間對話,背景則負責工具循環和快取。
  • 每個分頁各自運行的代理程式:如果每個分頁需要獨立上下文,就在背景為每個 tabId 保存一份代理程式狀態。
  • 混合 UI(popup + 側面板 + 選項頁):所有 UI 進入點都與同一背景協調者通訊,並重用相同的訊息契約。

實用規則很簡單:決定狀態的存放位置(global、tabId 或網站範圍),讓狀態和模型推論留在背景(本質上作為背景服務),並讓 UI/內容執行環境成為職責明確的用戶端。

來源:Hugging Face Blog · huggingface.co