API Prompt

Thomas Steiner

Publicado em 11 de novembro de 2024

Explicação Web Extensões Status do Chrome Intenção
GitHub Experimental No EPP Atrás de uma sinalização Teste do Origin Não relevante Não relevante

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

A API Prompt está disponível em um teste de origem para extensões do Chrome. Os desenvolvedores da Web podem usar a API de exploração, destinada à criação de protótipos e à descoberta de outros casos de uso, participando do programa de pré-lançamento.

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.

Primeiros passos

Para usar a API Prompt em extensões do Chrome, adicione a permissão "aiLanguageModelOriginTrial" ao manifest.json da extensão, junto com todas as outras permissões necessárias.

{
  "manifest_version": 3,
  "name": "YOUR_EXTENSION_NAME",
  "key": "YOUR_EXTENSION_KEY",
  "permissions": ["aiLanguageModelOriginTrial"]
}

Isso concede uma permissão temporária, válida apenas durante o teste de origem. Se a API for lançada, você vai precisar atualizar e fazer o upload da extensão novamente, removendo a permissão expirada e substituindo-a pelas permissões finais.

Além disso, recomendamos manter um ID de extensão consistente adicionando a propriedade key ao seu manifesto.

Participar do teste de origem

Para adicionar a API Prompt à sua extensão do Chrome:

  1. Participe do teste de origem da API Prompt, executado no Chrome 131 a 136.

  2. Use o URL chrome-extension://YOUR_EXTENSION_ID da sua extensão como a origem da Web. Por exemplo, chrome-extension://ljjhjaakmncibonnjpaoglbhcjeolhkk.

  3. Atualize o manifesto para adicionar o token de teste como uma matriz.

    {
  "manifest_version": 3,
  "name": "YOUR_EXTENSION_NAME",
  "key": "YOUR_EXTENSION_KEY",
  "permissions": ["aiLanguageModelOriginTrial"],
  "trial_tokens": ["GENERATED_TOKEN"],
}

Usar a API Prompt em extensões

Depois de solicitar a permissão para usar a API Prompt, você poderá criar sua extensão. Há duas funções de extensão disponíveis no namespace chrome.aiOriginTrial.languageModel:

  • capabilities() 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 chrome.aiOriginTrial.languageModel.capabilities() assíncrona. Ele retorna um objeto AILanguageModelCapabilities com um campo available que pode ter três valores possíveis:

  • 'no': o navegador atual 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 atual oferece suporte à API Prompt e pode ser usado imediatamente.
  • 'after-download': o navegador atual 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 chrome.aiOriginTrial.languageModel.create() assíncrona. Se a resposta para capabilities() 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 chrome.aiOriginTrial.languageModel.create({
  monitor(m) {
    m.addEventListener("downloadprogress", (e) => {
      console.log(`Downloaded ${e.loaded} of ${e.total} bytes.`);
    });
  },
});

Recursos de modelo

A função capabilities() também informa os recursos do modelo de linguagem. Além de available, o objeto AILanguageModelCapabilities resultante 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 chrome.aiOriginTrial.languageModel.capabilities();
// {available: 'readily', defaultTopK: 3, maxTopK: 8, defaultTemperature: 1}

Criar uma sessão

Depois de verificar se a API Prompt pode ser executada, crie uma sessão com a função create(), que permite 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 chrome.aiOriginTrial.languageModel.capabilities().

const capabilities = await chrome.aiOriginTrial.languageModel.capabilities();
// Initializing a new session must either specify both `topK` and
// `temperature` or neither of them.
const slightlyHighTemperatureSession = await chrome.aiOriginTrial.languageModel.create({
  temperature: Math.max(capabilities.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 chrome.aiOriginTrial.languageModel.create({
  signal: controller.signal,
})
Comandos do sistema

Com os comandos do sistema, você pode fornecer um pouco de contexto ao modelo de linguagem.

const session = await chrome.aiOriginTrial.languageModel.create({
  systemPrompt: 'You are a helpful and friendly assistant.',
});
await session.prompt('What is the capital of Italy?');
// 'The capital of Italy is Rome.'

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 chrome.aiOriginTrial.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 chrome.aiOriginTrial.languageModel.create({
  systemPrompt: '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 a solicitação inicial ou do sistema permanece intacta. 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 chrome.aiOriginTrial.languageModel.capabilities();

if (available !== 'no') {
  const session = await chrome.aiOriginTrial.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 chrome.aiOriginTrial.languageModel.capabilities();

if (available !== 'no') {
  const session = await chrome.aiOriginTrial.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);

Parar 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

Comece a testar a API Prompt agora nas suas extensões do Chrome participando do teste de origem e compartilhando seu feedback. Sua contribuição pode afetar diretamente a forma como criamos e implementamos versões futuras dessa API e de todas as APIs de IA integradas.