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


Crie apps e recursos com tecnologia de IA usando a inferência híbrida com Firebase AI Logic. A inferência híbrida permite executar a inferência usando modelos no dispositivo quando disponível e, caso contrário, voltar aos modelos hospedados na nuvem.

Com essa versão, 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 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

  • Usar a funcionalidade híbrida oferece:

    • Alcance 100% do seu público-alvo, independentemente da disponibilidade do modelo no dispositivo

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

  • Geração de conteúdo com interação única, streaming e sem streaming
  • Gerar texto com base em uma entrada somente de texto
  • Geração de texto com base em entradas de texto e imagem, especificamente tipos de entrada de imagem JPEG e PNG
  • Gerar saída estruturada, incluindo JSON e tipos enumerados

Primeiros passos

Este guia mostra como começar a usar o SDK Firebase AI Logic para Web para 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 de Gemini API escolhido (Gemini Developer API ou Vertex AI Gemini API).

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

  1. Faça o download do build mais recente do Chrome Dev.

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

  2. Para ativar a API Prompt na sua instância do Chrome, defina 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. Como alternativa, 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: definido 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, você poderá iniciar o download do modelo executando await LanguageModel.create();. Caso contrário, a primeira solicitação para inferência no dispositivo vai iniciar um download de 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.

  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 sem custos do Spark)
      O console vai ativar as APIs necessárias e criar uma chave de API Gemini no seu projeto. Você pode configurar o faturamento mais tarde se quiser fazer upgrade do seu plano de preços.

    • Vertex AI Gemini API: necessário faturamento (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 o app e conectá-lo ao Firebase.

  6. Siga para a próxima etapa deste guia para adicionar o SDK ao app.

Etapa 3: adicionar o SDK

A biblioteca do Firebase oferece acesso às APIs para interagir com modelos gerativos. A biblioteca está incluída como parte do SDK do Firebase para JavaScript na 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

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 uma solicitação para um modelo Gemini, inicialize o serviço para o 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 ele estiver disponível, ou para usar o modelo hospedado na nuvem.

  • only_on_device: configura o SDK para usar o modelo no dispositivo ou gera 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:

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 uma entrada somente de texto

Antes de testar este exemplo, conclua a seção Primeiros passos deste guia.

Use 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 (multimodal)

Antes de testar este exemplo, conclua a seção Primeiros passos deste guia.

É 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 arquivo em si.

Os tipos de imagem de entrada compatíveis 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();

O que mais você pode fazer?

Além dos exemplos acima, você também pode usar modos de inferência alternativos, modificar o modelo alternativo 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 para usar um modelo no dispositivo, se disponível, ou retornar a 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

Quando você usa o modo prefer_on_device, o SDK volta a usar um modelo hospedado na nuvem se um modelo no dispositivo estiver indisponível. O modelo 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.

É possível usar 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.0-flash"
  }
});

Encontre os nomes de todos os modelos do Gemini com suporte.

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 o modelo gera uma resposta. Os modelos hospedados na nuvem e no dispositivo oferecem diferentes opções de configuração.

A configuração é mantida durante 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 Gemini hospedado na nuvem. Saiba mais sobre os parâmetros disponíveis.

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

Definir a configuração para 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 tipos enumerados) tem suporte para inferência usando modelos hospedados na nuvem e no dispositivo.

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

  • Para inCloudParams: especifique o responseMimeType apropriado (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 geral de saída JSON 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.0-flash"
    generationConfig: {
      responseMimeType: "application/json",
      responseSchema: jsonSchema
    },
  }
  onDeviceParams: {
    promptOptions: {
      responseConstraint: jsonSchema
    }
  }
});
Saída de tipo enumerado

Como acima, mas adaptando a documentação sobre a saída de tipo enumerado 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 têm suporte para inferência no dispositivo, mas geralmente estão disponíveis para inferência baseada na nuvem.

  • Geração de texto com base em tipos de entrada de arquivo de imagem diferentes de JPEG e PNG

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

  • Gerar imagens usando modelos Gemini ou Imagen

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

  • Chat multiturno

    • Pode usar 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 de cliente Firebase AI Logic para Web 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 usando os modelos hospedados na nuvem pode ser monitorada assim como outras inferências usando o SDK do cliente Firebase AI Logic para Web.


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