如何在 Chrome 擴充功能中使用 Transformers.js:Manifest V3 架構指南
How to Use Transformers.js in a Chrome Extension
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 的核心架構。
- 即時擴充功能:Chrome Web Store
- 原始碼:github.com/nico-martin/gemma4-browser-extension
- 最終成果:在背景執行的 Transformers.js 引擎、側面板聊天介面,以及用於擷取頁面內容和標示重點的內容指令碼。
1) Chrome 擴充功能架構(MV3)
開始前先説明範圍:本文不會深入探討 React UI 層或 Vite 建置設定,而會聚焦於高層架構決策:每種 Chrome 執行環境負責甚麼,以及如何協調各部分。
如果你不熟悉 Manifest V3,請先閲讀這篇簡短概覽: 甚麼是 Manifest V3?。
1.1 執行環境和進入點
在 MV3 中,架構從 public/manifest.json 開始。本項目定義了 3 個進入點:
background.service_worker = background.js,由src/background/background.ts建置。side_panel.default_path = sidebar.html,由src/sidebar/index.html建置。content_scripts[].js = content.js,並設定matches: http(s)://*/*和run_at: document_idle;由src/content/content.ts建置。
背景服務工作者亦會處理 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_MODELSAGENT_INITIALIZE、AGENT_GENERATE_TEXT、AGENT_GET_MESSAGES、AGENT_CLEAREXTRACT_FEATURES
- 背景 -> 側面板(
BackgroundMessages):DOWNLOAD_PROGRESS、MESSAGES_UPDATE
- 背景 -> 內容指令碼(
ContentTasks):EXTRACT_PAGE_DATA、HIGHLIGHT_ELEMENTS、CLEAR_HIGHLIGHTS
協調規則很簡單:背景是唯一協調者;側面板和內容指令碼則是專門的工作單元,負責請求操作及呈現結果。
常見請求流程:
- 側面板傳送
AGENT_GENERATE_TEXT。 - 背景把訊息加入
Agent.chatMessages,並執行模型/工具步驟。 - 背景發出
MESSAGES_UPDATE。 - 側面板根據更新後的訊息清單重新呈現內容。
2) Transformers.js 整合細節
2.1 模型與職責
在 src/shared/constants.ts 中,此擴充功能使用兩種模型角色:
- TextGeneration/LLM:
onnx-community/gemma-4-E2B-it-ONNX(text-generation、q4f16) - VectorEmbeddings:
onnx-community/all-MiniLM-L6-v2-ONNX(feature-extraction、fp32)
刻意把兩者分開: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 下載與快取生命週期
模型生命週期有明確流程:
CHECK_MODELS檢查現有快取內容,並估算剩餘下載大小。INITIALIZE_MODELS下載/初始化模型,並向 UI 發出DOWNLOAD_PROGRESS。- 設定完成後會重用長期存續的實例:
權限和私隱是架構的一部分,不是最後才勾選的項目。本項目在 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)和效能指標。
執行流程:
- 把用戶輸入加入
chatMessages,建立 assistant 訊息佔位符,並開始串流 token。 - 使用
extractToolCalls.ts,把串流/最終模型輸出解析為{ message, toolCalls }。 - 保持用戶可見的 assistant 訊息為純文字,工具調用則在背景執行。
- 把工具結果加入 assistant 工具中繼資料,並將結果作為下一輪提示傳回。
- 重複執行,直至沒有剩餘工具調用,然後完成 assistant 內容及效能指標。
這樣用戶溝通內容便保持清晰,同時在背景保留確定性的工具循環。
4) 資料界線和持久化
在 MV3 中,狀態放置位置也是非常重要的架構決策。本實作會按生命週期和存取模式分開管理狀態:
- 對話狀態:儲存在背景記憶體(
Agent.chatMessages),以便快速逐輪協調。 - 工具偏好設定:使用
chrome.storage.local,讓設定能跨工作階段保存。 - 語義歷史向量:使用 IndexedDB(
VectorHistoryDB)儲存較大型的本機檢索資料。 - 擷取的頁面內容:儲存在背景快取(
WebsiteContentManager),並以目前 URL 作為索引鍵。
如 1.2 節所述,把對話記錄放在背景執行環境,可在 UI 更新之間維持唯一標準狀態。這讓短期狀態留在記憶體、持久設定留在擴充功能儲存空間,而大型檢索資料則放在本機資料庫。
5) 建置和封裝注意事項
你不需要複雜的建置設定,但 MV3 要求為每個執行環境提供可預期的輸出。
- 多入口建置位於
vite.config.ts: - 確保輸出名稱/路徑與 manifest 一致(
sidebar.html、background.js、content.js)。 - 內容指令碼應建置為獨立輸出,以避免執行階段載入程式區塊時出現問題。
目標很簡單:每個 Chrome 進入點各有一個成品,並放在 public/manifest.json 指定位置。
總結
讓整個項目得以實現的架構選擇很明確:清楚劃分職責。背景負責協調和模型執行,UI 層保持精簡,而內容指令碼則處理頁面存取。
本項目使用側面板,但同一做法亦適用於其他架構:
- 以 popup 為主的助理:使用
action.default_popup進行快速互動,並由背景管理對話狀態和模型執行。 - 側面板副駕:在持續顯示的面板中保留長時間對話,背景則負責工具循環和快取。
- 每個分頁各自運行的代理程式:如果每個分頁需要獨立上下文,就在背景為每個
tabId保存一份代理程式狀態。 - 混合 UI(popup + 側面板 + 選項頁):所有 UI 進入點都與同一背景協調者通訊,並重用相同的訊息契約。
實用規則很簡單:決定狀態的存放位置(global、tabId 或網站範圍),讓狀態和模型推論留在背景(本質上作為背景服務),並讓 UI/內容執行環境成為職責明確的用戶端。
來源:Hugging Face Blog · huggingface.co