O que é a API Prompt?

A API Prompt é uma proposta experimental de plataforma web do W3C Web Machine Learning Community Group que expõe um modelo de linguagem grande fornecido pelo navegador para JavaScript através de uma interface window.LanguageModel. As páginas criam uma sessão com LanguageModel.create(), opcionalmente a configuram com um prompt de sistema, e então chamam prompt() ou promptStreaming() para obter uma resposta.

Diferentemente de chamar uma API LLM hospedada, o modelo é executado no dispositivo do usuário. Isso significa que as entradas nunca saem da máquina, a página funciona offline uma vez que o modelo é armazenado em cache, e não há custos por solicitação. No Chrome, o modelo subjacente é o Gemini Nano, mas a API é intencionalmente agnóstica em relação ao modelo, portanto outros navegadores podem conectar implementações diferentes.

Uma sessão é com estado: ela rastreia o histórico da conversa dentro de uma janela de contexto medida em tokens. Quando a janela se enche, as mensagens não-sistema mais antigas são removidas automaticamente (um evento contextoverflow é disparado), e você pode inspecionar session.contextUsage e session.contextWindow a qualquer momento para ver quanto espaço resta.

Descrição da ferramenta

Este playground é uma superfície de chat interativa conectada a window.LanguageModel. Ele permite que você defina um prompt de sistema, envie mensagens e observe o modelo transmitir tokens em tempo real. Uma barra de progresso mostra a disponibilidade do modelo e o progresso do download, e uma barra de uso de tokens relata quanto da janela de contexto da sessão está sendo consumido.

A sessão é criada preguiçosamente no primeiro envio e reutilizada entre mensagens até que você altere o prompt de sistema, momento em que é destruída e uma nova é criada com as novas instruções.

Recursos

  • Respostas em streaming — usa promptStreaming() para que os tokens apareçam no chat conforme são produzidos.
  • Editor de prompt de sistema — defina um papel ou comportamento persistente que condiciona cada resposta.
  • Botão Parar — interrompa um prompt em andamento com um AbortController sem desmontar a sessão.
  • Uso de contexto ao vivo — visualiza contextUsage contra contextWindow para que você possa ver quando a conversa está prestes a transbordar.
  • Disponibilidade e progresso do download — expõe o estado availability() e eventos downloadprogress enquanto o modelo está sendo buscado.

Casos de uso

  • Testando prompts localmente — itere em prompts de sistema e padrões few-shot sem pagar por uma API em nuvem.
  • Testando a viabilidade de IA no dispositivo — verifique se a API Prompt está disponível, veja o tamanho da janela de contexto e compare a velocidade de resposta no seu hardware.
  • Rascunho sensível à privacidade — brainstorm ou reformule texto que não deve ser enviado para um servidor de terceiros.

Requisitos

  • Um navegador que implemente a API Prompt. Chrome 138+ a expõe experimentalmente; em versões mais antigas, você pode precisar ativá-la via chrome://flags/#prompt-api-for-gemini-nano e ter o modelo no dispositivo baixado.
  • Um contexto seguro (HTTPS ou localhost).
  • Um dispositivo que atenda aos requisitos de hardware do modelo (espaço em disco suficiente, RAM e GPU/CPU suportada). Em dispositivos não suportados, availability() retorna unavailable.
  • Largura de banda inicial para baixar o modelo. Sessões subsequentes reutilizam o modelo em cache.

Como funciona

  1. Na montagem, a ferramenta verifica typeof window.LanguageModel. Se ausente, um aviso substitui a entrada de chat.
  2. LanguageModel.availability() relata um de available, downloadable, downloading ou unavailable. O resultado é mostrado na barra de progresso.
  3. Na primeira vez que você pressiona Enviar, a ferramenta chama LanguageModel.create() com um monitor que transmite eventos downloadprogress para a UI. Se um prompt de sistema estiver definido, ele é passado via initialPrompts: [{ role: "system", content: ... }].
  4. A mensagem do usuário é enviada através de session.promptStreaming(text, { signal }). O ReadableStream<string> retornado é consumido pedaço por pedaço e anexado à mensagem do assistente.
  5. Após cada resposta, session.contextUsage e session.contextWindow são lidos e refletidos na barra de uso de tokens.
  6. Pressionar Parar chama controller.abort(), que rejeita o stream em andamento com um AbortError enquanto mantém a sessão viva para o próximo prompt.
  7. Editar o prompt de sistema invalida a sessão em cache: a existente é destroy()-ada e o próximo envio cria uma nova sessão com as instruções atualizadas.

Opções explicadas

  • Prompt de sistema — uma instrução livre passada como a primeira mensagem com função system. Ela condiciona todos os turnos subsequentes. Deixá-la em branco cria uma sessão sem uma mensagem de sistema.
  • Enviar / Parar — Enviar submete a entrada como uma mensagem user. Parar interrompe a resposta em streaming sem deletar mensagens anteriores.
  • Uso de tokens — tokens used / total para a sessão atual. Quando used se aproxima de total, pares de usuário/assistente mais antigos serão removidos no próximo prompt.
  • Status do modelo — leitura combinada de availability() e downloadprogress. Enquanto o modelo baixa, a barra anima e mostra uma porcentagem.

Limitações

  • A API Prompt é experimental. Nomes de métodos, opções (por exemplo, inputUsage vs contextUsage) e semântica de eventos podem mudar entre versões do Chrome.
  • A qualidade da saída, factualidade e seguimento de instruções dependem inteiramente do modelo fornecido pelo navegador e não são garantidos.
  • A janela de contexto é pequena em comparação com LLMs hospedados. Conversas longas transbordarão e silenciosamente descartarão os turnos mais antigos.
  • A API não é exposta a web workers e pode exigir delegação de Permissions Policy (language-model) em iframes de origem cruzada.
  • Esta ferramenta intencionalmente não expõe temperature, topK, uso de ferramentas, entradas multimodais, saída estruturada (responseConstraint) ou clonagem de sessão. Eles fazem parte da especificação, mas foram mantidos fora do playground para manter o foco no chat simples.

FAQ

Por que diz que a API não é suportada? window.LanguageModel é undefined no seu navegador. Tente o Chrome mais recente no desktop e, se necessário, ative a flag da API Prompt e aguarde o download do modelo no dispositivo via chrome://components.

Por que a primeira resposta é lenta? A primeira chamada pode disparar um download de modelo (observe a barra de progresso) e uma etapa de criação de sessão. Prompts posteriores reutilizam a mesma sessão e começam a transmitir quase imediatamente.

Meu prompt sai do dispositivo? Não. O modelo é executado localmente. Seu texto não é enviado para nenhum servidor por esta ferramenta.

O que acontece quando o contexto se enche? A sessão dispara um evento contextoverflow e remove os turnos não-sistema mais antigos para liberar espaço. O prompt de sistema é preservado.

Por que alterar o prompt de sistema limpou o estilo de resposta no meio da conversa? Editar o prompt de sistema destrói a sessão atual e cria uma nova no próximo envio. A nova sessão não tem memória dos turnos anteriores.