Hugging Face ha pubblicato una guida dettagliata su come costruire un’estensione Chrome che esegue modelli AI direttamente nel browser, senza server esterni, usando Transformers.js e Manifest V3 (MV3). Il progetto di riferimento è una browser assistant basata su Gemma 4 E2B, open source e già disponibile sul Chrome Web Store. Vediamo in dettaglio l’architettura e le scelte tecniche che rendono fattibile questo approccio.
Perché AI locale in un’estensione?
L’inferenza locale porta vantaggi concreti: nessun dato dell’utente inviato a server esterni, latenza ridotta dopo il download iniziale del modello, funzionamento offline. Il limite storico era la complessità di integrare modelli ONNX direttamente in un’estensione browser. Transformers.js risolve questo problema esponendo un’API familiare (ispirata alla libreria Python di HuggingFace) che gira interamente nel browser tramite WebAssembly e WebGPU.
Architettura MV3: tre contesti, tre ruoli
Manifest V3 impone un’architettura a contesti separati, ognuno con accesso e ciclo di vita differenti. Il progetto usa tre entry point distinti:
- Background service worker (
background.ts): il piano di controllo. Gestisce il ciclo di vita dell’agente, l’inizializzazione dei modelli, l’esecuzione dei tool e i servizi condivisi come feature extraction. I modelli Transformers.js vengono caricati e mantenuti qui. - Side panel (
sidebar/): il layer di interazione con l’utente. Chat input/output, streaming degli aggiornamenti, controlli di setup. - Content script (
content.ts): il bridge con la pagina web. Estrae contenuto dal DOM e gestisce l’evidenziazione di elementi.
La regola di design è chiara: orchestrazione pesante nel background, UI e logica di pagina leggeri. Questo evita di caricare il modello più volte, mantiene l’interfaccia reattiva e rispetta i confini di sicurezza di Chrome.
Contratto di messaggistica tipato
Con contesti separati, la comunicazione avviene tramite messaggi. Il progetto li tipizza con enum in src/shared/types.ts:
// Side panel verso background
enum BackgroundTasks {
CHECK_MODELS,
INITIALIZE_MODELS,
AGENT_GENERATE_TEXT,
AGENT_GET_MESSAGES,
AGENT_CLEAR,
EXTRACT_FEATURES
}
// Background verso side panel
enum BackgroundMessages {
DOWNLOAD_PROGRESS,
MESSAGES_UPDATE
}
// Background verso content script
enum ContentTasks {
EXTRACT_PAGE_DATA,
HIGHLIGHT_ELEMENTS,
CLEAR_HIGHLIGHTS
}
Il flusso tipico è: la side panel invia AGENT_GENERATE_TEXT, il background aggiunge il messaggio alla conversazione, esegue l’inferenza, poi emette MESSAGES_UPDATE alla side panel che ri-renderizza.
Integrazione di Transformers.js: dove gira l’inferenza
L’estensione usa due modelli con ruoli distinti, definiti in src/shared/constants.ts:
- Text generation (LLM):
onnx-community/gemma-4-E2B-it-ONNX, formatoq4f16– responsabile delle risposte chat e dell’esecuzione dell’agente. - Feature extraction (embedding): un modello separato per estrarre vettori da testi di pagina, usato per operazioni semantiche.
Entrambi i modelli vengono inizializzati e cachati nel background service worker. Il download avviene al primo avvio e i pesi rimangono nella cache del browser (via Cache API), così le sessioni successive partono istantaneamente. Il progresso del download viene trasmesso alla side panel tramite l’evento DOWNLOAD_PROGRESS.
Agent loop e tool calling
L’estensione implementa un loop agente completo. La classe Agent gestisce la cronologia dei messaggi e il ciclo di ragionamento:
// Flusso semplificato di Agent.runAgent
while (true) {
const response = await model.generate(chatMessages);
if (response.hasToolCall) {
const toolResult = await executeTool(response.toolCall);
chatMessages.push({ role: "tool", content: toolResult });
} else {
// Risposta finale
break;
}
}
I tool disponibili includono EXTRACT_PAGE_DATA (estrae il testo dalla pagina corrente via content script) e HIGHLIGHT_ELEMENTS (evidenzia elementi nel DOM). L’interfaccia dei tool è definita con schema JSON per permettere al modello di invocarli correttamente.
Build e packaging: Vite e MV3
Il progetto usa Vite per il build, con configurazione custom per generare entry point separati per background, side panel e content script. I modelli ONNX non sono inclusi nel bundle dell’estensione (sarebbero troppo grandi), ma vengono scaricati da Hugging Face Hub al primo avvio.
Un dettaglio pratico importante: i service worker MV3 possono essere terminati dal browser in qualsiasi momento quando inattivi. Bisogna gestire la persistenza dello stato (conversazione, modelli inizializzati) in modo da riprendere correttamente al risveglio del worker. Il progetto usa chrome.storage.session per lo stato effimero e chrome.storage.local per i dati persistenti tra sessioni.
Considerazioni pratiche prima di adottare questo approccio
Prima di replicare questa architettura in un progetto reale, vale la pena considerare alcune limitazioni:
- Dimensione modello: Gemma 4 E2B in q4f16 pesa diversi gigabyte. Il download iniziale richiede una connessione affidabile e spazio disco significativo nel profilo Chrome.
- Compatibilità hardware: le prestazioni variano molto tra macchine. Su hardware senza GPU decente, l’inferenza può essere lenta anche con quantizzazione aggressiva.
- Ciclo di vita service worker: Chrome può terminare il background worker dopo 5 minuti di inattività. Gestire il riavvio e la reinizializzazione del modello è parte non banale dell’implementazione.
- Review del Chrome Web Store: le estensioni con funzionalità AI vengono esaminate più attentamente; documentare chiaramente cosa fa il modello e dove girano i dati accelera il processo di approvazione.
Conclusione
L’architettura descritta da HuggingFace è solida e dimostra che eseguire AI locale in un’estensione Chrome è fattibile oggi con Transformers.js. Il codice sorgente dell’estensione Gemma 4 Browser Assistant è disponibile su GitHub come riferimento completo, con implementazione reale di tool calling, streaming e gestione del ciclo di vita MV3. Per chi vuole portare funzionalità AI nelle proprie estensioni senza dipendere da API esterne, questo progetto è un ottimo punto di partenza.
Fonte: How to Use Transformers.js in a Chrome Extension – Hugging Face Blog, 23 aprile 2026