API Prompt

Thomas Steiner

Alexandra Klepper

Publicado em: 20 de maio de 2025

Explicação	Web	Extensões	Status do Chrome	Intenção
GitHub	Em Teste de origem	Chrome 138	Ver	Intenção de experimentar

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

Há muitas maneiras de usar a API Prompt. Em um aplicativo da Web ou site, você pode criar:

• Pesquisa com tecnologia de IA: responda a perguntas com base no conteúdo de uma página da Web.
• Feeds de notícias personalizados: crie um feed que classifique artigos dinamicamente com categorias e permita que os usuários filtrem esse conteúdo.

Essas são apenas algumas possibilidades, e estamos ansiosos para ver o que você vai criar.

Usar a API Prompt

Antes de usar essa API, leia e aceite a Política de uso proibido da IA generativa do Google.

Há duas funções disponíveis para você no namespace LanguageModel:

• availability() para verificar o que o modelo pode 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 seja integrada ao Chrome, o modelo é baixado separadamente na primeira vez que uma origem usa a API.

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

• "unavailable" significa que a implementação não oferece suporte às opções solicitadas ou não oferece suporte a solicitações de um modelo de linguagem.
• "downloadable" significa que a implementação é compatível com as opções solicitadas, mas precisa baixar algo (por exemplo, o modelo de linguagem ou um ajuste refinado) antes de criar uma sessão usando essas opções.
• "downloading" significa que a implementação oferece suporte às opções solicitadas, mas precisa concluir uma operação de download em andamento antes de criar uma sessão usando essas opções.
• "available" significa que a implementação é compatível com as opções solicitadas sem exigir novos downloads.

Para acionar o download do modelo e criar a sessão do modelo de linguagem, chame a função assíncrona LanguageModel.create(). Se a resposta a availability() foi 'downloadable', a prática recomendada é aguardar 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 * 100}%`);
    });
  },
});

Recursos de modelo

A função params() informa os parâmetros do modelo de linguagem. O objeto 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.
• maxTemperature: a temperatura máxima.

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

Criar uma sessão

Depois que a API Prompt puder ser executada, crie uma sessão com a função create(). É possível enviar comandos ao 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.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,
});

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, você pode fornecer ao modelo de linguagem contexto sobre interações anteriores, por exemplo, para permitir que o usuário retome uma sessão armazenada após a 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. [...]',
    },
  ],
});

Restringir respostas fornecendo um prefixo

Você pode adicionar uma nova função "assistant", além das anteriores, para elaborar as respostas anteriores do modelo. Exemplo:

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

Em alguns casos, em vez de pedir uma nova resposta, talvez você queira preencher previamente parte da mensagem de resposta da função "assistant". Isso pode ser útil para orientar o modelo de linguagem a usar um formato de resposta específico. Para fazer isso, adicione prefix: true à mensagem final com a função "assistant". Exemplo:

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

Adicionar mensagens sem solicitação

A inferência pode levar algum tempo, principalmente ao usar comandos com entradas multimodais. É útil enviar comandos predeterminados com antecedência para preencher a sessão, assim o modelo pode começar a processar.

Embora initialPrompts seja útil na criação de sessões, o método append() pode ser usado junto com os métodos prompt() ou promptStreaming() para fornecer mais solicitações contextuais depois que a sessão é criada.

Exemplo:

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

A promessa retornada por append() é cumprida quando o comando é validado, processado e anexado à sessão. A promessa será rejeitada se o comando não puder ser anexado.

Limites de sessão

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

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

Persistência da sessão

Cada sessão acompanha o contexto da conversa. As interações anteriores são consideradas para as 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 recursos, é possível clonar uma sessão atual com a função clone(). O contexto da conversa é redefinido, mas o comando inicial permanece intacto. 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,
});

Comandar o modelo

É possível enviar comandos ao modelo com as funções prompt() ou promptStreaming().

Saída não transmitida

Se você espera um resultado curto, use a função prompt(), que retorna a resposta assim que 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 { 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);
}

Saída transmitida

Se você espera uma resposta mais longa, use a função promptStreaming(), que permite mostrar resultados parciais à medida que chegam do modelo. A função promptStreaming() retorna um 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);
  }
}

Parar de executar um comando

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

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 é interrompida. É recomendável 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."
);

Recursos multimodais

A API Prompt é compatível com entradas de áudio e imagem do Chrome 138 Canary para testes locais. A API retorna uma saída de texto.

Com esses recursos, é possível:

• Permite que os usuários transcrevam mensagens de áudio enviadas em um aplicativo de chat.
• Descreva uma imagem enviada ao seu site para usar em uma legenda ou texto alternativo.

const session = await LanguageModel.create({
  // { type: "text" } is not necessary to include explicitly, unless
  // you also want to include expected input languages for text.
  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 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 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 },
    ],
  },
]);

Demonstrações multimodais

Consulte a demonstração Mediarecorder Audio Prompt (em inglês) para usar a API Prompt com entrada de áudio e a demonstração Canvas Image Prompt (em inglês) para usar a API Prompt com entrada de imagem.

Estratégia de performance

A API de solicitação para a Web ainda está em desenvolvimento. Enquanto criamos essa API, consulte nossas práticas recomendadas sobre gerenciamento de sessões para ter uma performance ideal.

Feedback

Seu feedback ajuda a definir o futuro dessa API e as melhorias do Gemini Nano. Isso pode até resultar em APIs de tarefas dedicadas (como APIs para transcrição de áudio ou descrição de imagens), para que possamos atender às suas necessidades e às necessidades dos seus usuários.

Participe e compartilhe feedback

Sua opinião pode afetar diretamente a forma como criamos e implementamos versões futuras dessa API e de todas as APIs de IA integradas.

• Participe do Programa de prévia antecipada.
• Para enviar feedback sobre a implementação do Chrome, registre um relatório de bug ou uma solicitação de recurso.
• Compartilhe seu feedback sobre o formato da API comentando um problema atual ou abrindo um novo no repositório da API Prompt no GitHub.
• Participe do esforço de padrões entrando no Web Incubator Community Group (em inglês).