Um polyfill experimental para a API Prompt.

Thomas Steiner

Publicado em 14 de maio de 2026

Com a API Prompt no Chrome, você pode interagir com um LLM usando uma API de navegador de alto nível em window.LanguageModel. No entanto, ainda há suporte limitado para isso, e a implementação é um processo complexo.

Ao mesmo tempo, os desenvolvedores do programa de prévia antecipada compartilharam o entusiasmo pela API Prompt. A disponibilidade da API representa um desafio de compatibilidade para o futuro previsível.

Solução

É por isso que estamos lançando um polyfill da API Prompt compatível com a especificação experimental (consulte o código-fonte no GitHub) que implementa com precisão a API Prompt em provedores de back-end de nuvem configuráveis e também em um provedor de back-end local na forma de Transformers.js.

Usar o polyfill

Para usar o polyfill, faça o seguinte:

1. Faça o download do polyfill no npm:

   npm install prompt-api-polyfill
   

2. Escolha se você quer usar um provedor de back-end de nuvem ou um provedor de back-end local:

   • Provedor de back-end de nuvem:os dados do usuário são enviados para a nuvem para processamento remoto, mas não é necessário esperar que um modelo local esteja disponível. Você é responsável por qualquer custo incorrido de acordo com as informações de preços do seu provedor de nuvem.
   • Provedor de back-end local:os dados do usuário permanecem no navegador e são processados localmente, mas é necessário fazer o download de um modelo que, ao contrário da API Prompt real, não pode ser compartilhado em origens diferentes. Não há custo envolvido no processamento local.

Back-end de nuvem

Escolha entre qualquer um dos back-ends de nuvem e receba uma chave de API (e outras credenciais) para o provedor de back-end.

Depois de ter a chave de API, insira os detalhes no arquivo de configuração .env.json. Se você não especificar um modelName, o polyfill vai usar o modelo padrão de cada back-end, mas, se fizer isso, poderá selecionar um dos modelos compatíveis de cada back-end.

{
  "apiKey": "y0ur-Api-k3Y",
  "modelName": "model-name"
}

Back-end local

Se você decidir usar um provedor de back-end local com base no Transformers.js, só precisará de uma chave de API fictícia. No entanto, é possível configurar qual dispositivo o Transformers.js deve usar. Escolha "webgpu" para desempenho máximo e "wasm" para compatibilidade máxima. Opcionalmente, você pode mudar as configurações padrão. Escolha outro modelo no catálogo de modelos compatíveis do Hugging Face. Para alguns modelos, é possível selecionar entre diferentes quantizações usando o parâmetro dtype.

{
  "apiKey": "dummy",
  "device": "webgpu",
  "dtype": "q4f16",
  "modelName": "onnx-community/gemma-3-1b-it-ONNX-GQA"
};

Configurar o polyfill

Com o arquivo de configuração no lugar, você já pode começar a usar o polyfill no seu app.

1. Importe o arquivo de configuração e atribua-o a uma variável global com um nome adequado, em que $BACKEND é o back-end escolhido: window.$BACKEND_CONFIG.
2. Use uma importação dinâmica para carregar o polyfill somente quando o navegador subjacente não o oferecer suporte.
3. Chame as funções da API Prompt.

import config from './.env.json' with { type: 'json' };

// Set $BACKEND_CONFIG to select a backend
window.$BACKEND_CONFIG = config;

if (!('LanguageModel' in window)) {
  await import('prompt-api-polyfill');
}

const session = await LanguageModel.create({
  expectedInputs: [{type: 'text', languages: ['en']}],
  expectedOutputs: [{type: 'text', languages: ['en']}],
});
await session.prompt('Tell me a joke!');

O polyfill oferece suporte a saída estruturada (exceto para o back-end Transformers.js), lida com entrada multimodal (exceto para o back-end OpenAI que não oferece suporte a áudio e imagem juntos, apenas separadamente) e é testado no conjunto completo de testes da plataforma da Web para o LanguageModel.

Para mais informações sobre o contexto e o uso detalhado, bem como o código-fonte, consulte o arquivo README no repositório do GitHub.

Diferença da API Prompt do navegador

Se o polyfill for apoiado por modelos de nuvem, alguns dos benefícios da execução do lado do cliente não serão mais aplicáveis. Ou seja, não é mais possível garantir o tratamento local de dados sensíveis, embora as políticas de privacidade do provedor de back-end ainda sejam aplicáveis. Seu app também não poderá mais usar a IA quando o usuário estiver off-line. Para saber se você está on-line ou off-line, ouça os eventos correspondentes.

window.addEventListener("offline", (e) => {
  console.log("offline");
});

window.addEventListener("online", (e) => {
  console.log("online");
});

Se a inferência de IA for executada em um modelo na nuvem, não haverá um modelo local para fazer o download. O polyfill simula os eventos downloadprogress. Portanto, para seu app, vai parecer que o modelo integrado já foi baixado, o que significa que haverá dois eventos, um com um valor loaded de 0 e outro com 1, que é o que a especificação exige.

Com a inferência baseada na nuvem, ao contrário da inferência no dispositivo, há um custo potencial envolvido ao chamar APIs do provedor de back-end de sua escolha. Confira as informações de preços, como as da API Gemini. Se você souber o custo por token, poderá usar as informações contextUsage da API Prompt para calcular o custo.

const COST_PER_TOKEN = 123;
const COST_LIMIT = 456;

let costSoFar = 0;

const session = await LanguageModel.create(options);

/…/

if (costSoFar < COST_LIMIT) {
  await session.prompt('Tell me a joke.');
  costSoFar = session.contextUsage * COST_PER_TOKEN;
} else {
  // Show premium AI plan promo.
}

Quando você chama uma API de nuvem diretamente de um app para dispositivos móveis ou da Web (por exemplo, as APIs que permitem acesso a modelos de IA generativa), a chave de API fica vulnerável a abusos por clientes não autorizados. Para ajudar a proteger essas APIs, se você usar o SDK híbrido do Firebase AI Logic, use o Firebase App Check para verificar se todas as chamadas de API recebidas são do seu app real. Com alguns provedores de nuvem, como o Google, também é possível aplicar verificações de origem rigorosas para garantir que apenas sites permitidos possam usar a API.

Em vez dos limites da API Prompt, por exemplo, em relação ao contextWindow da sessão, os limites do provedor de back-end são aplicados. Para o contextWindow, esses limites geralmente são muito maiores do que no dispositivo, e é possível processar grandes quantidades de dados na nuvem. Portanto, embora você precise estar ciente da diferença, na prática, provavelmente não terá problemas com isso.

Criar seu próprio back-end

Para adicionar seu próprio provedor de back-end, siga estas etapas:

Estender a classe de back-end base

Crie um novo arquivo no diretório backends/, por exemplo, backends/custom-backend.js. É necessário estender a classe PolyfillBackend e implementar os métodos principais que atendem à interface esperada.

import PolyfillBackend from './base.js';
import { DEFAULT_MODELS } from './defaults.js';

export default class CustomBackend extends PolyfillBackend {
  constructor(config) {
    // config typically comes from a window global (e.g., window.CUSTOM_CONFIG)
    super(config.modelName || DEFAULT_MODELS.custom.modelName);
  }

  // Check if the backend is configured (e.g., API key is present), if given
  // combinations of modelName and options are supported, or, for local model,
  // if the model is available.
  static availability(options) {
    return window.CUSTOM_CONFIG?.apiKey ? 'available' : 'unavailable';
  }

  // Initialize the underlying SDK or API client. With local models, use
  // monitorTarget to report model download progress to the polyfill.
  createSession(options, sessionParams, monitorTarget) {
    // Return the initialized session or client instance
  }

  // Non-streaming prompt execution
  async generateContent(contents) {
    // contents: Array of { role: 'user'|'model', parts: [{ text: string }] }
    // Return: { text: string, usage: number }
  }

  // Streaming prompt execution
  async generateContentStream(contents) {
    // Return: AsyncIterable yielding chunks
  }

  // Token counting for quota/usage tracking
  async countTokens(contents) {
    // Return: total token count (number)
  }
}

Registrar seu back-end

O polyfill usa uma estratégia de "prioridade de primeira correspondência" com base na configuração global. É necessário registrar seu back-end no arquivo prompt-api-polyfill.js adicionando-o à matriz estática #backends:

// prompt-api-polyfill.js
static #backends = [
  // ... existing backends
  {
    config: 'CUSTOM_CONFIG', // The global object to look for on `window`
    path: './backends/custom-backend.js',
  },
];

Definir um modelo padrão

Defina a identidade do modelo de fallback em backends/defaults.js. Isso é usado quando um usuário inicializa uma sessão sem especificar um modelName específico.

// backends/defaults.js
export const DEFAULT_MODELS = {
  // ...
  custom: 'custom-model-pro-v1',
};

Ativar o desenvolvimento e os testes locais

O projeto usa um script de descoberta (scripts/list-backends.js) para gerar matrizes de teste. Para incluir seu novo back-end no executor de testes, crie um arquivo .env-[name].json (por exemplo, .env-custom.json) no diretório raiz:

{
  "apiKey": "your-api-key-here",
  "modelName": "custom-model-pro-v1"
}

Verificar com os testes da plataforma da Web (WPT, na sigla em inglês)

A etapa final é garantir a conformidade. Como o polyfill é orientado por especificações, qualquer novo back-end precisa passar nos testes oficiais (ou provisórios) da plataforma da Web:

npm run test:wpt

Essa etapa de verificação garante que o back-end processe itens como AbortSignal, comandos do sistema e formatação do histórico exatamente como a especificação da API Prompt espera.

Conclusão

O polyfill ajuda você a usar a API Prompt em todas as plataformas e dispositivos. Ao programar na API bem definida da API Prompt, você se torna mais independente dos provedores de nuvem e fica o mais próximo possível da plataforma.

Em dispositivos capazes que oferecem suporte à API Prompt, o polyfill nem sequer é carregado, o que evita que os usuários façam o download de um código que não será executado. Se você tiver feedback ou encontrar um bug, abra um problema no GitHub. Divirta-se criando comandos!