Modelo de linguagem

A API Prompt permite que os desenvolvedores executem tarefas de processamento de linguagem natural diretamente no navegador usando o Gemini Nano. Essa abordagem de IA integrada garante a privacidade do usuário, reduz os custos do servidor e permite o funcionamento off-line.

1. Primeiros passos e requisitos de hardware

A API Prompt está disponível no Chrome a partir da versão 148 (computador) para Windows, macOS, Linux e Chromebook Plus.

Pré-requisitos de hardware

• Armazenamento: 22 GB de espaço livre (para o perfil e o modelo iniciais).
• Memória/CPU: 16 GB de RAM e mais de 4 núcleos de CPU.
• GPU: 4 GB de VRAM ou mais (necessário para entrada de áudio).
• Rede: necessária apenas para o download inicial do modelo.

Como inicializar a API

Verifique a disponibilidade do modelo antes de acionar um download:

const availability = await LanguageModel.availability();

// Do not call create() when unavailable — the model cannot run on this device.
if (availability !== 'unavailable') {
    const session = await LanguageModel.create({
        monitor(m) {
            // Inform the user while the model downloads so the UI doesn't appear frozen.
            m.addEventListener('downloadprogress', (e) => {
                console.log(`Downloaded ${e.loaded * 100}%`);
            });
        },
    });
}

2. Principais recursos de comandos

Os exemplos de sessão nesta seção omitem session.destroy() para fins de brevidade. Sempre chame session.destroy() quando uma sessão não for mais necessária para liberar memória do dispositivo (consulte a Seção 5).

Saída básica e em streaming

Para respostas curtas, use prompt(). Para conteúdo mais longo, use promptStreaming() para fornecer uma interface mais responsiva.

OBRIGATÓRIO: nunca atribua a saída do modelo a innerHTML. A saída do modelo não é confiável e pode conter marcações injetadas. Sempre use textContent ou um limpador.

const session = await LanguageModel.create();

// prompt() accumulates the full response before resolving — use for short, one-shot output.
const result = await session.prompt('Write a haiku about coding.');
// textContent, not innerHTML — model output is untrusted and must not be parsed as markup.
outputEl.textContent = result;

// promptStreaming() yields independent chunks that must be concatenated;
// use for longer content so each chunk can be rendered progressively.
const stream = session.promptStreaming('Write a long story about a robot.');
let completeResult = '';
for await (const chunk of stream) {
    completeResult += chunk;
    outputEl.append(chunk);
}
console.log('Full story:', completeResult);

Entrada multimodal

A API Prompt aceita entradas de texto, áudio e visuais (imagens, telas, frames de vídeo).

const session = await LanguageModel.create({
    // Declaring expected input types lets the browser optimize model loading.
    expectedInputs: [{ type: 'text' }, { type: 'image' }],
    expectedOutputs: [{ type: 'text' }],
});

const response = await session.prompt([
    {
        role: 'user',
        content: [
            { type: 'text', value: 'What is in this image?' },
            { type: 'image', value: document.querySelector('canvas') },
        ],
    },
]);

3. Gerenciamento avançado de sessões

As sessões permitem que o modelo mantenha o contexto em várias interações.

Contexto e cota

Cada sessão tem um limite máximo de tokens. É possível monitorar o uso pelo session.contextUsage e pelo session.contextWindow. Se a janela transbordar, as mensagens mais antigas (exceto o comando do sistema) serão descartadas.

Sessões de clonagem

A clonagem é eficiente para iniciar conversas paralelas que compartilham o mesmo contexto inicial (como uma personalidade do "sistema") sem reinicialização.

const mainSession = await LanguageModel.create({
    initialPrompts: [{ role: 'system', content: 'You speak like a pirate.' }],
});

const branchA = await mainSession.clone();
const branchB = await mainSession.clone();
// Destroy the base after cloning — the clones own their own context from here.
mainSession.destroy();

Restaurar sessões anteriores

Enquanto um recurso nativo de "restauração" está em desenvolvimento, é possível recriar uma sessão inserindo o histórico anterior em initialPrompts.

Observação: localStorage não é criptografado e é persistente. O histórico de conversas armazenado pode incluir informações de identificação pessoal (PII) do usuário. Considere as implicações de privacidade antes de manter o histórico de chat.

// || '[]' ensures JSON.parse never receives null when the key doesn't exist yet.
const history = JSON.parse(localStorage.getItem('chat_history') || '[]');
const session = await LanguageModel.create({
    initialPrompts: history, // Array of {role, content} objects
});

4. Saída estruturada com esquema JSON

Para evitar que o modelo adicione "conversa" (por exemplo, "Claro, aqui está seu JSON:"), use um esquema JSON no campo responseConstraint. Isso garante que a saída seja um JSON válido que pode ser analisado imediatamente.

Exemplo: classificação de sentimento

// Pass the schema as a plain object — do not JSON.stringify() it first.
const schema = {
    type: 'object',
    properties: {
        rating: { type: 'number', minimum: 1, maximum: 5 },
        is_positive: { type: 'boolean' },
    },
    required: ['rating', 'is_positive'],
};

const result = await session.prompt(
    "Rate the following feedback: 'The food was great!'",
    { responseConstraint: schema },
);

const data = JSON.parse(result);
console.log(data.rating); // 5

Restrições e prefixos

Para orientar ainda mais o modelo, preencha a resposta do assistente usando prefix: true.

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

5. Práticas recomendadas e segurança

• Limpeza de recursos: sempre chame session.destroy() quando uma conversa for concluída para liberar memória.
• Segurança da saída: a saída do modelo não é confiável. Sempre grave os resultados em textContent, não em innerHTML, para evitar a injeção de XSS de saídas de modelo maliciosas.
• Use um limpador, como a API Sanitizer nativa ou o DOMPurify, se precisar permitir HTML limitado.
• Como cancelar tarefas: use AbortController para permitir que os usuários interrompam gerações de longa duração. Transmita o signal para prompt() ou promptStreaming(), não para LanguageModel.create().
• Segurança: use políticas de permissão para controlar o acesso em iframes: <iframe src="..." allow="language-model"></iframe>.
• Design: consulte o Guia People + AI para garantir uma implementação responsável da IA.

Ao combinar saídas estruturadas com um gerenciamento de sessão robusto, os desenvolvedores podem criar aplicativos de IA complexos e com estado que são executados inteiramente no dispositivo do usuário.

O que fazer e o que não fazer

Para conferir a lista completa de práticas recomendadas e não recomendadas, acesse https://developer.chrome.com/docs/ai/built-in-ai-dos-donts.md.txt. Veja abaixo o gist:

Preparar o modelo em um tempo razoável

Aplica-se a: todas as APIs, por exemplo, Summarizer, Translator e Writer.

O que fazer: inicialize a sessão assim que estabelecer claramente a intenção do usuário de usar o recurso de IA. Por exemplo, quando um usuário navega até uma superfície de ferramentas de IA relevante, passa o cursor sobre um espaço de trabalho de IA ou interage com a interface ao redor do recurso. O pré-aquecimento da sessão permite que o modelo seja carregado na memória em segundo plano enquanto o usuário configura a tarefa, eliminando a latência de inicialização a frio. Tente estar um passo à frente iniciando a próxima tarefa da IA mais provável assim que começar a renderizar o resultado atual, por exemplo, se o recurso for projetado para uso iterativo.

Não faça: a menos que seja necessário, não espere o usuário clicar em "Gerar" para inicializar a sessão. Isso leva a um atraso de inicialização a frio, porque o modelo precisa primeiro ser carregado na memória e preparar o pipeline de execução.

Definir comandos iniciais durante a criação

Válido para: API Prompt.

Recomendação: forneça instruções do sistema durante a inicialização da sessão para melhorar a velocidade do primeiro comando.

Não faça o seguinte: iniciar com uma sessão vazia e enviar instruções do sistema como parte da primeira chamada prompt(). Isso aumenta a latência porque força o modelo a processar essas instruções no último momento.

Clonar sessões para tarefas repetitivas

Válido para: API Prompt.

Para a API Prompt, cada sessão rastreia o contexto da conversa, considerando todas as interações anteriores. Como um clone herda tudo da sessão mãe, incluindo os comandos iniciais e todo o histórico de interações até o momento da clonagem, estruture o uso para somente herdar o que você precisa.

O que fazer:

• Crie uma sessão base: para lidar com tarefas não relacionadas de forma eficiente, crie uma sessão base que contenha apenas as instruções do sistema e nenhum contexto de conversa anterior.
• Clone o valor de referência: use clone() nessa sessão de base para novas tarefas para economizar o overhead de reanalisar as instruções do sistema. Isso permite criar conversas paralelas ou redefinir uma tarefa para o estado inicial.

O que não fazer:

• Não reutilize a mesma sessão para tarefas não relacionadas e evite clonar qualquer sessão que já contenha um histórico de interações desnecessário. Os dois padrões podem fazer com que um contexto anterior não relacionado interfira na tarefa atual.
• Não chame create() repetidamente com instruções idênticas do sistema. Use o padrão de clonagem para otimizar o desempenho.

Destruir sessões não utilizadas

Aplicável a: todas as APIs.

O que fazer: chame explicitamente destroy() em sessões que não são mais necessárias para liberar memória quando um recurso não estiver mais em uso. Se você usar um padrão de clonagem, mantenha a sessão base e destrua os clones que não forem mais necessários.

Não: mantenha várias sessões grandes ativas. Cada sessão consome memória, o que cria um uso desnecessário de recursos e pode se tornar um problema. As sessões serão limpas naturalmente pelo coletor de lixo, mas chamar destroy() libera memória mais rapidamente.

Renderizar respostas de streaming com segurança e eficiência

Aplicável a: todas as APIs com suporte a streaming (Prompt, Summarizer, Writer, Rewriter e Translator).

O que fazer: trate todas as saídas de LLM como conteúdo não confiável. Limpe toda a saída combinada, não apenas partes, porque o código malicioso pode ser dividido entre as atualizações. Antes de renderizar, use a API Sanitizer, quando disponível. Para evitar uma queda na performance, use um analisador de Markdown de streaming, como o streaming-markdown.

Não faça o seguinte: definir diretamente innerHTML em cada atualização de bloco. Isso é lento, especialmente com formatação complexa, como destaque de sintaxe, e vulnerável a injeção.

Otimizar a entrada para aumentar a velocidade

Aplicável a: todas as APIs.

O que fazer: transmita ao modelo apenas o que for estritamente necessário. Remova tudo o que for irrelevante para a tarefa em questão. Para conjuntos de dados grandes, forneça uma visão geral curta e uma pequena seleção de itens relevantes.

Não faça o seguinte: enviar texto bruto não processado, metadados desnecessários, tags HTML ou listas grandes não filtradas para as APIs. A latência aumenta significativamente com o tamanho da entrada, o que pode fazer com que o recurso de IA pareça quebrado em muitos dispositivos.

Usar saída estruturada para resultados previsíveis

Válido para: API Prompt.

O que fazer: quando você precisar que o modelo retorne dados em um formato específico, use a saída estruturada fornecendo um campo responseConstraint para fornecer um esquema JSON. Isso garante que a saída seja previsível e evita a necessidade de pós-processamento complexo ou análise manual.

Não faça o seguinte: confiar apenas em instruções de linguagem natural (como "gerar apenas JSON"). Os modelos podem incluir preenchimentos de conversa que interrompem o analisador.

Desvincular a geração das restrições de duração

Aplica-se a: API Prompt, já que é a única que oferece suporte a esquemas de saída estruturados.

O que fazer: deixe o modelo gerar a resposta naturalmente e use a lógica do lado do cliente para truncar o texto de acordo com a interface.

Não faça o seguinte: aplicar limites de caracteres rígidos, como maxLength: 125, usando esquemas de saída estruturados. Quando a resposta de um modelo é mais longa do que o limite definido, ele pode mudar para tokens de alta densidade, como idiomas estrangeiros ou emojis, para compactar o significado, resultando em uma saída sem sentido.

Manter o usuário informado

Aplicável a: todas as APIs.

O que fazer: dependendo da complexidade e da duração esperada da tarefa, use animações, dicas visuais e indicadores de progresso para manter o usuário informado. A abordagem ideal depende do seu caso de uso e do tamanho esperado da saída da API. Algumas ideias:

• Streaming para conteúdo longo: para resumos ou chats, o streaming cria um efeito de máquina de escrever por token por padrão. Isso pode parecer natural e fornecer feedback imediato.
• Sem streaming para tarefas curtas (ou tarefas assíncronas longas): para saídas curtas, como texto alternativo, a ausência de streaming pode criar uma interface mais refinada. Ele também dá tempo para preparar de forma especulativa a próxima tarefa de IA enquanto a atual é renderizada. Essa abordagem também funciona para tarefas assíncronas ou em segundo plano mais longas. Se o usuário não estiver bloqueado na saída para continuar a jornada, não há necessidade urgente de produzir a saída conforme ela acontece. Sinalize que o processo está em andamento na interface.
• Transições visuais para atualizações: ao traduzir ou reescrever texto, use animações, como a transformação de palavras.

Restrição: não atualize a interface sem dicas visuais.

Alinhar-se ao modelo mental de tempo e trabalho do usuário

Aplicável a: todas as APIs.

Recomendação: considere um atraso artificial de um ou dois segundos se uma resposta for quase instantânea. Paradoxalmente, os usuários podem achar os resultados mais confiáveis quando percebem um processo de geração que se alinha à dificuldade percebida da tarefa. Use animações para indicar que um processo de IA ocorreu.

Não: surpreenda os usuários com substituições instantâneas da interface.

Permitir que os usuários naveguem e desfaçam edições de IA rapidamente

Aplicável a: todas as APIs.

O que fazer: equipe sua interface com um seletor numérico ou histórico de navegação que permita aos usuários explorar diferentes resultados com confiança e desfazer rapidamente as edições da IA. Isso garante que as diferentes versões ainda estejam prontamente disponíveis.

Não faça o seguinte: substituir o rascunho anterior do usuário ou um resultado da IA que ele tenha gostado sem uma maneira de voltar, reverter ou comparar versões.

Capacitar o controle e as substituições do usuário

Aplicável a: todas as APIs.

O que fazer: o usuário deve ser o editor final de todo o conteúdo gerado. Ofereça substituições intuitivas para que o usuário mantenha a propriedade total do resultado final. As APIs podem produzir resultados incorretos.

Não: force um resultado gerado com IA como a única opção.

Armazenar em cache os resultados de tarefas recorrentes

Aplicável a: todas as APIs.

Recomendado: implemente um cache de resultados local (por exemplo, usando sessionStorage ou IndexedDB) para entradas ou consultas repetidas. Normalize a entrada cortando espaços em branco e usando letras minúsculas para aumentar as ocorrências em cache. Para entradas pesadas, como imagens, gere um hash para usar como chave de cache. Defina um time to live (TTL) conservador para o cache ou exiba resultados armazenados em cache enquanto eles são atualizados em segundo plano. Permita que o usuário acione uma nova inferência se o resultado não for satisfatório.

Não faça o seguinte: executar novamente a mesma inferência para uma consulta de pesquisa repetida ou uma entrada de dados idêntica em que a variabilidade não é desejável, por exemplo, quando um usuário navega entre os resultados da pesquisa. Isso otimiza a capacidade de resposta e o uso eficiente da computação local.

6. Estratégias de fallback

Antes de usar, verifique se o objeto LanguageModel está disponível no escopo global:

if ('LanguageModel' in self) {
  // The Prompt API is supported.
} else {
  // Execute fallback strategy
}

Se a API Prompt não for compatível ou as verificações de disponibilidade retornarem "indisponível", você precisará usar um substituto:

• Fallback de API remota: redirecione a solicitação de detecção para um endpoint de servidor ou uma API do Cloud (como a API Gemini da Vertex AI).
• Fallback da API local: redirecione a solicitação de detecção para um endpoint local, por exemplo, usando o Transformers.js.