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

Comece a desenvolver usando localhost, conforme descrito nesta seção. Você também pode saber mais sobre como usar APIs em localhost na documentação do Chrome. Depois de implementar o recurso, você pode permitir que os usuários finais testem o recurso.

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 Enabled:

    • chrome://flags/#prompt-api-for-gemini-nano-multimodal-input
  3. Reinicie o Chrome.

  4. (Opcional) Faça o download do 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 baixado o modelo antes da primeira solicitação de inferência no dispositivo, a solicitação vai iniciar automaticamente o download do modelo em segundo plano.

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.

  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. Gemini Developer API é recomendado para usuários iniciantes. Você pode adicionar faturamento ou configurar o Vertex AI Gemini API depois, 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 necessário (requer o plano de preços Blaze de pagamento por uso)
      . O console vai ajudar 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:

    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

Clique no seu provedor de Gemini API para conferir o conteúdo e o código específicos do provedor nesta página.

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, 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 to use on-device model when possible
const model = getGenerativeModel(ai, { mode: InferenceMode.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:

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

Antes de testar este exemplo, confira se você concluiu a seção Começar deste guia.

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)

Antes de testar este exemplo, confira se você concluiu a seção Começar deste guia.

É 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 permitir que os usuários finais testem seu recurso, 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.

Permitir que os usuários finais testem seu recurso

Para permitir que os usuários finais testem seu recurso, inscreva-se nos testes de origem do Chrome. Esses testes têm duração e uso limitados.

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

  2. Forneça o token em todas as páginas da Web em que você quer ativar o recurso de teste. Use uma das seguintes opções:

    • Forneça o token como uma metatag na tag <head>: <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.

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: InferenceMode.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: InferenceMode.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: InferenceMode.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: InferenceMode.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: InferenceMode.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: InferenceMode.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.
  • Gerar 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.
  • Usar "ferramentas", incluindo chamada de função e embasamento com a Pesquisa Google

    • 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