API Prompt

Thomas Steiner

Publicado em 11 de novembro de 2024 e atualizado pela última vez em 20 de maio de 2025

Explicação Web Extensões Status do Chrome Intenção
GitHub Experimental No EPP Chrome Beta Chrome 137 Beta Ver Intent to Experiment

Com a API Prompt, você pode enviar solicitações de linguagem natural para o Gemini Nano no navegador.

Há muitas maneiras de usar a API Prompt nas extensões do Chrome. Exemplo:

  • Eventos da agenda instantânea. Desenvolva uma extensão do Chrome que extraia automaticamente detalhes de eventos de páginas da Web para que os usuários possam criar entradas de agenda em apenas algumas etapas.
  • Extração de contatos simples. Crie uma extensão que extraia informações de contato de sites, facilitando o contato dos usuários com uma empresa ou a adição de detalhes à lista de contatos.
  • Filtragem dinâmica de conteúdo. Crie uma extensão do Chrome que analise artigos de notícias e desfoque ou oculte o conteúdo automaticamente com base em temas definidos pelo usuário.

Essas são apenas algumas possibilidades, mas queremos saber o que você vai criar.

Usar a API Prompt em extensões

Há duas funções de extensão disponíveis no namespace LanguageModel:

  • availability() para verificar o que o modelo é capaz de fazer e se ele está disponível.
  • create() para iniciar uma sessão de modelo de linguagem.

Download do modelo

A API Prompt usa o modelo Gemini Nano no Chrome. Embora a API esteja integrada ao Chrome, o modelo é transferido por download separadamente na primeira vez que uma extensão usa a API.

Para determinar se o modelo está pronto para uso, chame a função LanguageModel.availability() assíncrona. Isso vai retornar uma das seguintes respostas:

  • 'no': o navegador oferece suporte à API Prompt, mas ela não pode ser usada no momento. Isso pode acontecer por vários motivos, como espaço em disco insuficiente para fazer o download do modelo.
  • 'readily': o navegador oferece suporte à API Prompt e pode ser usado imediatamente.
  • 'after-download': o navegador oferece suporte à API Prompt, mas precisa fazer o download do modelo primeiro.

Para acionar o download do modelo e criar a sessão do modelo de linguagem, chame a função LanguageModel.availability() assíncrona. Se a resposta para availability() foi 'after-download', a prática recomendada é detectar o progresso do download. Assim, você pode informar o usuário caso o download demore.

const session = await LanguageModel.create({
  monitor(m) {
    m.addEventListener("downloadprogress", (e) => {
      console.log(`Downloaded ${e.loaded} of ${e.total} bytes.`);
    });
  },
});

Recursos de modelo

A função availability() também informa os recursos do modelo de linguagem. Além de available, o objeto também tem os seguintes campos:

  • defaultTopK: o valor padrão top-K (padrão: 3).
  • maxTopK: o valor máximo de top-K (8).
  • defaultTemperature: a temperatura padrão (1.0). O valor da temperatura precisa estar entre 0.0 e 2.0.
await LanguageModel.availability();
// {available: 'readily', defaultTopK: 3, maxTopK: 8, defaultTemperature: 1}

Criar uma sessão

Depois que a API Prompt puder ser executada, crie uma sessão com a função create(). É possível solicitar o modelo com as funções prompt() ou promptStreaming().

Personalizar sua sessão

Cada sessão pode ser personalizada com topK e temperature usando um objeto de opções opcional. Os valores padrão desses parâmetros são retornados de LanguageModel.availability().

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

O objeto de opções opcional da função create() também usa um campo signal, que permite transmitir um AbortSignal para destruir a sessão.

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

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

Comandos iniciais

Com os comandos iniciais, é possível fornecer ao modelo de linguagem o contexto sobre interações anteriores, por exemplo, para permitir que o usuário retome uma sessão armazenada após uma reinicialização do navegador.

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

Limites de sessão

Uma determinada sessão de modelo de linguagem tem um número máximo de tokens que pode processar. É possível verificar o uso e o progresso em relação a esse limite usando as seguintes propriedades no objeto de sessão:

console.log(`${session.tokensSoFar}/${session.maxTokens}
(${session.tokensLeft} left)`);

Persistência de sessão

Cada sessão rastreia o contexto da conversa. As interações anteriores são consideradas para interações futuras até que a janela de contexto da sessão esteja cheia.

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

Clonar uma sessão

Para preservar os recursos, você pode clonar uma sessão existente com a função clone(). O contexto da conversa é redefinido, mas o comando inicial permanece intato. A função clone() usa um objeto de opções opcional com um campo signal, que permite transmitir um AbortSignal para destruir a sessão clonada.

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

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

Solicitar o modelo

É possível solicitar o modelo com as funções prompt() ou promptStreaming().

Saída sem streaming

Se você espera um resultado curto, use a função prompt(), que retorna a resposta quando ela estiver disponível.

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

if (available !== 'no') {
  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);
}

Saída de streaming

Se você espera uma resposta mais longa, use a função promptStreaming(), que permite mostrar resultados parciais conforme eles chegam do modelo.

const {available, defaultTemperature, defaultTopK, maxTopK } =
  await LanguageModel.availability();

if (available !== 'no') {
  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);
  }
}

promptStreaming() retorna um ReadableStream cujos blocos são construídos sucessivamente. Por exemplo, "Hello,", "Hello world,", "Hello world I am,", "Hello world I am an AI.". Esse não é o comportamento esperado. Nossa intenção é alinhar com outras APIs de streaming na plataforma, em que os blocos são partes sucessivas de um único stream longo. Isso significa que a saída seria uma sequência como "Hello", " world", " I am", " an AI".

Por enquanto, para alcançar o comportamento desejado, implemente o seguinte. Isso funciona com o comportamento padrão e não padrão.

let result = '';
let previousChunk = '';

for await (const chunk of stream) {
  const newChunk = chunk.startsWith(previousChunk)
      ? chunk.slice(previousChunk.length) : chunk;
  console.log(newChunk);
  result += newChunk;
  previousChunk = chunk;
}
console.log(result);

Interromper a execução de uma solicitação

prompt() e promptStreaming() aceitam um segundo parâmetro opcional com um campo signal, que permite interromper a execução de avisos.

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

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

Encerrar uma sessão

Chame destroy() para liberar recursos se você não precisar mais de uma sessão. Quando uma sessão é destruída, ela não pode mais ser usada, e qualquer execução em andamento é abortada. Talvez seja melhor manter a sessão se você pretende solicitar o modelo com frequência, já que a criação de uma sessão pode levar algum 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 unsure between a
  t-shirt and a polo."
);

Demonstração

Para testar a API Prompt nas extensões do Chrome, instale a extensão de demonstração. O código-fonte da extensão está disponível no GitHub.

Interface de demonstração da API Prompt

Participar e compartilhar feedback

Sua contribuição pode afetar diretamente a criação e implementação de versões futuras dessa API e de todas as APIs de IA integradas.