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

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

Esta página descreve como começar a usar o SDK do cliente. Depois de concluir essa configuração padrão setup, 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.

Acessar os exemplos de código

Casos de uso recomendados e recursos compatíveis

Casos de uso recomendados :

• O uso de um modelo no dispositivo para inferência oferece:

  • Privacidade aprimorada
  • Contexto local
  • Inferência sem custo financeiro
  • Funcionalidade off-line

• O uso da funcionalidade híbrida oferece:

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

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

A inferência no dispositivo oferece suporte apenas à geração de texto de turno único (não chat), com saída de streaming ou não streaming. Ela oferece suporte aos 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 imagem 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 oGemini API provedor escolhido (aGemini Developer API ou a Agent Platform Gemini API (formerly Vertex AI)).

• Esta página descreve como começar a desenvolver usando o localhost (saiba mais sobre como usar APIs no 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 de introdução 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 flag a seguir como Ativada:

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

3. Reinicie o Google Chrome.

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

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

   Ver instruções para fazer o download do 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. É possível usar 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 o app ao Firebase

1. Faça login no Firebase console, 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 projeto e use uma das seguintes opções:

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

   • Opção 2: "Adicione o Firebase" a um projeto Google Cloud existente clicando em Adicionar o Firebase ao projeto na nuvem 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, não é necessário configurar Google Analytics para usar os Firebase AI Logic SDKs.

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 para seu projeto.

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

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

   Mais tarde, você sempre poderá configurar Agent Platform Gemini API (formerly Vertex AI) e o requisito de faturamento.

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 automaticamente o Firebase App Check para AI Logic, que é um serviço essencial para ajudar a proteger a Gemini API quando ela é acessada diretamente do seu app. Como parte da introdução (consulte as etapas mais adiante neste guia), você precisará configurar o App Check provedor de depuração para desenvolvimento local quando o App Check for aplicado.

7. Continue para a próxima etapa deste guia para adicionar 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 no 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, Firebase App Check será aplicado automaticamente para proteger a Gemini API. Para o desenvolvimento local, é necessário configurar o App Check provedor de depuração para ignorar a atestação, mantendo a aplicação de App Check.

Veja como usar o provedor de depuração ao executar seu app de 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 no 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 mais detalhes sobre o provedor de depuração (incluindo como receber um novo token de depuração), consulte a documentação App Check oficial.

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. Crie uma instância GenerativeModel. Defina o mode como um destes:

   • PREFER_ON_DEVICE: use o modelo no dispositivo se ele estiver disponível. Caso contrário, faça o fallback para 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, faça o fallback para 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

É necessário chamar initializeDeviceModel() depois ou em uma interação da página do usuário final (como um clique de 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 você quiser gerar saída estruturada (como JSON ou enums), então use um dos exemplos de "gerar texto" a seguir e adicionalmente configure o modelo para responder de acordo com um esquema fornecido.

Gerar texto com base em entradas somente de texto

É possível usar 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();

Observe que Firebase AI Logic também oferece suporte ao streaming de respostas de texto usando generateContentStream (em vez de generateContent).

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

É possível usar generateContent() para gerar texto com base em um comando que contém arquivos de texto e imagem, fornecendo o arquivo de cada entradamimeType 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();

Observe que Firebase AI Logic também oferece suporte ao streaming de respostas de texto usando generateContentStream (em vez de generateContent).

O que mais você sabe fazer?

É possível usar várias outras opções e recursos de configuração para suas experiências híbridas:

• Definir um modo de inferência

• Substituir o modelo de fallback hospedado na nuvem padrão

• 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 inferência baseada na nuvem).

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

  • Pode fazer o 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 o fallback para o modelo hospedado na nuvem. No entanto, o modo ONLY_ON_DEVICE vai gerar um erro.

• Gerar imagens usando modelos Gemini ou Imagen

  • Pode fazer o 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. É necessário fornecer arquivos como dados inline para modelos no dispositivo.

• Conversa multiturno

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

• Streaming bidirecional com a Gemini Live API

• Fornecer ferramentas ao modelo para ajudar a gerar a resposta (como chamada de função, execução de código, contexto de URL, Grounding com Google Search, e Grounding 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á fallback intuitivo.

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

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

Enviar feedback sobre sua experiência com Firebase AI Logic