A API Prompt nas extensões do Chrome

Thomas Steiner

Publicado em 11 de novembro de 2024

A API Prompt para extensões agora está disponível em um teste de origem. Assim, você pode criar extensões do Chrome que usam o Gemini Nano, nosso modelo de linguagem mais eficiente, no navegador.

Há muitos casos de uso para a API Prompt com extensões do Chrome. Confira alguns exemplos:

  • Eventos da agenda instantânea. Desenvolva uma extensão do Chrome que extraia automaticamente os detalhes dos eventos das páginas da Web para que os usuários possam criar entradas de calendário em apenas algumas etapas.
  • Extração de contatos integrada. Crie uma extensão que extraia informações de contato de sites, facilitando a comunicação 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 analisa artigos de notícias e desfoca ou oculta automaticamente o conteúdo com base em temas definidos pelo usuário.

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

Disponibilidade

  • Participe do teste de origem da API Prompt, que é executado no Chrome 131 a 136, para criar extensões com essa API. Se você não conhece os testes de origem, saiba que eles são programas com tempo limitado abertos a todos os desenvolvedores, que oferecem acesso antecipado a recursos experimentais da plataforma. Os desenvolvedores podem testar, coletar feedback dos usuários e iterar para um lançamento futuro.
    • Embora possa haver limites de uso, é possível integrar esses recursos para testar ao vivo e coletar feedback dos usuários. O objetivo é informar as iterações futuras dessa API, à medida que trabalhamos para aumentar a disponibilidade.
  • Participe do programa de prévia antecipada para conferir as novas APIs de IA integradas e participar da discussão na nossa lista de e-mails.

Participar do teste de origem

Para usar a API Prompt nas extensões do Chrome, adicione a permissão "aiLanguageModelOriginTrial" ao arquivo manifest.json conforme o trecho abaixo, junto com todas as outras permissões necessárias para a extensão.

Para inscrever sua extensão no teste de origem, use o URL chrome-extension://YOUR_EXTENSION_ID como a Origem da Web. Por exemplo, chrome-extension://ljjhjaakmncibonnjpaoglbhcjeolhkk.

Inscrição no teste de origem do Chrome

O ID da extensão é criado dinamicamente. Depois de atribuído, você pode forçar o ID a permanecer estável adicionando a propriedade key ao manifesto.

Depois de se inscrever no teste original, você vai receber um token gerado, que precisa ser transmitido em uma matriz como o valor do campo trial_tokens no manifesto.

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

Adicionar suporte ao localhost

Para acessar a API Prompt no localhost durante o teste de origem, é necessário atualizar o Chrome para a versão mais recente. Em seguida, siga estas etapas:

  1. Abra o Chrome em uma destas plataformas: Windows, Mac ou Linux.
  2. Acesse chrome://flags/#optimization-guide-on-device-model.
  3. Selecione BypassPerfRequirement ativado.
    • Isso pula as verificações de desempenho que podem impedir o download do Gemini Nano no dispositivo.
  4. Clique em Reiniciar ou reinicie o Chrome.

Usar a API Prompt

Depois de solicitar a permissão para usar a API Prompt, você pode criar sua extensão. Há duas novas 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 do 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:

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().

Opções da 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. [...]' }
  ]
});

Informações da 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() recebe 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);

Interromper a execução de um comando

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.