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 usando a inferência híbrida com o Firebase AI Logic. A inferência híbrida permite executar inferências usando modelos no dispositivo, quando disponíveis, e, caso contrário, recorrer facilmente a 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 a 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 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 conexão de internet

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

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

• Gerar texto com base em entrada 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 tipos enumerados.

Antes de começar

Observações:

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

• Nesta página, descrevemos 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 a 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 seguinte flag como Ativada:

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

3. Reinicie o Google Chrome.

4. (Opcional) Baixe o 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 tiver feito 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.

   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 seguinte callback monitor 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 (que vai ser um projeto do Google Cloud automaticamente) ao inserir um novo nome na primeira etapa do fluxo de trabalho.

   • Opção 2: "Adicionar o Firebase" a um projeto do 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 a ele.

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

   A qualquer momento, é possível configurar o 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.

   Essa etapa do fluxo de trabalho aplica automaticamente o Firebase App Check para o AI Logic, que é um serviço essencial para ajudar a proteger o Gemini API quando ele é acessado diretamente do seu app. Como parte do processo de introdução (consulte as etapas mais adiante neste guia), você precisará configurar o provedor de depuração do App Check para desenvolvimento local quando o App Check for aplicado.

7. Siga 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 fornece 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 JS 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 do App Check para desenvolvimento local

Como parte do fluxo de trabalho de configuração guiada para AI Logic no console, o Firebase App Check é aplicado automaticamente para proteger o Gemini API. Para o desenvolvimento local, é necessário configurar o App Check provedor de depuração para ignorar o atestado, mantendo a aplicação de 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 o token de depuração.

Para mais detalhes sobre o provedor de depuração (incluindo como receber um novo token de depuração), confira 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 das seguintes opções:

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

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

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

   • ONLY_IN_CLOUD: use o modelo hospedado na nuvem, se 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

Chame 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 para um modelo

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

• Gerar texto gerado com base em entrada somente de texto
• Gerar texto com base em entrada de texto e imagem (multimodal)

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

Gerar texto com base em entrada somente de texto

Use generateContent() para gerar texto gerado 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 entrada de texto e imagem (multimodal)

É possível 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 aceitos para 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 {
    type: "inlineData",
    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ê sabe fazer?

É possível 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 substituto padrão hospedado na nuvem

• Usar a configuração do modelo para controlar as respostas

• 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 entrada de arquivo de imagem que não sejam JPEG e PNG

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

• Gerar imagens usando modelos do Gemini Nano Banana

  • Pode voltar 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 voltar 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 ao modelo ferramentas para ajudar a gerar a 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 será diferente entre os 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 que use os modelos hospedados na nuvem pode ser monitorada como qualquer outra inferência que use o SDK do cliente do Firebase AI Logic para Web.

Envie feedback sobre sua experiência com o Firebase AI Logic