L'API Prompt

Thomas Steiner

Alexandra Klepper

Pubblicato: 20 maggio 2025, ultimo aggiornamento: 21 luglio 2025

Spiegazione	Web	Estensioni	Stato di Chrome	Intenzione
GitHub	In prova dell'origine	Chrome 138	Visualizza	Intenzione di sperimentare

Con l'API Prompt, puoi inviare richieste in linguaggio naturale a Gemini Nano nel browser.

Esistono molti modi per utilizzare l'API Prompt in un'applicazione web o in un sito web. Ad esempio, potresti creare:

• Ricerca basata sull'AI: risponde 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 consente agli utenti di filtrare i contenuti.

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

Utilizzare 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.

Per determinare se il modello è pronto per l'uso, chiama LanguageModel.availability(). Se la risposta a availability() è stata downloadable, ascolta l'avanzamento del download e informa l'utente, poiché il download potrebbe richiedere tempo.

const availability = await LanguageModel.availability();

Per attivare il download e l'istanza del modello linguistico, verifica l'attivazione utente. Quindi, chiama la funzione asincrona LanguageModel.create().

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

Parametri del modello

La funzione params() ti informa sui parametri del modello linguistico. L'oggetto contiene i seguenti campi:

• defaultTopK: il valore predefinito di top-K.
• maxTopK: il valore massimo top-K.
• defaultTemperature: la temperatura predefinita.
• maxTemperature: la temperatura massima.

await LanguageModel.params();
// {defaultTopK: 3, maxTopK: 128, defaultTemperature: 1, maxTemperature: 2}

Creare una sessione

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

Ogni sessione può essere personalizzata con topK e temperature utilizzando un oggetto opzioni facoltativo. I valori predefiniti di questi parametri vengono restituiti da LanguageModel.params().

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

L'oggetto delle opzioni facoltative della funzione create() accetta anche un campo signal, che ti consente di passare un AbortSignal per distruggere la sessione.

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

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

Aggiungere 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 salvata 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. [...]',
    },
  ],
});

Limitare le risposte con un prefisso

Puoi aggiungere un ruolo "assistant", oltre ai ruoli precedenti, per elaborare 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 di ruolo "assistant" finale. 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,
  },
]);

Aggiungere messaggi

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

Sebbene initialPrompts siano utili durante la creazione della sessione, il metodo append() può essere utilizzato in aggiunta ai metodi prompt() o promptStreaming() per fornire ulteriori 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 promessa viene rifiutata se il prompt non può essere aggiunto.

Persistenza e limiti delle sessioni

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

const session = await LanguageModel.create({
  initialPrompts: [
    {
      role: 'system',
      content:
        'You are a friendly, helpful assistant specialized in clothing choices.',
    },
  ],
});

const result1 = await session.prompt(
  'What should I wear today? It is sunny. I am unsure between a t-shirt and a polo.',
);
console.log(result1);

const result2 = await session.prompt(
  'That sounds great, but oh no, it is actually going to rain! New advice?',
);
console.log(result2);

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

console.log(`${session.inputUsage}/${session.inputQuota}`);

Trasmettere uno schema JSON

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

Nel seguente esempio, 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

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

Puoi evitare questo comportamento con l'opzione omitResponseConstraintInput. In questo caso, 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 });

Clonare una sessione

Per preservare le risorse, puoi clonare una sessione esistente con la funzione clone(). Il contesto della conversazione viene reimpostato, ma il prompt iniziale rimane intatto. La funzione clone() accetta un oggetto di opzioni 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,
});

Richiedere al modello

Puoi richiedere al modello di utilizzare la funzione prompt() o promptStreaming().

Output non in streaming

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 { defaultTemperature, maxTemperature, defaultTopK, maxTopK } =
  await LanguageModel.params();

const available = await LanguageModel.availability();

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 restituiti dal modello. La funzione promptStreaming() restituisce un ReadableStream.

const { defaultTemperature, maxTemperature, defaultTopK, maxTopK } =
  await LanguageModel.params();

const available = await LanguageModel.availability();
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);
  }
}

Interrompere la richiesta

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,
});

Terminare una sessione

Chiama destroy() per liberare le risorse se non hai più bisogno di una sessione. Quando una sessione viene eliminata, non può più essere utilizzata e qualsiasi esecuzione in corso viene interrotta. Potresti voler mantenere la sessione se intendi richiedere spesso al modello, poiché la creazione di una sessione può richiedere un po' di 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."
);

Funzionalità multimodali

La prova dell'origine dell'API Prompt supporta gli input audio e immagine. L'API restituisce un output di testo.

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.

const session = await LanguageModel.create({
  // { type: 'text' } only required when including expected input languages.
  expectedInputs: [{ type: 'audio' }, { type: 'image' }],
});

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 an artistic critique of how well the second image matches the first:',
      },
      { type: 'image', value: referenceImage },
      { type: 'image', value: userDrawnImage },
    ],
  },
]);

console.log(response1);

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

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

Consulta la demo Mediarecorder Audio Prompt per utilizzare l'API Prompt con l'input audio e la demo Canvas Image Prompt per utilizzare l'API Prompt con l'input immagine.

Strategia di rendimento

L'API Prompt per il web è ancora in fase di sviluppo. Durante la creazione di questa API, fai riferimento alle nostre best practice sulla gestione delle sessioni per ottenere prestazioni ottimali.

Norme relative alle 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 la stessa origine. L'accesso all'API può essere delegato agli iframe multiorigine utilizzando l'attributo allow="" della policy sui permessi:

<!--
  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>

L'API Prompt non è attualmente disponibile nei web worker a causa della complessità di stabilire un documento responsabile per ogni worker al fine di controllare lo stato della norma relativa alle autorizzazioni.

Partecipare e condividere 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 AI integrate.

• Per inviare feedback sull'implementazione di Chrome, compila una segnalazione di bug o una richiesta di funzionalità.
• Condividi il tuo feedback sulla forma dell'API commentando un problema esistente o aprendone uno nuovo nel repository GitHub dell'API Prompt.
• Partecipa al programma di anteprima iniziale.