Come Utilizzare Transformers.js in un'estensione Chrome

Di recente, abbiamo rilasciato una demo di estensione del browser Transformers.js alimentata da Gemma 4 E2B per aiutare gli utenti a navigare nel web. Durante la costruzione, abbiamo incontrato diverse osservazioni pratiche sui tempi di esecuzione di Manifest V3, il caricamento dei modelli e la messaggistica che valgono la pena di condividere.

Questa guida è per sviluppatori che desiderano eseguire funzionalità di intelligenza artificiale locali in un'estensione Chrome con Transformers.js sotto le restrizioni di Manifest V3. Alla fine, gli sviluppatori avranno la stessa architettura utilizzata in questo progetto: un servizio di lavoro in background che ospita i modelli, un pannello laterale di chat UI e un copione di contenuto per azioni a livello di pagina.

Introduzione a Manifest V3

Se Manifest V3 è nuovo per te, leggi questo breve panorama prima: Cosa è Manifest V3?. In MV3, la tua architettura inizia in public/manifest.json. Questo progetto definisce tre punti di ingresso:

I punti di ingresso sono:

• Il servizio di lavoro in background anche gestisce chrome.action.onClicked per aprire il pannello laterale per la scheda attiva.
• Un punto di ingresso correlato è un popup che può essere definito con action.default_popup e funziona bene per azioni rapide.

La chiave decisione di design è quella di mantenere un'orchestrazione pesante in background e mantenere la logica dell'interfaccia utente/pagina sottile.

Separazione delle preoccupazioni

Una delle conseguenze pratiche di questa divisione è che la storia della conversazione vive anche in background (Agent.chatMessages): l'interfaccia utente invia eventi come AGENTGENERATETEXT, il background aggiunge il messaggio, esegue l'inferenza e quindi emette MESSAGES_UPDATE indietro al pannello laterale.

Questa divisione evita carichi di modelli duplicati, mantiene l'interfaccia utente responsiva e rispetta i confini di sicurezza di Chrome intorno all'accesso al DOM.

Messaggistica

Una volta separate le preoccupazioni, la messaggistica diventa la spina dorsale. In questo progetto, tutti i messaggi sono tipizzati tramite enum in src/shared/types.ts.

La regola di orchestrazione è semplice: il background è il coordinatore unico; il pannello laterale e il copione di contenuto sono lavoratori specializzati che richiedono azioni e visualizzano i risultati.

Ruoli dei modelli

In src/shared/constants.ts, questa estensione utilizza due ruoli di modello:

• Gemma 4 gestisce la logica strumento/decisioni, mentre MiniLM genera incorporamenti di vettori per la ricerca di similarità semantica in askwebsite e findhistory.

La divisione è intenzionale: Gemma 4 gestisce la logica strumento/decisioni, mentre MiniLM genera incorporamenti di vettori per la ricerca di similarità semantica.

Caricamento dei modelli

Tutte le inferenze vengono eseguite in background (src/background/background.ts):

Ciò fornisce un unico host di modelli per tutte le schede/sessioni, evita l'uso di memoria duplicato e mantiene l'interfaccia utente del pannello laterale responsiva. Poiché i modelli vengono caricati dal servizio di lavoro in background, gli artefatti vengono memorizzati nella cache sotto l'origine dell'estensione (chrome-extension://) invece che sotto le origini del sito web, il che fornisce una cache condivisa per l'intera installazione dell'estensione.

Ciclo di vita di Manifest V3

Nota sul ciclo di vita di MV3: i servizi di lavoro possono essere sospesi e riavviati, quindi lo stato del runtime del modello dovrebbe essere trattato come recuperabile e re-inizializzato quando necessario.

Permessi e privacy

I permessi e la privacy fanno parte dell'architettura, non di una casella di controllo alla fine. In questo progetto, public/manifest.json chiede i permessi per il pannello laterale, l'archiviazione, la gestione degli script e le schede, più i permessi dell'host per http(s):///:

Perché mantenere questo limite: i permessi definiscono la fiducia dell'utente e il rischio di revisione del Chrome Web Store. Richiedere solo ciò che le tue funzionalità necessitano effettivamente e dichiarare chiaramente che l'inferenza viene eseguita localmente nel runtime dell'estensione in modo che gli utenti capiscano dove vengono elaborati i loro dati.

Normalizzazione e parsing

Prima del ciclo di esecuzione, aiuta a capire come funziona la chiamata degli strumenti del modello (la base di ogni flusso di lavoro agente). Si passano messaggi più uno schema di strumento (nome, descrizione e parametri), e Transformers.js formatta il prompt effettivo da quegli input utilizzando il modello del template di chat. Poiché i template di chat sono specifici del modello, il formato esatto della chiamata dello strumento dipende dal modello utilizzato.

Con template di Gemma-4, il modello emette un blocco di token di chiamata speciale quando decide di chiamare uno.

Questo è esattamente il motivo per cui questo progetto ha un livello di normalizzazione (webMcp) e un parser (extractToolCalls): l'output del modello deve essere convertito in esecuzioni di strumenti deterministici.

src/background/agent/webMcp.tsx normalizza gli strumenti dell'estensione in una forma amichevole per il modello:

Gli strumenti di esempio includono getopentabs, gototab, openurl, closetab, findhistory, askwebsite e highlightwebsiteelement.

Collocazione dello stato

La collocazione dello stato è un'altra decisione architettonica che conta molto in MV3. In questa implementazione, lo stato è diviso per ciclo di vita e modello di accesso:

Come descritto nella sezione 1.2, mantenere la storia della conversazione in background fornisce uno stato canonico attraverso gli aggiornamenti dell'interfaccia utente. Ciò mantiene lo stato a breve termine in memoria, le impostazioni durevoli nell'archiviazione dell'estensione e i dati di recupero pesanti in un database locale.

Configurazione della compilazione

Non è necessario un setup di compilazione complesso, ma MV3 richiede output prevedibili per ogni runtime.

L'obiettivo è semplice: un artefatto per ogni punto di ingresso Chrome, nel luogo esatto in cui public/manifest.json si aspetta.

Scelta architettonica

La scelta architettonica che sblocca questo intero progetto è la chiara separazione delle preoccupazioni: il background possiede l'orchestrazione e l'esecuzione del modello, le superfici dell'interfaccia utente rimangono sottili e i copioni di contenuto gestiscono l'accesso alla pagina.

Questo progetto utilizza un pannello laterale, ma lo stesso approccio funziona per altri