Che cos'è l'API Prompt?

L'API Prompt è una proposta sperimentale di piattaforma web del W3C Web Machine Learning Community Group che espone un modello di linguaggio di grandi dimensioni fornito dal browser a JavaScript attraverso un'interfaccia window.LanguageModel. Le pagine creano una sessione con LanguageModel.create(), la configurano facoltativamente con un prompt di sistema, e quindi chiamano prompt() o promptStreaming() per ottenere una risposta.

A differenza della chiamata a un'API LLM ospitata, il modello viene eseguito sul dispositivo dell'utente. Ciò significa che gli input non lasciano mai la macchina, la pagina funziona offline una volta che il modello è memorizzato nella cache, e non ci sono costi per richiesta. In Chrome il modello sottostante è Gemini Nano, ma l'API è intenzionalmente indipendente dal modello in modo che altri browser possano inserire implementazioni diverse.

Una sessione è stateful: tiene traccia della cronologia della conversazione all'interno di una finestra di contesto misurata in token. Quando la finestra si riempie, i messaggi non di sistema più vecchi vengono rimossi automaticamente (si attiva un evento contextoverflow), e puoi ispezionare session.contextUsage e session.contextWindow in qualsiasi momento per vedere quanto spazio rimane.

Descrizione dello strumento

Questo playground è una superficie di chat interattiva collegata a window.LanguageModel. Ti permette di impostare un prompt di sistema, inviare messaggi e guardare il modello trasmettere token in tempo reale. Una barra di avanzamento mostra la disponibilità del modello e l'avanzamento del download, e una barra di utilizzo dei token riporta quanto della finestra di contesto della sessione viene consumato.

La sessione viene creata in modo lazy al primo invio e riutilizzata tra i messaggi finché non modifichi il prompt di sistema, a quel punto viene distrutta e ne viene creata una nuova con le nuove istruzioni.

Funzionalità

  • Risposte in streaming — utilizza promptStreaming() in modo che i token appaiano nella chat man mano che vengono prodotti.
  • Editor del prompt di sistema — definisci un ruolo o un comportamento persistente che condiziona ogni risposta.
  • Pulsante Stop — interrompi un prompt in corso con un AbortController senza smontare la sessione.
  • Utilizzo del contesto in tempo reale — visualizza contextUsage rispetto a contextWindow in modo da poter vedere quando la conversazione sta per traboccare.
  • Disponibilità e avanzamento del download — espone lo stato availability() e gli eventi downloadprogress mentre il modello viene scaricato.

Casi d'uso

  • Provare i prompt localmente — itera sui prompt di sistema e sui pattern few-shot senza pagare per un'API cloud.
  • Testare la fattibilità dell'IA on-device — verifica che l'API Prompt sia disponibile, vedi quanto è grande la finestra di contesto e fai un benchmark della velocità di risposta sul tuo hardware.
  • Bozza sensibile alla privacy — brainstorm o riformula testo che non dovrebbe essere inviato a un server di terze parti.

Requisiti

  • Un browser che implementa l'API Prompt. Chrome 138+ lo espone sperimentalmente; nelle versioni precedenti potrebbe essere necessario abilitarlo tramite chrome://flags/#prompt-api-for-gemini-nano e avere il modello on-device scaricato.
  • Un contesto sicuro (HTTPS o localhost).
  • Un dispositivo che soddisfa i requisiti hardware del modello (spazio su disco sufficiente, RAM e una GPU/CPU supportata). Su dispositivi non supportati availability() restituisce unavailable.
  • Larghezza di banda iniziale per scaricare il modello. Le sessioni successive riutilizzano il modello memorizzato nella cache.

Come funziona

  1. Al montaggio, lo strumento controlla typeof window.LanguageModel. Se assente, un avviso sostituisce l'input della chat.
  2. LanguageModel.availability() riporta uno tra available, downloadable, downloading o unavailable. Il risultato viene mostrato nella barra di avanzamento.
  3. La prima volta che premi Invia, lo strumento chiama LanguageModel.create() con un monitor che trasmette gli eventi downloadprogress all'interfaccia utente. Se è impostato un prompt di sistema, viene passato tramite initialPrompts: [{ role: "system", content: ... }].
  4. Il messaggio dell'utente viene inviato tramite session.promptStreaming(text, { signal }). Lo ReadableStream<string> restituito viene consumato pezzo per pezzo e aggiunto al messaggio dell'assistente.
  5. Dopo ogni risposta, session.contextUsage e session.contextWindow vengono letti e riflessi nella barra di utilizzo dei token.
  6. Premendo Stop si chiama controller.abort(), che rifiuta il flusso in corso con un AbortError mentre la sessione rimane attiva per il prompt successivo.
  7. La modifica del prompt di sistema invalida la sessione memorizzata nella cache: quella esistente viene destroy()-ed e il prossimo invio crea una nuova sessione con le istruzioni aggiornate.

Opzioni spiegate

  • Prompt di sistema — un'istruzione in forma libera passata come primo messaggio con ruolo system. Condiziona tutti i turni successivi. Lasciarlo vuoto crea una sessione senza un messaggio di sistema.
  • Invia / Stop — Invia invia l'input come messaggio user. Stop interrompe la risposta in streaming senza eliminare i messaggi precedenti.
  • Utilizzo dei token — token used / total per la sessione corrente. Quando used si avvicina a total, le coppie utente/assistente più vecchie verranno rimosse al prossimo prompt.
  • Stato del modello — lettura combinata di availability() e downloadprogress. Mentre il modello viene scaricato, la barra si anima e mostra una percentuale.

Limitazioni

  • L'API Prompt è sperimentale. I nomi dei metodi, le opzioni (ad es. inputUsage vs contextUsage) e la semantica degli eventi possono cambiare tra i rilasci di Chrome.
  • La qualità dell'output, la fattualità e il seguire le istruzioni dipendono interamente dal modello fornito dal browser e non sono garantiti.
  • La finestra di contesto è piccola rispetto agli LLM ospitati. Le conversazioni lunghe traboccheranno e elimineranno silenziosamente i turni più vecchi.
  • L'API non è esposta ai web worker e potrebbe richiedere la delega di Permissions Policy (language-model) su iframe cross-origin.
  • Questo strumento intenzionalmente non espone temperature, topK, tool use, input multimodali, output strutturato (responseConstraint) o clonazione di sessione. Fanno parte della specifica ma sono esclusi dal playground per rimanere focalizzati sulla chat semplice.

Domande frequenti

Perché dice che l'API non è supportata? window.LanguageModel è undefined nel tuo browser. Prova l'ultimo Chrome su desktop e, se necessario, abilita il flag dell'API Prompt e attendi che il modello on-device venga scaricato tramite chrome://components.

Perché la prima risposta è lenta? La prima chiamata potrebbe attivare un download del modello (guarda la barra di avanzamento) e un passaggio di creazione della sessione. I prompt successivi riutilizzano la stessa sessione e iniziano a trasmettere quasi immediatamente.

Il mio prompt lascia il dispositivo? No. Il modello viene eseguito localmente. Il tuo testo non viene inviato a nessun server da questo strumento.

Cosa succede quando il contesto si riempie? La sessione attiva un evento contextoverflow e rimuove i turni non di sistema più vecchi per fare spazio. Il prompt di sistema viene preservato.

Perché la modifica del prompt di sistema ha cancellato lo stile di risposta a metà conversazione? La modifica del prompt di sistema distrugge la sessione corrente e ne crea una nuova al prossimo invio. La nuova sessione non ha memoria dei turni precedenti.