Criar experiências híbridas com modelos no dispositivo e hospedados na nuvem

Crie apps e recursos com tecnologia de IA usando 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 quando não estão.

Com esse lançamento, a inferência híbrida está disponível usando o SDK do cliente Firebase AI Logic para Web com suporte à inferência no dispositivo para o Chrome no 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 do modelo no dispositivo

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

• Geração de conteúdo com interação única, com e sem streaming
• 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
• Gerar saída estruturada, incluindo JSON e enums

Primeiros passos

Este guia mostra como começar a usar o SDK Firebase AI Logic para Web e realizar inferência híbrida.

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 Vertex AI Gemini API).

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

1. Baixe o build mais recente do Chrome Beta.

   A inferência no dispositivo está disponível no Chrome v138 e em versões mais recentes.

2. Ative a API Prompt na sua instância do Chrome definindo as seguintes flags:

   • chrome://flags/#optimization-guide-on-device-model: defina como Ativado.
   • chrome://flags/#prompt-api-for-gemini-nano: defina como Ativado.

   Saiba mais sobre como usar APIs no localhost na documentação do Chrome. Se quiser, participe do Programa de prévia antecipada (EPP) do Chrome para enviar feedback.

3. Ative o modelo multimodal no dispositivo definindo a seguinte flag:

   • chrome://flags/#prompt-api-for-gemini-nano-multimodal-input: defina como Ativado.

4. Verifique a API localmente:

   1. Reinicie o Chrome.

   2. Abra Ferramentas para desenvolvedores > Console.

   3. Execute o comando a seguir:

      await LanguageModel.availability();
      

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

   5. Se a saída for downloadable, inicie o download do modelo executando await LanguageModel.create();. Caso contrário, a primeira solicitação de inferência no dispositivo vai iniciar um download do modelo em segundo plano, o que pode levar vários minutos.

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 tem um projeto do Firebase, clique em Criar projeto 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 "Criar projeto".

   • Opção 2: "Adicionar o Firebase" a um projeto Google Cloud existente selecionando o nome do projeto Google Cloud no menu suspenso da primeira etapa do fluxo de trabalho "Criar projeto".

   Quando solicitado, você não vai precisar configurar o Google Analytics para usar os SDKs do Firebase AI Logic.

2. No console Firebase, acesse a página Firebase AI Logic.

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. Selecione o provedor "Gemini API" que você quer usar com os SDKs Firebase AI Logic. Você pode configurar e usar o outro provedor de API mais tarde, se quiser.

   • Gemini Developer API: faturamento opcional (disponível no plano de preços Spark sem custos financeiros, e você pode fazer upgrade depois, se quiser)
     . O console vai ativar as APIs necessárias e criar uma chave de API Gemini no seu projeto.
     Não adicione essa chave de API Gemini à base de código do seu app. Saiba mais.

   • Vertex AI Gemini API: faturamento obrigatório (requer o plano de preços Blaze de pagamento por uso)
     . O console ajuda você a configurar o faturamento e ativar as APIs necessárias no seu projeto.

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 e adicione o SDK ao 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.

   O recurso híbrido é lançado com uma tag npm diferente. Portanto, inclua-o no comando de instalação.

   npm install firebase@eap-ai-hybridinference
   

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

Antes de enviar um comando para um modelo Gemini, inicialize o serviço do provedor de API escolhido e crie uma instância GenerativeModel.

Defina o mode como uma das seguintes opções:

• prefer_on_device: configura o SDK para usar o modelo no dispositivo, se disponível, ou fazer fallback para o modelo hospedado na nuvem.

• only_on_device: configura o SDK para usar o modelo no dispositivo ou gerar uma exceção.

• only_in_cloud: configura o SDK para nunca usar o modelo no dispositivo.

Por padrão, quando você usa prefer_on_device ou only_in_cloud, o modelo hospedado na nuvem é gemini-2.0-flash-lite, mas é possível substituir o padrão.

import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend } 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 to use on-device model when possible
const model = getGenerativeModel(ai, { mode: "prefer_on_device" });

Enviar uma solicitação de comando para um modelo

Esta seção fornece exemplos de 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 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 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();

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

É possível usar o 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 que mais você sabe fazer?

Além dos exemplos acima, você também pode usar modos de inferência alternativos, substituir o modelo de substituição padrão e usar a configuração do modelo para controlar as respostas.

Usar modos de inferência alternativos

Os exemplos acima usaram o modo prefer_on_device para configurar o SDK de modo que ele use um modelo no dispositivo, se disponível, ou volte para um modelo hospedado na nuvem. O SDK oferece dois modos de inferência alternativos: only_on_device e only_in_cloud.

• Use o modo only_on_device para que o SDK só possa usar um modelo no dispositivo. Nessa configuração, a API vai gerar um erro se um modelo no dispositivo não estiver disponível.

  const model = getGenerativeModel(ai, { mode: "only_on_device" });
  

• Use o modo only_in_cloud para que o SDK só possa usar um modelo hospedado na nuvem.

  const model = getGenerativeModel(ai, { mode: "only_in_cloud" });
  

Substituir o modelo de fallback padrão

Ao usar o modo prefer_on_device, o SDK volta a usar um modelo hospedado na nuvem se um modelo no dispositivo não estiver disponível. O modelo de substituição padrão hospedado na nuvem é gemini-2.0-flash-lite. Esse modelo hospedado na nuvem também é o padrão quando você usa o modo only_in_cloud.

Use a opção de configuração inCloudParams para especificar um modelo alternativo padrão hospedado na nuvem:

const model = getGenerativeModel(ai, {
  mode: 'prefer_on_device',
  inCloudParams: {
    model: "gemini-2.5-flash"
  }
});

Encontre os nomes de todos os modelos do Gemini compatíveis.

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

Em cada solicitação a um modelo, é possível enviar uma configuração para controlar como ele gera uma resposta. Os modelos hospedados na nuvem e no dispositivo oferecem opções de configuração diferentes.

A configuração é mantida durante toda a vida útil da instância. Se você quiser usar uma configuração diferente, crie uma nova instância GenerativeModel com essa configuração.

Definir a configuração de um modelo hospedado na nuvem

Use a opção inCloudParams para configurar um modelo do Gemini hospedado na nuvem. Saiba mais sobre os parâmetros disponíveis.

const model = getGenerativeModel(ai, {
  mode: 'prefer_on_device',
  inCloudParams: {
    model: "gemini-2.5-flash"
    temperature: 0.8,
    topK: 10
  }
});

Definir a configuração de um modelo no dispositivo

A inferência usando um modelo no dispositivo usa a API Prompt do Chrome.

Use a opção onDeviceParams para configurar um modelo no dispositivo. Saiba mais sobre os parâmetros disponíveis.

const model = getGenerativeModel(ai, {
  mode: 'prefer_on_device',
  onDeviceParams: {
    createOptions: {
      temperature: 0.8,
      topK: 8
    }
  }
});

Definir a configuração para saída estruturada

A geração de saída estruturada (como JSON e enums) é compatível com a inferência usando modelos hospedados na nuvem e no dispositivo.

Para inferência híbrida, use inCloudParams e onDeviceParams para configurar o modelo e gerar uma saída estruturada. Para os outros modos, use apenas a configuração aplicável.

• Para inCloudParams: especifique o responseMimeType adequado (neste exemplo, application/json) e o responseSchema que você quer que o modelo use.

• Para onDeviceParams: especifique o responseConstraint que você quer que o modelo use.

Saída JSON

O exemplo a seguir adapta o exemplo de saída JSON geral para inferência híbrida:

import {
  getAI,
  getGenerativeModel,
  Schema
} from "firebase/ai";

const jsonSchema = Schema.object({
 properties: {
    characters: Schema.array({
      items: Schema.object({
        properties: {
          name: Schema.string(),
          accessory: Schema.string(),
          age: Schema.number(),
          species: Schema.string(),
        },
        optionalProperties: ["accessory"],
      }),
    }),
  }
});

const model = getGenerativeModel(ai, {
  mode: 'prefer_on_device',
  inCloudParams: {
    model: "gemini-2.5-flash"
    generationConfig: {
      responseMimeType: "application/json",
      responseSchema: jsonSchema
    },
  }
  onDeviceParams: {
    promptOptions: {
      responseConstraint: jsonSchema
    }
  }
});

Saída de enumeração

Como acima, mas adaptando a documentação sobre saída de enumeração para inferência híbrida:

// ...

const enumSchema = Schema.enumString({
  enum: ["drama", "comedy", "documentary"],
});

const model = getGenerativeModel(ai, {

// ...

    generationConfig: {
      responseMimeType: "text/x.enum",
      responseSchema: enumSchema
    },

// ...

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

Como é uma versão experimental, 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 fallback para o modelo hospedado na nuvem. No entanto, o modo only_on_device vai gerar um erro.

• Geração de 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 Gemini ou Imagen

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

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

  • Isso não é compatível com o SDK do cliente Firebase AI Logic para Web, nem mesmo para modelos hospedados na nuvem.

• Chamadas de função

  • Em breve!

• Contar tokens

  • Sempre gera um erro. A contagem varia 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 que use 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.

Enviar feedback sobre sua experiência com Firebase AI Logic