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 só oferece suporte à 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 entrada somente de texto

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

Também é possível gerar saída estruturada, incluindo JSON e enumerações.

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 Gemini API escolhido (a Gemini Developer API ou a Vertex AI Gemini API).

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

• Depois de implementar o recurso, você pode permitir que os usuários finais o testem no seu app.

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) 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. Você pode 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 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 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. Configure seu projeto para usar um provedor "Gemini API".

   Recomendamos começar usando a Gemini Developer API. A qualquer momento, você pode sempre configurar a Vertex AI Gemini API (e o requisito de faturamento).

   Para o Gemini Developer API, o console vai ativar as APIs necessárias e criar uma chave da API Gemini no seu projeto.
   Não adicione essa chave da API Gemini à base de código do seu app. Saiba mais.

5. Se solicitado no fluxo de trabalho do console, siga as instruções na tela para registrar seu app e conectá-lo ao Firebase.

6. Continue para a próxima etapa deste guia para adicionar o SDK 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 JS para Web usando o npm:

   npm install firebase
   

2. Inicialize o Firebase no seu app:

   import { initializeApp } from "firebase/app";
   
   // 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: 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. Faça o seguinte:

   1. Chame getGenerativeModel após ou em uma interação do usuário final (como um clique de botão). Esse é um pré-requisito para inferenceMode.

   2. 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
// Call `getGenerativeModel` after or on an end-user interaction
// Set the mode (for example, use the on-device model if it's available)
const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_ON_DEVICE });

Etapa 5: 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 entrada somente de texto
• Gerar texto com base em entrada de texto e imagem (multimodal)

Se você quiser gerar saída estruturada (como JSON ou enumerações), 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 entrada 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 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 arquivo de cada entrada e o próprio arquivo.mimeType

Os tipos de imagem de entrada com suporte 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 {
    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).

Permitir que os usuários finais testem seu recurso

Para que os usuários finais testem seu recurso no app, você precisa se inscrever nos testes de origem do Chrome. Esses testes têm duração e uso limitados.

1. Inscreva-se no teste de origem da API Prompt do Chrome. Você vai receber um token.

2. Forneça o token em cada página da Web em que você quer que o recurso de teste seja ativado. Use uma das seguintes opções:

   • Forneça o token como uma metatag na <head> tag: <meta http-equiv="origin-trial" content="TOKEN">

   • Forneça o token como um cabeçalho HTTP: Origin-Trial: TOKEN

   • Forneça o token de maneira programática.

O que mais você sabe fazer?

Você pode 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

Como uma versão de pré-lançamento, 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 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 e embasamento com a Pesquisa Google)

• 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 da mesma forma que outras inferências usando o Firebase AI Logic SDK do cliente para Web.

Enviar feedback sobre sua experiência com Firebase AI Logic