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.
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
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.
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.
Ative o modelo multimodal no dispositivo definindo a seguinte flag:
chrome://flags/#prompt-api-for-gemini-nano-multimodal-input
: defina como Ativado.
Verifique a API localmente:
Reinicie o Chrome.
Abra Ferramentas para desenvolvedores > Console.
Execute o comando a seguir:
await LanguageModel.availability();
Verifique se a saída é
available
,downloading
oudownloadable
. .Se a saída for
downloadable
, inicie o download do modelo executandoawait 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
Faça login no console do Firebase e selecione seu projeto do Firebase.
No console Firebase, acesse a página Firebase AI Logic.
Clique em Começar para iniciar um fluxo de trabalho guiado que ajuda a configurar as APIs necessárias e os recursos do projeto.
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.
Se solicitado no fluxo de trabalho do console, siga as instruções na tela para registrar seu app e conectá-lo ao Firebase.
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.
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
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 } 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
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 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 oresponseMimeType
adequado (neste exemplo,application/json
) e oresponseSchema
que você quer que o modelo use.Para
onDeviceParams
: especifique oresponseConstraint
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.
- Pode fazer fallback para o modelo hospedado na nuvem. No entanto, o modo
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.
- Pode fazer fallback para o modelo hospedado na nuvem. No entanto, o modo
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.
- Pode fazer fallback para o modelo hospedado na nuvem. No entanto, o modo
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.
- Pode fazer fallback para o modelo hospedado na nuvem. No entanto, o modo
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