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


Crie recursos e web apps 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 disponíveis (e vice-versa).

Nesta página, descrevemos como começar a usar o SDK do cliente e mostramos 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.

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 ou da conectividade com a Internet

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

Antes de começar

Observações:

Começar a usar o localhost

Estas etapas iniciais 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 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. Configure seu projeto para usar um provedor "Gemini API".

    Recomendamos começar usando o Gemini Developer API. A qualquer momento, você pode configurar o 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 de API Gemini no seu projeto.
    Não adicione essa chave de 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 e conectar seu app ao Firebase.

  6. Continue 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 generativos. 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:

    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.

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. 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 uma destas opções:

      • PREFER_ON_DEVICE: use o modelo no dispositivo se ele estiver disponível. Caso contrário, use 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, use o modelo no dispositivo.

      • ONLY_IN_CLOUD: use o modelo hospedado na nuvem se ele estiver disponível. Caso contrário, gerar 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

Nesta seção, mostramos como enviar vários tipos de entrada para gerar diferentes tipos de saída, incluindo:

Se 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 esta amostra, 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 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 (multimodais)

Antes de testar esta amostra, 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 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 Firebase AI Logic também é compatível com o 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 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.

O que mais você pode fazer?

Nesta seção, você vai aprender a definir um modo de inferência, substituir o modelo de substituição padrão hospedado na nuvem e usar a configuração do modelo para controlar respostas (como gerar saída estruturada).

Definir um modo de inferência

Os exemplos na configuração geral usam o modo PREFER_ON_DEVICE, mas esse é apenas um dos quatro modos de inferência disponíveis.

  • PREFER_ON_DEVICE: use o modelo no dispositivo se ele estiver disponível. Caso contrário, use o modelo hospedado na nuvem.

    const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_ON_DEVICE });

  • ONLY_ON_DEVICE: use o modelo no dispositivo se ele estiver disponível. Caso contrário, gere uma exceção.

    const model = getGenerativeModel(ai, { mode: InferenceMode.ONLY_ON_DEVICE });

  • PREFER_IN_CLOUD: use o modelo hospedado na nuvem se ele estiver disponível. Caso contrário, use o modelo no dispositivo.

    const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_IN_CLOUD });

  • ONLY_IN_CLOUD: use o modelo hospedado na nuvem se ele estiver disponível. Caso contrário, gerar uma exceção.

    const model = getGenerativeModel(ai, { mode: InferenceMode.ONLY_IN_CLOUD });

Determinar se a inferência no dispositivo ou na nuvem foi usada

Se você usa os modos de inferência PREFER_ON_DEVICE ou PREFER_IN_CLOUD, pode ser útil saber qual modo foi usado para determinadas solicitações. Essas informações são fornecidas pela propriedade inferenceSource de cada resposta (disponível a partir do SDK JavaScript v12.5.0).

Ao acessar essa propriedade, o valor retornado será ON_DEVICE ou IN_CLOUD.

// ...

console.log('You used: ' + result.response.inferenceSource);

console.log(result.response.text());

Substituir o modelo de fallback padrão

O modelo padrão hospedado na nuvem é gemini-2.5-flash-lite (a partir do SDK do JavaScript v12.8.0).

Esse modelo é o modelo alternativo hospedado na nuvem quando você usa o modo PREFER_ON_DEVICE. Ele também é o modelo padrão quando você usa o modo ONLY_IN_CLOUD ou PREFER_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.INFERENCE_MODE,
  inCloudParams: {
    model: "GEMINI_MODEL_NAME"
  }
});

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 Gemini hospedado na nuvem. Saiba mais sobre os parâmetros disponíveis.

const model = getGenerativeModel(ai, {
  mode: InferenceMode.INFERENCE_MODE,
  inCloudParams: {
    model: "GEMINI_MODEL_NAME"
    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.INFERENCE_MODE,
  onDeviceParams: {
    createOptions: {
      temperature: 0.8,
      topK: 8
    }
  }
});

Definir a configuração para saída estruturada (como JSON)

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.INFERENCE_MODE,
  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 a 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

  • Fornecer ao modelo ferramentas para ajudar na geração da resposta (como chamadas 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 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 da mesma forma que outras inferências usando o SDK do cliente Firebase AI Logic para Web.


Envie feedback sobre sua experiência com Firebase AI Logic