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

É possível criar apps e recursos da Web com tecnologia de IA usando 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 recorrer facilmente a modelos hospedados na nuvem quando não estão (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.

A inferência no dispositivo via Firebase AI Logic é compatível com apps da Web que usam o SDK do Firebase AI Logic v12.5.0 ou mais recente e são executados no Chrome para computador (versão 139 ou mais recente).

arrow_downward Ir para exemplos de código de visualização

Casos de uso e recursos compatíveis

Dependendo dos casos de uso do seu app, você pode aproveitar vários benefícios das experiências híbridas ou no dispositivo:

• Benefícios de usar um modelo no dispositivo para inferência:

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

• Benefícios de usar uma abordagem híbrida:

  • Oferecer uma experiência semelhante no app, independente do dispositivo do usuário final
  • Melhorar a disponibilidade dos recursos de IA generativa, independentemente da conectividade com a Internet, das limitações de cota ou dos recursos do dispositivo

Recursos de inferência no dispositivo compatíveis

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), especificamente os seguintes recursos:

• 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.

• Gerar saída estruturada, incluindo JSON e tipos enumerados.

Confira a lista de recursos ainda não compatíveis com inferência híbrida ou no dispositivo na parte de baixo desta página.

APIs e plataformas compatíveis

As seções a seguir descrevem as APIs, as plataformas e os navegadores compatíveis.

APIs compatíveis com inferência na nuvem e no dispositivo

• A inferência na nuvem usa o provedor de Gemini API escolhido (Gemini Developer API ou Agent Platform Gemini API (formerly Vertex AI)).

• A inferência no dispositivo usa a API Prompt do Chrome.

Plataformas e navegadores compatíveis

Para inferência no dispositivo (que usa a API Prompt do Chrome), o usuário final do seu app precisa estar executando o Chrome no computador (versão 139 ou mais recente). Saiba mais na documentação do Chrome.

Começar no localhost

Estas etapas de introdução descrevem a configuração geral necessária para qualquer solicitação de comando com suporte que você queira enviar.

Saiba mais sobre como usar APIs no localhost na documentação do Chrome.

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, mas 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 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 (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 custos financeiros.

   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 pelo 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 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 o token de depuração.

Para saber mais 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, use o 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, use o 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 entradas 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 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 {
    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 outras opções e recursos de configuração para suas experiências híbridas:

• Defina um modo de inferência.

• Determinar se a inferência foi feita no dispositivo ou na nuvem.

• Substitua o modelo substituto padrão hospedado na nuvem.

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

• Gerar saída estruturada (como JSON e tipos enumerados).

Recursos ainda não disponíveis

Nem todos os recursos do SDK da Web ou dos modelos hospedados na nuvem estão disponíveis para inferência híbrida ou no dispositivo.

Recursos ainda não disponíveis para implementações híbridas

Os recursos a seguir não podem ser usados com implementações híbridas (nem no dispositivo nem por substituição na nuvem):

• Gemini Live API: o streaming bidirecional em tempo real não é compatível.

• Modelos de comando do servidor: não há suporte para modelos de comando do servidor gerenciados.

• Contagem de tokens: não é recomendável confiar na contagem de tokens porque ela varia entre os modelos hospedados na nuvem e no dispositivo. Portanto, não há um substituto intuitivo.

Recursos ainda nã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 estão disponíveis para modelos hospedados na nuvem.

• 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.

• 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 multimodais de áudio, vídeo e documentos (PDFs)

  • 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.

• 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)

• O AI Monitoring no console do Firebase não mostra dados de inferência no dispositivo (incluindo registros do dispositivo). No entanto, qualquer inferência que use um modelo hospedado na nuvem pode ser monitorada como outras inferências por meio do Firebase AI Logic.

Outras limitações

Além do que foi mencionado acima, a inferência no dispositivo tem as seguintes limitações:

• O usuário final do app precisa estar executando o Chrome para computador (versão 139 ou mais recente) com as flags necessárias ativadas.

• O modelo no dispositivo requer espaço de armazenamento suficiente no dispositivo do usuário para o download inicial do modelo.

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