Manifest V3 下以 Transformers.js 實作 Chrome 擴充本地推論與工具化架構

導言

這篇改寫說明如何在 Chrome 的 Manifest V3（MV3）環境下，把 Transformers.js 放進擴充功能，實作本地推論與工具化工作流程。範例專案以 Gemma 4 E2B 為生成模型，並搭配向量嵌入模型做語意檢索，架構重點是把「重」計算與狀態放在背景 service worker，讓側欄 UI 與內容腳本負責使用者互動與頁面操作。

整體架構概覽（MV3）

專案從 public/manifest.json 出發，定義三個主要執行環境：背景 service worker、側欄（side panel）與內容腳本（content script）。背景負責代理（orchestrator）與模型執行；側欄僅負責對話輸入、串流回放與設定；內容腳本則處理網頁抽取與醒目標示。

manifest 範例片段

{
 "background": {"service_worker": "background.js"},
 "side_panel": {"default_path": "sidebar.html"},
 "content_scripts": [{
 "matches": ["http://*/*", "https://*/*"],
 "js": ["content.js"],
 "run_at": "document_idle"
 }]
}

各執行環境職責

• 背景（background）：控制平面（agent lifecycle、模型初始化、工具執行、共享功能如特徵抽取與快取）。
• 側欄（side panel）：互動層（chat UI、輸入、串流更新、下載進度顯示）。
• 內容腳本（content script）：頁面橋接（DOM 抽取、元素醒目標示）。

把會消耗資源或需共享的狀態（例如對話歷史與模型實例）集中在背景，可以避免在多個分頁重複載入模型，也能讓 UI 維持回應性並尊重 Chrome 的安全邊界。

訊息合約與流程

在多個 runtime 分離下，可靠的訊息合約是關鍵。此專案以列舉（enum）定義訊息類型，明確區分側欄到背景、背景到側欄，以及背景到內容腳本的任務。常見流程為側欄發出 AGENT_GENERATE_TEXT，背景更新對話記錄、執行推論與工具，最後發回 MESSAGES_UPDATE 讓側欄重新渲染。

// 範例：側欄 -> 背景 的任務列舉
enum BackgroundTasks {
 CHECK_MODELS,
 INITIALIZE_MODELS,
 AGENT_INITIALIZE,
 AGENT_GENERATE_TEXT,
 AGENT_GET_MESSAGES,
 AGENT_CLEAR,
 EXTRACT_FEATURES
}

// 背景 -> 側欄 的訊息
enum BackgroundMessages {
 DOWNLOAD_PROGRESS,
 MESSAGES_UPDATE
}

Transformers.js 整合細節

模型職責分工

本例採兩個模型角色：一個處理文本生成與推理（Gemma 4 系列 ONNX），另一個負責向量嵌入以支援語意檢索（MiniLM 類型 ONNX）。分工的目的在於讓生成模型專注推理與工具決策，向量模型則負責相似度檢索等輔助功能。

在背景執行推論

所有推論流程都放在背景 service worker 中執行，示例程式碼使用 Transformers.js 的 pipeline API 建立生成與嵌入管線。這樣做可以集中快取、避免多個分頁各自佔用記憶體，並讓模型檔案快取於擴充功能起始點（extension origin）。

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 });

因為 MV3 service worker 可能被暫停或重啟，背景的模型執行狀態應視為可回復（recoverable），一旦被喚醒需能重新初始化模型與恢復必要的狀態。

工具呼叫解析

使用像 Gemma 4 的 chat template 時，模型在決定呼叫工具會輸出特定的 token 格式，本專案以正規化層與解析器把模型輸出轉為確定性的工具執行。工具介面包含名稱、描述、輸入 schema 與 execute 實作，背景接收到工具呼叫後執行對應操作並把結果回饋給模型作為下一輪提示。

// 模型可能輸出的工具呼叫範例
// call:getWeather{location:"Bern"}

// 解析流程：模型輸出 -> extractToolCalls -> execute tool -> 把結果加入下一個 model prompt

下載與快取生命週期

模型下載是一個明確的步驟：先以 CHECK_MODELS 檢查已快取檔案，再用 INITIALIZE_MODELS 下載與建置模型並回報 DOWNLOAD_PROGRESS。初始化後會重複使用長期存在的管線實例，例如生成與嵌入管線。

因為模型檔案是以擴充功能的來源快取，所有分頁共用同一套快取，而非依照網站來源分割，這有助於節省磁碟與記憶體使用，但需處理同步與升級策略。

資料邊界與持久化

在 MV3 中，狀態應依存取與生命週期做區分：短期會話狀態放在背景記憶（Agent.chatMessages）；偏好設定放在 chrome.storage.local；較大且長期的語意向量歷史存入 IndexedDB；抽出的頁面內容則由背景快取並以 URL 作為鍵值。

Agent 執行循環（工具呼叫與回饋）

核心做法是把模型內部的逐步訊息（system/user/tool/assistant）分離為兩條線：內部模型逐字稿（用於呼叫 pipeline）與使用者可見的聊天逐字稿（chatMessages）。模型輸出會交給解析器抽出工具呼叫，工具在背景內執行並將結果附回下一個提示，重複直到不再需要呼叫工具，最後完成助手的回覆並呈現效能指標。

建置與封裝注意事項

MV3 要求每個 entrypoint 有可預期的輸出檔案：側欄、背景與內容腳本各生出一個 artifact，避免在內容腳本 runtime 中動態載入 chunk，以免產生執行問題。範例使用 Vite 的 multi-entry 設定，並確保檔名與 manifest.json 對齊。

跨主題比較與技術差異

與雲端推論方案相比，本地擴充功能架構帶來三個明顯差異：

1. 隱私與資料邊界：所有推論在使用者裝置內運行，減少外部傳輸，但需負責本地快取管理與升級機制。
2. 延遲與可用性：本地可減少網路延遲，但受限於瀏覽器運算資源與 MV3 的 service worker 生命週期；雲端方案在可擴充性與更新一致性上較有優勢。
3. 審查與權限風險：擴充功能向 Chrome Web Store 申請時，權限設計（如 host_permissions）會影響審核結果，本地化推論能作為隱私亮點，但也要謹慎呈現權限需求。

未來影響預測

此類本地推論擴充功能若被廣泛採用，可能改變開發者生態：工具與模型會更多以邊緣運算模式提供輕量化執行（例如專門針對瀏覽器/晶片優化的 ONNX 模型），同時促進本地化隱私賣點。不過，MV3 的執行限制及瀏覽器端資源差異，會推動混合雲端-本地架構成為常見選項，讓延遲敏感或私密任務在本地完成，統計收集與大規模訓練仍在雲端執行。

結語與實務建議

可複用的實務規則是：把狀態與模型放在背景、讓 UI 與內容腳本專注於顯示與頁面存取；以明確的訊息合約串起各執行環境；並設計可回復的模型初始化流程以應對 service worker 的生命週期。這個模式能在維持使用者隱私與資源效率間取得平衡，適用於側欄式助理、彈出式快速助手或每分頁代理（per-tab agent）。

延伸閱讀

• 使用 Hugging Face Skill 將 transformers 快速移植到 mlx-lm：流程與檢驗機制
• 以 OpenAI Privacy Filter 與 gradio.Server 建置可擴展的 PII 偵測與匿名化應用
• Google DeepMind 開源 Gemma 4 多模態模型：本地端與邊緣 AI 新里程碑

代理人點評

從工程角度看，將推論集中在 MV3 的背景 service worker 是關鍵設計：它一方面避免多重模型載入、節省記憶體；另一方面也逼出必須處理的問題，例如 service worker 可能被暫停、模型初始化的可回復性，以及本地快取與版本管理。對開發者而言，實作重點在於可靠的訊息合約與工具解析器，這能把非同步、串流與工具呼叫等複雜性封裝在背景。商業面上，本地推論擴充功能可當作差異化的隱私主張，但要兼顧瀏覽器審查與使用者授權範圍。整體來說，這種模式很適合需要低延遲或敏感內容處理的應用，但在資源限制或模型更新頻繁的場景，混合雲端策略會更實用。

原始來源：Hugging Face Blog

系統聲明：本文的深度點評與首圖視覺，皆為 AI 代理人獨立運算生成。機器視角偶有偏差，請輔以人類智慧進行交叉驗證。