Crie experiências híbridas em apps da Web com modelos hospedados na nuvem e no dispositivo

Crie apps da Web e recursos com tecnologia de IA usando a inferência híbrida com Firebase AI Logic. A inferência híbrida permite executar a inferência usando modelos no dispositivo quando disponíveis e fazer fallback para modelos hospedados na nuvem (e vice-versa).

Nesta página, descrevemos como começar a usar o SDK do cliente. Depois de concluir essa configuração padrão, confira as outras opções e recursos de configuração (como saída estruturada).

A inferência no dispositivo é compatível com apps da Web executados no Chrome para computador.

Ir para os exemplos de código

Casos de uso recomendados e recursos disponíveis

Casos de uso recomendados:

• Usar um modelo no dispositivo para inferência oferece:

  • Privacidade reforçada
  • Contexto local
  • Inferência sem custo financeiro
  • Funcionalidade off-line

• Usar ofertas de funcionalidade híbrida:

  • Alcance 100% do seu público-alvo, independente da disponibilidade de modelos no dispositivo ou da conectividade com a Internet

Recursos e funcionalidades compatíveis para inferência no dispositivo:

A inferência no dispositivo só é compatível com geração de texto em uma única interação (não chat), com saída de streaming ou sem streaming. Ele é compatível com os seguintes recursos de geração de texto:

• Gerar texto com base em entradas somente de texto

• Gerar texto com base em entradas de texto e imagem, especificamente tipos de imagens de entrada JPEG e PNG

Também é possível gerar saída estruturada, incluindo JSON e enums.

Antes de começar

Observações:

• A inferência usando um modelo no dispositivo usa a API Prompt do Chrome; já a inferência usando um modelo hospedado na nuvem usa o provedor Gemini API escolhido (o Gemini Developer API ou o Agent Platform Gemini API (formerly Vertex AI)).

• Nesta página, descrevemos como começar a desenvolver usando localhost. Saiba mais sobre como usar APIs em localhost na documentação do Chrome.

  Depois de concluir essa configuração padrão, confira as outras opções e recursos de configuração, como saída estruturada.

Começar no localhost

Estas etapas iniciais descrevem a configuração geral necessária para qualquer solicitação de comando compatível que você queira enviar.

Etapa 1: configurar o Chrome e a API Prompt para inferência no dispositivo

1. Verifique se você está usando uma versão recente do Chrome. Atualize em chrome://settings/help.
   A inferência no dispositivo está disponível no Chrome v139 e versões mais recentes.

2. Ative o modelo multimodal no dispositivo definindo a seguinte flag como Enabled:

   • chrome://flags/#prompt-api-for-gemini-nano-multimodal-input

3. Reinicie o Chrome.

4. (Opcional) Faça o download do modelo no dispositivo antes da primeira solicitação.

   A API Prompt está integrada ao Chrome, mas o modelo no dispositivo não está disponível por padrão. Se você ainda não tiver baixado o modelo antes da primeira solicitação de inferência no dispositivo, a solicitação vai iniciar automaticamente o download do modelo em segundo plano.

   Confira as instruções para baixar o modelo no dispositivo

   1. Abra Ferramentas para desenvolvedores > Console.

   2. Execute o comando a seguir:

      await LanguageModel.availability();
      

   3. Verifique se a saída é available, downloading ou downloadable.

   4. Se a saída for downloadable, inicie o download do modelo executando:

      await LanguageModel.create();
      

   5. Use o callback monitor a seguir para detectar o progresso do download e garantir que o modelo esteja available antes de fazer solicitações:

      const session = await LanguageModel.create({
        monitor(m) {
          m.addEventListener("downloadprogress", (e) => {
            console.log(`Downloaded ${e.loaded * 100}%`);
          });
        },
      });
      

Etapa 2: configurar um projeto do Firebase e conectar seu app a ele

1. Faça login no console do Firebase e selecione seu projeto do Firebase.

   Ainda não tem um projeto do Firebase?

   Se você ainda não tiver um projeto do Firebase, clique no botão para criar um novo e use uma das seguintes opções:

   • Opção 1: crie um projeto do Firebase totalmente novo (e o projeto do Google Cloud automaticamente) inserindo um novo nome na primeira etapa do fluxo de trabalho.

   • Opção 2: "Adicionar o Firebase" a um projeto Google Cloud clicando em Adicionar o Firebase ao projeto do Google Cloud (na parte de baixo da página). Na primeira etapa do fluxo de trabalho, comece a digitar o nome do projeto e selecione-o na lista exibida.

   Conclua as etapas restantes do fluxo de trabalho na tela para criar um projeto do Firebase. Quando solicitado, você não vai precisar configurar o Google Analytics para usar os SDKs do Firebase AI Logic.

2. No console do Firebase, acesse Serviços de IA > Lógica de IA.

3. Clique em Começar para iniciar um fluxo de trabalho guiado que ajuda a configurar as APIs necessárias e os recursos do projeto.

4. Se solicitado, siga as instruções na tela para registrar o app e adicionar a configuração do Firebase.

5. Quando for solicitado a escolher um "provedor da API Gemini", recomendamos selecionar a API Gemini Developer, que permite começar rapidamente sem custos financeiros.

   A qualquer momento depois, você pode configurar o Agent Platform Gemini API (formerly Vertex AI) (e o requisito de faturamento dele).

6. Continue no fluxo de trabalho para configurar as APIs necessárias e os serviços associados para Firebase AI Logic.

   A partir do início de julho de 2026, essa etapa do fluxo de trabalho vai aplicar Firebase App Check para AI Logic de forma automática. Esse é um serviço essencial para proteger o Gemini API quando ele é acessado diretamente do app. Como parte do processo de início (confira as etapas mais adiante neste guia), você precisará configurar o provedor de depuração App Check para o desenvolvimento local quando o App Check for aplicado.

7. Continue para a próxima etapa deste guia e adicione os SDKs necessários ao seu app.

Etapa 3: adicionar o SDK

A biblioteca do Firebase oferece acesso às APIs para interagir com modelos generativos. A biblioteca está incluída como parte do SDK do Firebase para JavaScript para Web.

1. Instale o SDK do Firebase para JavaScript para Web usando o npm:

   npm install firebase
   

2. Inicialize o Firebase no seu app:

   import { initializeApp } from "firebase/app";
   import { initializeAppCheck } from "firebase/app-check";
   
   // TODO(developer) Replace the following with your app's Firebase configuration
   // See: https://firebase.google.com/docs/web/learn-more#config-object
   const firebaseConfig = {
     // ...
   };
   
   // Initialize FirebaseApp
   const firebaseApp = initializeApp(firebaseConfig);
   

Etapa 4: configurar o provedor de depuração App Check para desenvolvimento local

A partir do início de julho de 2026, como parte do fluxo de trabalho de configuração guiada para AI Logic no console, a Firebase App Check será aplicada automaticamente para proteger o Gemini API. Para desenvolvimento local, é necessário configurar o provedor de depuração do App Check para ignorar o atestado, mantendo a aplicação do App Check.

Veja como usar o provedor de depuração ao executar seu app em localhost de forma interativa (por exemplo, durante o desenvolvimento local):

1. No build de depuração, ative o modo de depuração definindo self.FIREBASE_APPCHECK_DEBUG_TOKEN como true antes de inicializar App Check. Exemplo:

   self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
   initializeAppCheck(firebaseApp, { /* App Check options */ });
   

2. Acesse seu app da Web localmente e abra as ferramentas para desenvolvedores do navegador. No console de depuração, você verá um token:

   AppCheck debug token: "123a4567-b89c-12d3-e456-789012345678".
   You will need to safelist it in the Firebase console for it to work.
   

3. Registre seu token de depuração com App Check:

   1. No console do Firebase, acesse a guia Segurança > App Check > Apps.

   2. Encontre seu app, clique no menu flutuante (more_vert) e selecione Gerenciar tokens de depuração.

   3. Siga as instruções na tela para registrar seu token de depuração.

Para detalhes sobre o provedor de depuração, incluindo como conseguir um novo token de depuração, consulte a documentação oficial do App Check.

Etapa 5: inicializar o serviço e criar uma instância de modelo

Configure o seguinte antes de enviar uma solicitação de comando ao modelo:

1. Inicialize o serviço para o provedor de API escolhido.

2. Criar uma instância GenerativeModel. Defina mode como uma destas opções:

   • PREFER_ON_DEVICE: use o modelo no dispositivo se ele estiver disponível. Caso contrário, use o modelo hospedado na nuvem.

   • ONLY_ON_DEVICE: use o modelo no dispositivo se ele estiver disponível. Caso contrário, gere uma exceção.

   • PREFER_IN_CLOUD: use o modelo hospedado na nuvem se ele estiver disponível. Caso contrário, use o modelo no dispositivo.

   • ONLY_IN_CLOUD: use o modelo hospedado na nuvem se ele estiver disponível. Caso contrário, gere uma exceção.

import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend, InferenceMode } from "firebase/ai";

// TODO(developer) Replace the following with your app's Firebase configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp
const firebaseApp = initializeApp(firebaseConfig);

// Initialize the Gemini Developer API backend service
const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

// Create a `GenerativeModel` instance
// Set the mode (for example, use the on-device model if it's available)
const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_ON_DEVICE });

Etapa 6: inicializar o modelo no dispositivo

Você precisa chamar initializeDeviceModel() depois ou durante uma interação do usuário final com a página (como um clique em um botão) e antes de enviar uma solicitação de comando ao modelo. Saiba mais sobre o requisito de ativação do usuário na documentação do Chrome.

import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend, InferenceMode } from "firebase/ai";

// TODO(developer) Replace the following with your app's Firebase configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp
const firebaseApp = initializeApp(firebaseConfig);

// Initialize the Gemini Developer API backend service
const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

// Create a `GenerativeModel` instance
// Set the mode (for example, use the on-device model if it's available)
const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_ON_DEVICE });

// `initializeDeviceModel` must be called:
// (1) after or on an end-user page interaction such as a button click
// and
// (2) before any queries to the model (such as `generateContent()`)
// You may want to `await` this promise if using `ONLY_ON_DEVICE` (see note below).
model.initializeDeviceModel((val) =>
  // Example: "Download progress: 72.62%""
  console.log(`Download progress: ${Math.round(val*10000) / 100}%`)
);

Etapa 7: enviar uma solicitação de comando a um modelo

Esta seção mostra como enviar vários tipos de entrada para gerar diferentes tipos de saída, incluindo:

• Gerar texto com base em entradas somente de texto
• Gerar texto com base em entradas de texto e imagem (multimodais)

Se quiser gerar uma saída estruturada (como JSON ou tipos enumerados), use um dos exemplos de "gerar texto" a seguir e configure o modelo para responder de acordo com um esquema fornecido.

Gerar texto com base em entradas somente de texto

Você pode usar o generateContent() para gerar texto com base em um comando que contém texto:

// Imports + initialization of FirebaseApp and backend service + creation of model instance

// Wrap in an async function so you can use await
async function run() {
  // Provide a prompt that contains text
  const prompt = "Write a story about a magic backpack."

  // To generate text output, call `generateContent` with the text input
  const result = await model.generateContent(prompt);

  const response = result.response;
  const text = response.text();
  console.log(text);
}

run();

O Firebase AI Logic também é compatível com o streaming de respostas de texto usando generateContentStream (em vez de generateContent).

Gerar texto com base em entradas de texto e imagem (multimodais)

Você pode usar generateContent() para gerar texto com base em um comando que contém arquivos de texto e imagem, fornecendo o mimeType de cada arquivo de entrada e o próprio arquivo.

Os tipos de imagem de entrada compatíveis com a inferência no dispositivo são PNG e JPEG.

// Imports + initialization of FirebaseApp and backend service + creation of model instance

// Converts a File object to a Part object.
async function fileToGenerativePart(file) {
  const base64EncodedDataPromise = new Promise((resolve) => {
    const reader = new FileReader();
    reader.onloadend = () => resolve(reader.result.split(',')[1]);
    reader.readAsDataURL(file);
  });
  return {
    inlineData: { data: await base64EncodedDataPromise, mimeType: file.type },
  };
}

async function run() {
  // Provide a text prompt to include with the image
  const prompt = "Write a poem about this picture:";

  const fileInputEl = document.querySelector("input[type=file]");
  const imagePart = await fileToGenerativePart(fileInputEl.files[0]);

  // To generate text output, call `generateContent` with the text and image
  const result = await model.generateContent([prompt, imagePart]);

  const response = result.response;
  const text = response.text();
  console.log(text);
}

run();

O Firebase AI Logic também é compatível com o streaming de respostas de texto usando generateContentStream (em vez de generateContent).

O que mais você pode fazer?

Você pode usar várias opções e recursos de configuração adicionais para suas experiências híbridas:

• Definir um modo de inferência

• Substituir o modelo de substituição padrão hospedado na nuvem

• Usar a configuração do modelo para controlar respostas (como temperatura)

• Gerar saída estruturada (como JSON)

Recursos ainda não disponíveis para inferência no dispositivo

Nem todos os recursos do SDK da Web estão disponíveis para inferência no dispositivo. Os recursos a seguir ainda não são compatíveis com a inferência no dispositivo, mas geralmente estão disponíveis para a inferência baseada na nuvem.

• Gerar texto com base em tipos de entrada de arquivo de imagem diferentes de JPEG e PNG

  • Pode fazer fallback para o modelo hospedado na nuvem. No entanto, o modo ONLY_ON_DEVICE vai gerar um erro.

• Gerar texto com base em entradas de áudio, vídeo e documentos (como PDFs)

  • Pode fazer fallback para o modelo hospedado na nuvem. No entanto, o modo ONLY_ON_DEVICE vai gerar um erro.

• Gerar imagens usando modelos do Gemini

  • Pode fazer fallback para o modelo hospedado na nuvem. No entanto, o modo ONLY_ON_DEVICE vai gerar um erro.

• Fornecer arquivos usando URLs em solicitações multimodais. Você precisa fornecer arquivos como dados inline para modelos no dispositivo.

• Conversa multiturno

  • Pode fazer fallback para o modelo hospedado na nuvem. No entanto, o modo ONLY_ON_DEVICE vai gerar um erro.

• Streaming bidirecional com o Gemini Live API

• Fornecer ferramentas ao modelo para ajudar na geração da resposta (como chamada de função, execução de código, contexto de URL, embasamento com Google Search e embasamento com Google Maps)

• Contar tokens

  • Sempre gera um erro. A contagem vai variar entre modelos hospedados na nuvem e no dispositivo, então não há um substituto intuitivo.

• Monitoramento de IA no console do Firebase para inferência no dispositivo.

  • Qualquer inferência usando os modelos hospedados na nuvem pode ser monitorada da mesma forma que outras inferências usando o SDK do cliente Firebase AI Logic para Web.

Envie feedback sobre sua experiência com Firebase AI Logic