L'API Prompt

Thomas Steiner
Alexandra Klepper
Alexandra Klepper
GitHub Bluesky

Pubblicato: 20 maggio 2025, ultimo aggiornamento: 21 ottobre 2026

Video esplicativo Web Estensioni Chrome Status Intenzione
GitHub Chrome 148 Chrome 138 Visualizza Intent to Ship
GitHub Origin trial Origin trial per i parametri di campionamento Chrome 148 Visualizza Intent to Experiment

Con l'API Prompt, puoi inviare richieste in linguaggio naturale al modello di base in Chrome.

Esistono molti modi per utilizzare l'API Prompt. Ad esempio, potresti creare:

  • Ricerca basata sull'AI: rispondi alle domande in base ai contenuti di una pagina web.
  • Feed di notizie personalizzati: crea un feed che classifica dinamicamente gli articoli con categorie e consenti agli utenti di filtrare i contenuti.
  • Filtri dei contenuti personalizzati. Analizza gli articoli e sfoca o nascondi automaticamente i contenuti in base ad argomenti definiti dall'utente.
  • Creazione di eventi nel calendario. Sviluppa un'estensione di Chrome che estrae automaticamente i dettagli degli eventi dalle pagine web, in modo che gli utenti possano creare voci di calendario in pochi passaggi.
  • Estrazione dei contatti senza problemi. Crea un'estensione che estrae i dati di contatto dai siti web, semplificando per gli utenti il contatto con un'attività o l'aggiunta di dettagli al proprio elenco di contatti.

Queste sono solo alcune delle possibilità e non vediamo l'ora di vedere cosa creerai.

Esamina i requisiti hardware

I seguenti requisiti si applicano agli sviluppatori e agli utenti che utilizzano le funzionalità tramite queste API in Chrome. Altri browser potrebbero avere requisiti operativi diversi.

Le API Language Detector e Translator funzionano in Chrome su computer. Queste API non funzionano sui dispositivi mobili.

L'API Prompt, l'API Summarizer, l'API Writer, l'API Rewriter e l'API Proofreader funzionano in Chrome quando vengono soddisfatte le seguenti condizioni:

  • Sistema operativo: Windows 10 o 11; macOS 13 o versioni successive (Ventura e versioni successive); Linux; o ChromeOS (dalla piattaforma 16389.0.0 e versioni successive) su dispositivi Chromebook Plus. Chrome per Android, iOS e ChromeOS su dispositivi non Chromebook Plus non sono ancora supportati dalle API che utilizzano i foundation model.
  • Spazio di archiviazione: almeno 22 GB di spazio libero sul volume che contiene il tuo profilo Chrome.
  • GPU o CPU: i modelli integrati possono essere eseguiti con GPU o CPU.
    • GPU: rigorosamente più di 4 GB di VRAM.
    • CPU: almeno 16 GB di RAM e almeno 4 core della CPU.
    • Nota: l'API Prompt con input audio richiede una GPU.
  • Rete: dati illimitati o una connessione non a consumo.

Le dimensioni esatte di Gemini Nano possono variare man mano che il browser aggiorna il modello. Per determinare le dimensioni attuali, visita la pagina chrome://on-device-internals.

Utilizza l'API Prompt

L'API Prompt utilizza il modello Gemini Nano in Chrome. Sebbene l'API sia integrata in Chrome, il modello viene scaricato separatamente la prima volta che un'origine utilizza l'API.

"permissions": ["aiLanguageModelOriginTrial"]

Per determinare se il modello è pronto per l'uso, chiama LanguageModel.availability().

const availability = await LanguageModel.availability({
  // The same options in `prompt()` or `promptStreaming()`
});

Per attivare il download e creare un'istanza del modello linguistico, verifica l'attivazione dell'utente. Poi, chiama la funzione create().

const session = await LanguageModel.create({
  monitor(m) {
    m.addEventListener('downloadprogress', (e) => {
      console.log(`Downloaded ${e.loaded * 100}%`);
    });
  },
});

Se la risposta a availability() è stata downloading, ascolta l'avanzamento del download e informa l'utente, poiché il download potrebbe richiedere del tempo.

Crea una sessione

Una volta che l'API Prompt può essere eseguita, crei una sessione con la funzione create().

const session = await LanguageModel.create();

L'oggetto options facoltativo della funzione create() accetta un campo signal, che ti consente di passare un AbortSignal per eliminare la sessione.

const controller = new AbortController();
stopButton.onclick = () => controller.abort();

const session = await LanguageModel.create({
  signal: controller.signal,
});

Parametri di campionamento

Il controllo del campionamento ti consente di ottimizzare il livello di prevedibilità (determinismo) o creatività (varietà) delle risposte del modello. La disponibilità dei parametri di campionamento varia tra la piattaforma web e le estensioni di Chrome:

  • Web: utilizza l'opzione samplingMode, che utilizza valori enum descrittivi anziché numeri non elaborati per regolare la prevedibilità dell'output.
  • Estensioni di Chrome: sono supportati i parametri numerici legacy (topK, temperature) e il metodo LanguageModel.params().

Modalità di campionamento web

Passa l'opzione samplingMode a LanguageModel.create() (o LanguageModel.availability()).

I valori enum samplingMode supportati sono:

  • "most-predictable": determinismo e prevedibilità massimi.
  • "predictable": output più prevedibile con variazioni minime.
  • "slightly-predictable": output leggermente prevedibile.
  • "balanced": un equilibrio tra prevedibilità e creatività (comportamento predefinito tipico).
  • "slightly-creative": output leggermente vario e creativo.
  • "creative": output creativo e variegato.
  • "most-creative": massima variabilità e creatività.
// Available on the web with the Sampling Parameters Origin Trial enabled
const session = await LanguageModel.create({
  samplingMode: 'creative',
});

// The configured sampling mode is exposed on the session instance
console.log(session.samplingMode);
// "creative"

Parametri di campionamento per le estensioni di Chrome

Quando utilizzi l'API Prompt nelle estensioni di Chrome, ogni sessione può comunque essere personalizzata con topK e temperature utilizzando l'oggetto options.

La funzione statica LanguageModel.params() ti informa dei limiti dei parametri predefiniti e massimi del modello linguistico:

  • defaultTopK: il valore top-K predefinito.
  • maxTopK: il valore top-K massimo.
  • defaultTemperature: la temperatura predefinita.
  • maxTemperature: la temperatura massima.
// Only available in Chrome Extensions
const params = await LanguageModel.params();
// {defaultTopK: 3, maxTopK: 128, defaultTemperature: 1, maxTemperature: 2}

// Initializing a new session in extensions must either specify both `topK` and
// `temperature` or neither of them.
const slightlyHighTemperatureSession = await LanguageModel.create({
  temperature: Math.min(params.defaultTemperature * 1.2, params.maxTemperature),
  topK: params.defaultTopK,
});

console.log(slightlyHighTemperatureSession.temperature);
console.log(slightlyHighTemperatureSession.topK);

Aggiungi contesto con i prompt iniziali

Con i prompt iniziali, puoi fornire al modello linguistico il contesto delle interazioni precedenti, ad esempio per consentire all'utente di riprendere una sessione memorizzata dopo il riavvio del browser.

const session = await LanguageModel.create({
  initialPrompts: [
    { role: 'system', content: 'You are a helpful and friendly assistant.' },
    { role: 'user', content: 'What is the capital of Italy?' },
    { role: 'assistant', content: 'The capital of Italy is Rome.' },
    { role: 'user', content: 'What language is spoken there?' },
    {
      role: 'assistant',
      content: 'The official language of Italy is Italian. [...]',
    },
  ],
});

Limita le risposte con un prefisso

Puoi aggiungere un ruolo "assistant", oltre ai ruoli precedenti, per approfondire le risposte precedenti del modello. Ad esempio:

const followup = await session.prompt([
  {
    role: "user",
    content: "I'm nervous about my presentation tomorrow"
  },
  {
    role: "assistant",
    content: "Presentations are tough!"
  }
]);

In alcuni casi, anziché richiedere una nuova risposta, potresti voler precompilare parte del messaggio di risposta del ruolo "assistant". Questo può essere utile per guidare il modello linguistico a utilizzare un formato di risposta specifico. Per farlo, aggiungi prefix: true al messaggio finale del ruolo "assistant". Ad esempio:

const characterSheet = await session.prompt([
  {
    role: 'user',
    content: 'Create a TOML character sheet for a gnome barbarian',
  },
  {
    role: 'assistant',
    content: '```toml\n',
    prefix: true,
  },
]);

Aggiungi input e output previsti

L'API Prompt ha funzionalità multimodali e supporta più lingue. Imposta le modalità e le lingue expectedInputs e expectedOutputs quando crei la sessione.

  • type: modalità prevista.
    • Per expectedInputs, può essere text, image o audio.
    • Per expectedOutputs, l'API Prompt consente solo text.
  • languages: array per impostare la lingua o le lingue previste. L'API Prompt accetta "en", "ja", "es", "de" e "fr". Il supporto per altre lingue è in fase di sviluppo.
    • Per expectedInputs, imposta la lingua del prompt di sistema e una o più lingue previste per i prompt dell'utente.
    • Imposta una o più lingue expectedOutputs.
const session = await LanguageModel.create({
  expectedInputs: [
    { type: "text", languages: ["en" /* system prompt */, "ja" /* user prompt */] }
  ],
  expectedOutputs: [
    { type: "text", languages: ["ja"] }
  ]
});

Potresti ricevere un'eccezione DOMException "NotSupportedError" se il modello rileva un input o un output non supportato.

Funzionalità multimodali

Con queste funzionalità, puoi:

  • Consenti agli utenti di trascrivere i messaggi audio inviati in un'applicazione di chat.
  • Descrivi un'immagine caricata sul tuo sito web da utilizzare in una didascalia o in un testo alternativo.

Dai un'occhiata alla demo Mediarecorder Audio Prompt per l'utilizzo dell'API Prompt con l'input audio e alla demo Canvas Image Prompt per l'utilizzo dell'API Prompt con l'input di immagini.

L'API Prompt supporta i seguenti tipi di input:

Questo snippet mostra una sessione multimodale che prima elabora due elementi visivi (un'immagine Blob e un'immagine HTMLCanvasElement) e chiede all'AI di confrontarli, poi consente all'utente di rispondere con una registrazione audio (come AudioBuffer).

const session = await LanguageModel.create({
  expectedInputs: [
    { type: "text", languages: ["en"] },
    { type: "audio" },
    { type: "image" },
  ],
  expectedOutputs: [{ type: "text", languages: ["en"] }],
});

const referenceImage = await (await fetch("reference-image.jpeg")).blob();
const userDrawnImage = document.querySelector("canvas");

const response1 = await session.prompt([
  {
    role: "user",
    content: [
      {
        type: "text",
        value:
          "Give a helpful artistic critique of how well the second image matches the first:",
      },
      { type: "image", value: referenceImage },
      { type: "image", value: userDrawnImage },
    ],
  },
]);
console.log(response1);

const audioBuffer = await captureMicrophoneInput({ seconds: 10 });

const response2 = await session.prompt([
  {
    role: "user",
    content: [
      { type: "text", value: "My response to your critique:" },
      { type: "audio", value: audioBuffer },
    ],
  },
]);
console.log(response2);

Aggiungi messaggi

L'inferenza potrebbe richiedere un po' di tempo, soprattutto quando si utilizzano prompt con input multimodali. Può essere utile inviare in anticipo prompt predeterminati per popolare la sessione, in modo che il modello possa iniziare l'elaborazione.

Sebbene i initialPrompts siano utili al momento della creazione della sessione, il metodo append() può essere utilizzato in aggiunta ai metodi prompt() o promptStreaming() per fornire prompt contestuali aggiuntivi dopo la creazione della sessione.

Ad esempio:

const session = await LanguageModel.create({
  initialPrompts: [
    {
      role: 'system',
      content:
        'You are a skilled analyst who correlates patterns across multiple images.',
    },
  ],
  expectedInputs: [{ type: 'image' }],
});

fileUpload.onchange = async () => {
  await session.append([
    {
      role: 'user',
      content: [
        {
          type: 'text',
          value: `Here's one image. Notes: ${fileNotesInput.value}`,
        },
        { type: 'image', value: fileUpload.files[0] },
      ],
    },
  ]);
};

analyzeButton.onclick = async (e) => {
  analysisResult.textContent = await session.prompt(userQuestionInput.value);
};

La promessa restituita da append() viene soddisfatta una volta che il prompt è stato convalidato, elaborato e aggiunto alla sessione. La promise viene rifiutata se il prompt non può essere aggiunto.

Passa uno schema JSON

Aggiungi il campo responseConstraint al metodo prompt() o promptStreaming() per passare uno schema JSON come valore. Puoi quindi utilizzare l'output strutturato con l'API Prompt.

Nell'esempio seguente, lo schema JSON assicura che il modello risponda con true o false per classificare se un determinato messaggio riguarda la ceramica.

const session = await LanguageModel.create();

const schema = {
  "type": "boolean"
};

const post = "Mugs and ramen bowls, both a bit smaller than intended, but that
happens with reclaim. Glaze crawled the first time around, but pretty happy
with it after refiring.";

const result = await session.prompt(
  `Is this post about pottery?\n\n${post}`,
  {
    responseConstraint: schema,
  }
);
console.log(JSON.parse(result));
// true

La tua implementazione può includere uno schema JSON o un'espressione regolare come parte del messaggio inviato al modello. In questo modo viene utilizzata parte della finestra contestuale. Puoi misurare la quantità di finestra contestuale che utilizzerà passando l'opzione responseConstraint a session.measureContextUsage().

Puoi evitare questo comportamento con l'opzione omitResponseConstraintInput. Se lo fai, ti consigliamo di includere alcune indicazioni nel prompt:

const result = await session.prompt(`
  Summarize this feedback into a rating between 0-5. Only output a JSON
  object { rating }, with a single property whose value is a number:
  The food was delicious, service was excellent, will recommend.
`, { responseConstraint: schema, omitResponseConstraintInput: true });

Invia un prompt al modello

Puoi inviare un prompt al modello con le funzioni prompt() o promptStreaming().

Output basato sulle richieste

Se prevedi un risultato breve, puoi utilizzare la funzione prompt() che restituisce la risposta non appena è disponibile.

// Start by checking if it's possible to create a session based on the
// availability of the model, and the characteristics of the device.
const available = await LanguageModel.availability({
  expectedInputs: [{type: 'text', languages: ['en']}],
  expectedOutputs: [{type: 'text', languages: ['en']}],
});

if (available !== 'unavailable') {
  const session = await LanguageModel.create();

  // Prompt the model and wait for the whole result to come back.
  const result = await session.prompt('Write me a poem!');
  console.log(result);
}

Output in streaming

Se prevedi una risposta più lunga, devi utilizzare la funzione promptStreaming(), che ti consente di mostrare i risultati parziali man mano che vengono generati dal modello. La funzione promptStreaming() restituisce un valore ReadableStream.

const available = await LanguageModel.availability({
  expectedInputs: [{type: 'text', languages: ['en']}],
  expectedOutputs: [{type: 'text', languages: ['en']}],
});
if (available !== 'unavailable') {
  const session = await LanguageModel.create();

  // Prompt the model and stream the result:
  const stream = session.promptStreaming('Write me an extra-long poem!');
  for await (const chunk of stream) {
    console.log(chunk);
  }
}

Interrompi prompt

Sia prompt() che promptStreaming() accettano un secondo parametro facoltativo con un campo signal, che consente di interrompere l'esecuzione dei prompt.

const controller = new AbortController();
stopButton.onclick = () => controller.abort();

const result = await session.prompt('Write me a poem!', {
  signal: controller.signal,
});

Gestione sessione

Ogni sessione tiene traccia del contesto della conversazione. Le interazioni precedenti vengono prese in considerazione per le interazioni future fino a quando la finestra di contesto della sessione non è piena.

Ogni sessione ha un numero massimo di token che può elaborare. Controlla i tuoi progressi verso questo limite con quanto segue:

console.log(`${session.contextUsage}/${session.contextWindow}`);

È possibile inviare un prompt che causa l'overflow della finestra contestuale. In questi casi, le parti iniziali della conversazione con il modello linguistico verranno rimosse, una coppia di prompt e risposta alla volta, finché non saranno disponibili token sufficienti per elaborare il nuovo prompt. L'eccezione è il prompt di sistema, che non viene mai rimosso.

Questi overflow possono essere rilevati ascoltando l'evento contextoverflow nella sessione:

session.addEventListener("contextoverflow", () => {
  console.log("We've gone past the context window, and some inputs will be dropped!");
});

Se non è possibile rimuovere un numero sufficiente di token dalla cronologia delle conversazioni per elaborare il nuovo prompt, la chiamata prompt() o promptStreaming() non andrà a buon fine con un'eccezione QuotaExceededError e non verrà rimosso nulla. QuotaExceededError ha le seguenti proprietà:

  • requested: il numero di token di cui è composto l'input
  • contextWindow: il numero di token disponibili

Scopri di più sulla gestione delle sessioni.

Clona una sessione

Per preservare le risorse, puoi copiare una sessione esistente con la funzione clone(). In questo modo viene creato un fork della conversazione, in cui vengono conservati il contesto e il prompt iniziale.

La funzione clone() accetta un oggetto options facoltativo con un campo signal, che ti consente di passare un AbortSignal per eliminare la sessione clonata.

const controller = new AbortController();
stopButton.onclick = () => controller.abort();

const clonedSession = await session.clone({
  signal: controller.signal,
});

Termina una sessione

Chiama destroy() per liberare risorse se non hai più bisogno di una sessione. Quando una sessione viene eliminata, non può più essere utilizzata e l'esecuzione in corso viene interrotta. Potresti voler mantenere la sessione se intendi inviare prompt al modello spesso, poiché la creazione di una sessione può richiedere del tempo.

await session.prompt(
  "You are a friendly, helpful assistant specialized in clothing choices."
);

session.destroy();

// The promise is rejected with an error explaining that
// the session is destroyed.
await session.prompt(
  "What should I wear today? It is sunny, and I am choosing between a t-shirt
  and a polo."
);

Demo

Abbiamo creato diverse demo per esplorare i numerosi casi d'uso dell'API Prompt. Le seguenti demo sono applicazioni web:

Per testare l'API Prompt nelle estensioni di Chrome, installa l'estensione demo. Il codice sorgente dell'estensione è disponibile su GitHub.

Strategia di rendimento

L'API Prompt per il web è ancora in fase di sviluppo. Mentre creiamo questa API, consulta le nostre best practice sulla gestione delle sessioni per un rendimento ottimale.

Policy sulle autorizzazioni, iframe e web worker

Per impostazione predefinita, l'API Prompt è disponibile solo per le finestre di primo livello e per i relativi iframe con stessa origine. L'accesso all'API può essere delegato a iframe multiorigine utilizzando l'attributo allow="" della policy sulle autorizzazioni:

<!--
  The hosting site at https://main.example.com can grant a cross-origin iframe
  at https://cross-origin.example.com/ access to the Prompt API by
  setting the `allow="language-model"` attribute.
-->
<iframe src="https://cross-origin.example.com/" allow="language-model"></iframe>

Al momento l'API Prompt non è disponibile in Web Worker a causa della complessità di stabilire un documento responsabile per ogni worker al fine di controllare lo stato secondo le norme Permissions.

Partecipa e condividi feedback

Il tuo contributo può influire direttamente sul modo in cui creiamo e implementiamo le versioni future di questa API e di tutte le API di AI integrate.