Un polyfill sperimentale per l'API Prompt

Thomas Steiner

Pubblicato: 14 maggio 2026

Con l'API Prompt in Chrome, puoi interagire con un LLM utilizzando un'API browser di alto livello su window.LanguageModel. Tuttavia, il supporto è ancora limitato e l'implementazione è un processo complesso.

Browser	Sistema operativo supportato	Sistema operativo non supportato	Posizione
Chrome	Windows, macOS, Linux, ChromeOS (Chromebook Plus)	Android, iOS	✅ Supportato
Edge	Windows, macOS	Android, iOS	✅ Supportato
Safari	—	—	📋 Posizione decisa
Firefox	—	—	📋 Posizione decisa

Allo stesso tempo, gli sviluppatori che partecipano al programma di anteprima iniziale hanno espresso il loro entusiasmo per l'API Prompt. La disponibilità dell'API pone una sfida di compatibilità per il futuro prevedibile.

Soluzione

Per questo motivo, stiamo rilasciando un polyfill dell'API Prompt conforme alle specifiche sperimentale (vedi il codice sorgente su GitHub) che implementa con precisione l'API Prompt su provider di backend cloud configurabili e anche su un provider di backend locale sotto forma di Transformers.js.

Nota: per l'utilizzo in produzione, ti consigliamo di utilizzare direttamente l'SDK ibrido Firebase AI Logic.

Utilizzare il polyfill

Per utilizzare il polyfill:

1. Scarica la polyfill da npm:

   npm install prompt-api-polyfill
   

2. Scegli se utilizzare un provider di backend cloud o un provider di backend locale:

   • Provider di backend cloud: i dati utente vengono inviati al cloud per l'elaborazione remota, ma non devi attendere che sia disponibile un modello locale. Sei responsabile di eventuali costi sostenuti in base alle informazioni sui prezzi del tuo provider cloud.
   • Provider di backend locale: i dati utente rimangono nel browser e vengono elaborati localmente, ma devi scaricare un modello che, a differenza della vera API Prompt, non può essere condiviso tra origini diverse. L'elaborazione locale non comporta costi.

Backend cloud

Scegli tra uno dei backend cloud e ottieni una chiave API (e eventuali credenziali aggiuntive) per il tuo provider di backend.

Una volta ottenuta la chiave API, inserisci i dettagli nel file di configurazione .env.json. Se non specifichi un modelName, il polyfill utilizzerà il modello predefinito di ogni backend, ma se lo fai, puoi selezionare uno dei modelli supportati di ogni backend.

{
  "apiKey": "y0ur-Api-k3Y",
  "modelName": "model-name"
}

Avviso: l'SDK ibrido Firebase AI Logic con App Check è il modo più sicuro per eseguire il backup dell'API Prompt. Solo App Check protegge la tua chiave API da utilizzi non autorizzati. Assicurati di non esporre direttamente le chiavi API Gemini o OpenAI.

Backend locale

Se decidi di utilizzare un fornitore di backend locale basato su Transformers.js, ti serve solo una chiave API fittizia. Tuttavia, puoi configurare il dispositivo che deve essere utilizzato da Transformers.js. Scegli "webgpu" per le massime prestazioni e "wasm" per la massima compatibilità. Se vuoi, puoi modificare le impostazioni predefinite. Scegli un altro modello dal catalogo di modelli compatibili di Hugging Face. Per alcuni modelli, puoi scegliere tra diverse quantizzazioni utilizzando il parametro dtype.

{
  "apiKey": "dummy",
  "device": "webgpu",
  "dtype": "q4f16",
  "modelName": "onnx-community/gemma-3-1b-it-ONNX-GQA"
};

Configura il polyfill

Con il file di configurazione in posizione, ora puoi iniziare a utilizzare il polyfill nella tua app.

1. Importa il file di configurazione e assegnalo a una variabile globale con un nome appropriato, dove $BACKEND è il backend scelto: window.$BACKEND_CONFIG.
2. Utilizza un'importazione dinamica per caricare il polyfill solo quando il browser sottostante non lo supporta.
3. Chiama le funzioni dell'API Prompt.

import config from './.env.json' with { type: 'json' };

// Set $BACKEND_CONFIG to select a backend
window.$BACKEND_CONFIG = config;

if (!('LanguageModel' in window)) {
  await import('prompt-api-polyfill');
}

const session = await LanguageModel.create({
  expectedInputs: [{type: 'text', languages: ['en']}],
  expectedOutputs: [{type: 'text', languages: ['en']}],
});
await session.prompt('Tell me a joke!');

Il polyfill supporta l'output strutturato (ad eccezione del backend Transformers.js), gestisce l'input multimodale (ad eccezione del backend OpenAI che non supporta audio e immagini insieme, solo separatamente) ed è testato rispetto alla suite completa di test della piattaforma web per LanguageModel.

Per ulteriori informazioni di base e dettagliate sull'utilizzo, nonché sul codice sorgente, consulta il file README nel repository GitHub.

Differenza rispetto all'API Prompt del browser

Se il polyfill è supportato da modelli cloud, alcuni dei vantaggi dell'esecuzione lato client non sono più applicabili. In particolare, non puoi più garantire il trattamento locale dei dati sensibili, anche se le norme sulla privacy del tuo fornitore di backend rimangono valide. Inoltre, l'app non può più utilizzare l'AI quando l'utente è offline. Per sapere se sei online o offline, puoi ascoltare gli eventi corrispondenti.

window.addEventListener("offline", (e) => {
  console.log("offline");
});

window.addEventListener("online", (e) => {
  console.log("online");
});

Se l'inferenza AI viene eseguita su un modello nel cloud, non è necessario scaricare un modello locale. Il polyfill simula gli eventi downloadprogress, quindi per la tua app sembrerà che il modello integrato sia già stato scaricato, il che significa che ci saranno due eventi, uno con un valore loaded di 0 e uno con 1, come richiesto dalle specifiche.

Con l'inferenza basata sul cloud, a differenza dell'inferenza on-device, è possibile che si verifichino costi quando chiami le API dal provider di backend che preferisci. Controlla le informazioni sui prezzi, ad esempio quelle dell'API Gemini. Se conosci il costo per token, puoi utilizzare le informazioni contextUsage dell'API Prompt per calcolare il costo.

const COST_PER_TOKEN = 123;
const COST_LIMIT = 456;

let costSoFar = 0;

const session = await LanguageModel.create(options);

/…/

if (costSoFar < COST_LIMIT) {
  await session.prompt('Tell me a joke.');
  costSoFar = session.contextUsage * COST_PER_TOKEN;
} else {
  // Show premium AI plan promo.
}

Quando chiami un'API cloud direttamente da un'app web o mobile (ad esempio, le API che consentono l'accesso a modelli di AI generativa), la chiave API è vulnerabile all'abuso da parte di client non autorizzati. Per proteggere queste API, se utilizzi l'SDK ibrido Firebase AI Logic, devi utilizzare Firebase App Check per verificare che tutte le chiamate API in entrata provengano dalla tua app effettiva. Con alcuni provider di servizi cloud come Google, puoi anche applicare controlli rigorosi dell'origine per assicurarti che solo i siti web consentiti possano utilizzare l'API.

Anziché i limiti dell'API Prompt, ad esempio per quanto riguarda il contextWindow della sessione, si applicano i limiti del fornitore di backend. Per contextWindow, questi limiti sono in genere molto più elevati rispetto a quelli sul dispositivo e puoi elaborare quantità maggiori di dati nel cloud, quindi, anche se devi essere consapevole della differenza, in pratica è improbabile che si verifichino problemi.

Crea il tuo backend

Per aggiungere il tuo provider di backend:

Estendi la classe di backend di base

Crea un nuovo file nella directory backends/, ad esempio backends/custom-backend.js. Devi estendere la classe PolyfillBackend e implementare i metodi principali che soddisfano l'interfaccia prevista.

import PolyfillBackend from './base.js';
import { DEFAULT_MODELS } from './defaults.js';

export default class CustomBackend extends PolyfillBackend {
  constructor(config) {
    // config typically comes from a window global (e.g., window.CUSTOM_CONFIG)
    super(config.modelName || DEFAULT_MODELS.custom.modelName);
  }

  // Check if the backend is configured (e.g., API key is present), if given
  // combinations of modelName and options are supported, or, for local model,
  // if the model is available.
  static availability(options) {
    return window.CUSTOM_CONFIG?.apiKey ? 'available' : 'unavailable';
  }

  // Initialize the underlying SDK or API client. With local models, use
  // monitorTarget to report model download progress to the polyfill.
  createSession(options, sessionParams, monitorTarget) {
    // Return the initialized session or client instance
  }

  // Non-streaming prompt execution
  async generateContent(contents) {
    // contents: Array of { role: 'user'|'model', parts: [{ text: string }] }
    // Return: { text: string, usage: number }
  }

  // Streaming prompt execution
  async generateContentStream(contents) {
    // Return: AsyncIterable yielding chunks
  }

  // Token counting for quota/usage tracking
  async countTokens(contents) {
    // Return: total token count (number)
  }
}

Registra il backend

Il polyfill utilizza una strategia di "priorità della prima corrispondenza" basata sulla configurazione globale. Devi registrare il backend nel file prompt-api-polyfill.js aggiungendolo all'array statico #backends:

// prompt-api-polyfill.js
static #backends = [
  // ... existing backends
  {
    config: 'CUSTOM_CONFIG', // The global object to look for on `window`
    path: './backends/custom-backend.js',
  },
];

Impostare un modello predefinito

Definisci l'identità del modello di riserva in backends/defaults.js. Viene utilizzato quando un utente inizializza una sessione senza specificare un modelName specifico.

// backends/defaults.js
export const DEFAULT_MODELS = {
  // ...
  custom: 'custom-model-pro-v1',
};

Attivare lo sviluppo e i test locali

Il progetto utilizza uno script di rilevamento (scripts/list-backends.js) per generare matrici di test. Per includere il nuovo backend nel test runner, crea un file .env-[name].json (ad esempio .env-custom.json) nella directory principale:

{
  "apiKey": "your-api-key-here",
  "modelName": "custom-model-pro-v1"
}

Verifica con i test della piattaforma web (WPT)

Il passaggio finale consiste nel garantire la conformità. Poiché il polyfill è basato sulle specifiche, qualsiasi nuovo backend deve superare i test ufficiali (o provvisori) della piattaforma web:

npm run test:wpt

Questo passaggio di verifica garantisce che il backend gestisca elementi come AbortSignal, prompt di sistema e formattazione della cronologia esattamente come previsto dalla specifica dell'API Prompt.

Conclusione

Il polyfill ti aiuta a utilizzare l'API Prompt su tutte le piattaforme e i dispositivi. Se codifichi in base all'API ben definita dell'API Prompt, diventi più indipendente dai fornitori di servizi cloud e rimani il più vicino possibile alla piattaforma.

Sui dispositivi compatibili che supportano l'API Prompt, il polyfill non viene nemmeno caricato, quindi gli utenti non devono scaricare codice che non verrà eseguito. Se hai un feedback o riscontri un bug, apri un problema su GitHub. Buon lavoro con i prompt!