Migrar para os SDKs de lógica da AI do Firebase a partir da versão de Pré-lançamento da Vertex AI nos SDKs do Firebase

Este guia ajuda você a migrar das versões de prévia (ou beta) dos SDKs "Vertex AI in Firebase" para os SDKs do cliente Firebase AI Logic.
Esses SDKs de cliente estão disponíveis em Swift para plataformas Apple, Kotlin e Java para Android, JavaScript para Web, Dart para Flutter e Unity.

Se você estiver usando uma versão GA de um SDK "Vertex AI in Firebase", acesse o guia para migrar da versão GA do SDK.

O Firebase AI Logic e os SDKs de cliente dele eram chamados de "Vertex AI in Firebase". Para refletir melhor nossos serviços e recursos expandidos (por exemplo, agora oferecemos suporte ao Gemini Developer API!), renomeamos e reempacotamos nossos serviços em Firebase AI Logic.

Para acessar com segurança os modelos de IA generativa do Google diretamente dos seus apps para dispositivos móveis ou da Web, agora você pode escolher um provedor "Gemini API" — Vertex AI Gemini API, que já está disponível há muito tempo, ou Gemini Developer API. Isso significa que agora você tem a opção de usar o Gemini Developer API, que oferece um nível sem custos financeiros com limites de taxa e cotas razoáveis.

Visão geral das etapas para migrar para os SDKs Firebase AI Logic

• Etapa 1: escolha o melhor provedor da "API Gemini" para seu app e casos de uso.

• Etapa 2: ative as APIs necessárias.

• Etapa 3: atualize a biblioteca usada no app.

• Etapa 4: atualize a inicialização no app.

• Etapa 5: atualize seu código de acordo com os recursos que você usa.

Etapa 1: escolha o melhor provedor da "API Gemini" para seu app

Com essa migração, você pode escolher um provedor de "Gemini API":

• Os SDKs antigos "Vertex AI in Firebase" só podiam usar o Vertex AI Gemini API.

• Com os novos SDKs do Firebase AI Logic, é possível escolher qual provedor de "Gemini API" você quer chamar diretamente do seu app para dispositivos móveis ou da Web – o Gemini Developer API ou o Vertex AI Gemini API.

Confira as diferenças entre o uso dos dois provedores de Gemini API, principalmente em termos de recursos compatíveis, preços e limites de taxa. Por exemplo, o Gemini Developer API não oferece suporte ao fornecimento de arquivos usando URLs Cloud Storage, mas pode ser uma boa opção se você quiser aproveitar o nível sem custo financeiro e a cota razoável.

Importante: se você quiser usar o "nível sem custos financeiros" do Gemini Developer API, faça downgrade do projeto do Firebase que você usa atualmente com os SDKs do cliente para o plano de preços Spark sem custos financeiros (ou seja, desvincule a conta do Cloud Billing). Antes de fazer downgrade, verifique se você não depende de outros serviços ou cotas que exigem o plano de preços Blaze.

Se o projeto do Firebase continuar no plano de preços Blaze, você vai usar um dos níveis pagos" do Gemini Developer API.

Etapa 2: ativar as APIs necessárias

Verifique se todas as APIs necessárias estão ativadas no seu projeto do Firebase para usar o provedor "Gemini API" escolhido.

É possível ter os dois provedores de API ativados no seu projeto ao mesmo tempo.

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 "API Gemini" 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)
     . O fluxo de trabalho do 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 do Blaze de pagamento conforme o uso)
     . O fluxo de trabalho do console vai ativar as APIs necessárias no seu projeto.

5. Continue neste guia de migração para atualizar a biblioteca e a inicialização no app.

Etapa 3: atualizar a biblioteca usada no app

Atualize a base de código do app para usar a biblioteca Firebase AI Logic.

Swift

1. No Xcode, com o projeto do app aberto, atualize o pacote do Firebase para v11.13.0 ou mais recente usando uma das seguintes opções:

   • Opção 1: atualize todos os pacotes. Navegue até Arquivo > Pacotes > Atualizar para as versões mais recentes dos pacotes.

   • Opção 2: atualize o Firebase individualmente. Navegue até o pacote do Firebase na seção Dependências de pacote. Clique com o botão direito do mouse no pacote do Firebase e selecione Atualizar pacote.

2. Verifique se o pacote do Firebase mostra a versão 11.13.0 ou mais recente. Caso contrário, verifique se os requisitos de pacote especificados permitem a atualização para a v11.13.0 ou mais recente.

3. Selecione o destino do app no Project Editor e navegue até a seção Frameworks, Libraries, and Embedded Content.

4. Adicione a nova biblioteca: selecione o botão + e adicione FirebaseAI do pacote do Firebase.

5. Depois de concluir a migração do app (consulte as seções restantes neste guia), remova a biblioteca antiga:
   Selecione FirebaseVertexAI-Preview e pressione o botão —.

Kotlin

1. No arquivo Gradle do módulo (nível do app) (geralmente <project>/<app-module>/build.gradle.kts ou <project>/<app-module>/build.gradle), substitua as dependências antigas (conforme aplicável) pelo seguinte.

   Talvez seja mais fácil migrar a base de código do app (consulte as seções restantes neste guia) antes de excluir a dependência antiga.

   // BEFORE
   dependencies {
     implementation("com.google.firebase:firebase-vertexai:16.0.0-betaXX")
   }
   
   
   // AFTER
   dependencies {
     // Import the BoM for the Firebase platform
     implementation(platform("com.google.firebase:firebase-bom:33.16.0"))
   
     // Add the dependency for the Firebase AI Logic library
     // When using the BoM, you don't specify versions in Firebase library dependencies
     implementation("com.google.firebase:firebase-ai")
   }

2. Sincronize seu projeto do Android com os arquivos Gradle.

Se você optar por não usar o Firebase Android BoM, adicione a dependência da biblioteca firebase-ai e aceite a versão mais recente sugerida pelo Android Studio.

Java

1. No arquivo Gradle do módulo (nível do app) (geralmente <project>/<app-module>/build.gradle.kts ou <project>/<app-module>/build.gradle), substitua as dependências antigas (conforme aplicável) pelo seguinte.

   Talvez seja mais fácil migrar a base de código do app (consulte as seções restantes neste guia) antes de excluir a dependência antiga.

   // BEFORE
   dependencies {
     implementation("com.google.firebase:firebase-vertexai:16.0.0-betaXX")
   }
   
   
   // AFTER
   dependencies {
     // Import the BoM for the Firebase platform
     implementation(platform("com.google.firebase:firebase-bom:33.16.0"))
   
     // Add the dependency for the Firebase AI Logic library
     // When using the BoM, you don't specify versions in Firebase library dependencies
     implementation("com.google.firebase:firebase-ai")
   }

2. Sincronize seu projeto do Android com os arquivos Gradle.

Se você optar por não usar o Firebase Android BoM, adicione a dependência da biblioteca firebase-ai e aceite a versão mais recente sugerida pelo Android Studio.

Web

1. Instale a versão mais recente do SDK do Firebase para JavaScript na Web usando npm:

   npm i firebase@latest

   OU

   yarn add firebase@latest

2. Atualize as instruções de importação para usar firebase/ai em vez de importar a biblioteca.

   Talvez seja mais fácil migrar a base de código do app (consulte as seções restantes neste guia) antes de excluir as importações antigas.

   // BEFORE
   import { initializeApp } from "firebase/app";
   import { getVertexAI, getGenerativeModel } from "firebase/vertexai-preview";
   
   
   // AFTER
   import { initializeApp } from "firebase/app";
   import { getAI, getGenerativeModel } from "firebase/ai";

Dart

1. Atualize para usar o pacote firebase_ai no arquivo pubspec.yaml executando o seguinte comando no diretório do projeto do Flutter:

   flutter pub add firebase_ai

2. Recrie o projeto do Flutter:

   flutter run

3. Depois de concluir a migração do app (consulte as seções restantes neste guia), exclua o pacote antigo:

   flutter pub remove firebase_vertexai

Unity

O suporte ao Unity não estava disponível em "Vertex AI in Firebase".

Saiba como começar a usar o SDK do Firebase AI Logic para Unity.

Etapa 4: atualizar a inicialização no app

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

Atualize a forma como você inicializa o serviço para o provedor de API escolhido e crie uma instância GenerativeModel.

Swift

import FirebaseAI

// Initialize the Gemini Developer API backend service
let ai = FirebaseAI.firebaseAI(backend: .googleAI())

// Create a `GenerativeModel` instance with a model that supports your use case
let model = ai.generativeModel(modelName: "gemini-2.5-flash")

Kotlin

// Initialize the Gemini Developer API backend service
// Create a `GenerativeModel` instance with a model that supports your use case
val model = Firebase.ai(backend = GenerativeBackend.googleAI())
                        .generativeModel("gemini-2.5-flash")

Java

// Initialize the Gemini Developer API backend service
// Create a `GenerativeModel` instance with a model that supports your use case
GenerativeModel ai = FirebaseAI.getInstance(GenerativeBackend.googleAI())
        .generativeModel("gemini-2.5-flash");

// Use the GenerativeModelFutures Java compatibility layer which offers
// support for ListenableFuture and Publisher APIs
GenerativeModelFutures model = GenerativeModelFutures.from(ai);

Web

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 with a model that supports your use case
const model = getGenerativeModel(ai, { model: "gemini-2.5-flash" });

Dart

import 'package:firebase_ai/firebase_ai.dart';
import 'package:firebase_core/firebase_core.dart';
import 'firebase_options.dart';

// Initialize FirebaseApp
await Firebase.initializeApp(
  options: DefaultFirebaseOptions.currentPlatform,
);

// Initialize the Gemini Developer API backend service
// Create a `GenerativeModel` instance with a model that supports your use case
final model =
      FirebaseAI.googleAI().generativeModel(model: 'gemini-2.5-flash');

Unity

O suporte ao Unity não estava disponível em "Vertex AI in Firebase".

Saiba como começar a usar o SDK do Firebase AI Logic para Unity.

Dependendo da capacidade que você está usando, talvez nem sempre seja necessário criar uma instância GenerativeModel.

• Para acessar um modelo Imagen, crie uma instância ImagenModel.

Etapa 5: atualizar seu código dependendo dos recursos que você usa

Esta etapa descreve as mudanças que podem ser necessárias dependendo dos recursos que você usa.

• Se você usa URLs Cloud Storage e e mudou para usar o Gemini Developer API nesta migração, atualize seus pedidos multimodais para incluir arquivos como dados inline (ou use URLs do YouTube para vídeos).

• Várias mudanças foram introduzidas nas versões GA dos SDKs "Vertex AI in Firebase". Essas mesmas mudanças são necessárias para usar os SDKs Firebase AI Logic. Revise as listas a seguir para conferir se há mudanças que você precisa fazer no seu código para acomodar a adoção do SDK Firebase AI Logic.

Obrigatório para todas as linguagens e plataformas

• Chamada de função
  Se você implementou esse recurso antes da GA, será necessário atualizar a forma como você define seu esquema. Recomendamos revisar o guia atualizado de chamada de função para saber como escrever declarações de função.

• Gerar saída estruturada (como JSON) usando responseSchema
  Se você implementou esse recurso antes da GA, será necessário atualizar a forma como define seu esquema. Recomendamos que você consulte o novo guia de saída estruturada para saber como escrever esquemas JSON.

• Tempo limite

  • Mudamos o tempo limite padrão das solicitações para 180 segundos.

Obrigatório com base na plataforma ou no idioma

Swift

• Enumerações

  • Substituição da maioria dos tipos enum por structs com variáveis estáticas. Essa mudança permite mais flexibilidade para desenvolver a API de uma maneira compatível com versões anteriores. Ao usar instruções switch, agora é necessário incluir um caso default: para cobrir valores desconhecidos ou não processados, incluindo novos valores que serão adicionados ao SDK no futuro.

  • A enumeração BlockThreshold foi renomeada como HarmBlockThreshold. Esse tipo agora é um struct.

  • Os casos unknown e unspecified foram removidos das seguintes enumerações (agora structs): HarmCategory, HarmBlockThreshold, HarmProbability, BlockReason e FinishReason.

  • Substituímos a enumeração ModelContent.Part por um protocolo chamado Part para permitir a adição de novos tipos de maneira compatível com versões anteriores. Essa mudança é descrita com mais detalhes na seção Partes de conteúdo.

• Partes do conteúdo

  • O protocolo ThrowingPartsRepresentable foi removido, e os inicializadores de ModelContent foram simplificados para evitar erros ocasionais do compilador. Imagens que não são codificadas corretamente ainda vão gerar erros quando usadas em generateContent.

  • Substituímos os casos de ModelContent.Part pelos seguintes tipos de struct, de acordo com o protocolo Part:

    • .text a TextPart
    • De .data para InlineDataPart
    • De .fileData para FileDataPart
    • De .functionCall para FunctionCallPart
    • .functionResponse a FunctionResponsePart

• Categoria de dano

  • Mudou o HarmCategory para não ficar mais aninhado no tipo SafetySetting. Se você estiver se referindo a ele como SafetySetting.HarmCategory, isso pode ser substituído por HarmCategory.

• Feedback sobre segurança

  • O tipo SafetyFeedback foi removido porque não era usado em nenhuma das respostas.

• Metadados de citação

  • A propriedade citationSources foi renomeada como citations em CitationMetadata.

• Total de caracteres faturáveis

  • Mudamos a propriedade totalBillableCharacters em CountTokensResponse para ser opcional e refletir situações em que nenhum caractere é enviado.

• Resposta do candidato

  • CandidateResponse foi renomeado como Candidate para corresponder a outras plataformas.

• Configuração de geração

  • As propriedades públicas de GenerationConfig foram alteradas para internal. Todos eles permanecem configuráveis no inicializador.

Kotlin

• Enumerações

  • Substituímos as classes enum e sealed por classes regulares. Essa mudança permite mais flexibilidade para desenvolver a API de maneira compatível com versões anteriores.

  • A enumeração BlockThreshold foi renomeada como HarmBlockThreshold.

  • Valores removidos das seguintes enumerações: HarmBlockThreshold, HarmProbability, HarmSeverity, BlockReason e FinishReason.

• Métodos de blob

  • Todos os métodos que incluíam Blob como parte do nome foram renomeados para usar InlineData.

• Configurações de segurança

  • O campo method foi mudado para ser anulável.

• Classe de duração

  • Removemos todos os usos da classe Duration do Kotlin e a substituímos por long. Essa mudança oferece uma interoperabilidade melhor com o Java.

• Metadados de citação

  • Encapsulou todos os campos declarados anteriormente em CitationMetadata em uma nova classe chamada Citation. As citações podem ser encontradas na lista chamada citations em CitationMetadata. Essa mudança permite um melhor alinhamento de tipos em todas as plataformas.

• Contar tokens

  • O campo totalBillableCharacters foi mudado para ser anulável.

• Total de caracteres faturáveis

  • Mudamos a propriedade totalBillableCharacters em CountTokensResponse para ser opcional e refletir situações em que nenhum caractere é enviado.

• Instanciar um modelo

  • Movemos o parâmetro requestOptions para o final da lista de parâmetros para alinhar com outras plataformas.

• Live API

  • Removemos o valor UNSPECIFIED da classe de enumeração ResponseModality. Em vez disso, use null.

  • LiveGenerationConfig.setResponseModalities foi renomeado como LiveGenerationConfig.setResponseModality.

  • A classe LiveContentResponse.Status foi removida, e os campos de status foram aninhados como propriedades de LiveContentResponse.

  • A classe LiveContentResponse foi removida e substituída por subclasses de LiveServerMessage que correspondem às respostas do modelo.

  • LiveModelFutures.connect foi alterado para retornar ListenableFuture<LiveSessionFutures> em vez de ListenableFuture<LiveSession>.

Java

• Enumerações

  • Substituímos as classes enum e sealed por classes regulares. Essa mudança permite mais flexibilidade para desenvolver a API de maneira compatível com versões anteriores.

  • A enumeração BlockThreshold foi renomeada como HarmBlockThreshold.

  • Valores removidos das seguintes enumerações: HarmBlockThreshold, HarmProbability, HarmSeverity, BlockReason e FinishReason.

• Métodos de blob

  • Todos os métodos que incluíam Blob como parte do nome foram renomeados para usar InlineData.

• Configurações de segurança

  • O campo method foi mudado para ser anulável.

• Classe de duração

  • Removemos todos os usos da classe Duration do Kotlin e a substituímos por long. Essa mudança oferece uma interoperabilidade melhor com o Java.

• Metadados de citação

  • Encapsulou todos os campos declarados anteriormente em CitationMetadata em uma nova classe chamada Citation. As citações podem ser encontradas na lista chamada citations em CitationMetadata. Essa mudança permite um melhor alinhamento de tipos em todas as plataformas.

• Contar tokens

  • O campo totalBillableCharacters foi mudado para ser anulável.

• Total de caracteres faturáveis

  • Mudamos a propriedade totalBillableCharacters em CountTokensResponse para ser opcional e refletir situações em que nenhum caractere é enviado.

• Instanciar um modelo

  • Movemos o parâmetro requestOptions para o final da lista de parâmetros para alinhar com outras plataformas.

• Live API

  • Removemos o valor UNSPECIFIED da classe de enumeração ResponseModality. Em vez disso, use null.

  • LiveGenerationConfig.setResponseModalities foi renomeado como LiveGenerationConfig.setResponseModality.

  • A classe LiveContentResponse.Status foi removida, e os campos de status foram aninhados como propriedades de LiveContentResponse.

  • A classe LiveContentResponse foi removida e substituída por subclasses de LiveServerMessage que correspondem às respostas do modelo.

  • LiveModelFutures.connect foi alterado para retornar ListenableFuture<LiveSessionFutures> em vez de ListenableFuture<LiveSession>.

• Mudança em vários métodos do builder Java para retornar corretamente a instância da classe, em vez de void.

Web

• Enumerações

  • Valores removidos das seguintes enumerações: HarmCategory, BlockThreshold, HarmProbability, HarmSeverity, BlockReason e FinishReason.

• Motivo do bloqueio

  • O campo blockReason em PromptFeedback agora é opcional.

As mudanças são necessárias apenas se você estiver começando a usar o Gemini Developer API (em vez do Vertex AI Gemini API):

• Configurações de segurança

  • Removemos os usos do SafetySetting.method incompatível.

• Dados inline

  • Removemos os usos do InlineDataPart.videoMetadata incompatível.

Dart

• Enumerações

  • Valores removidos das seguintes enumerações: HarmCategory, HarmProbability, BlockReason e FinishReason.

• Parte de dados

  • DataPart foi renomeado como InlineDataPart, e a função static data foi renomeada como inlineData para se alinhar a outras plataformas.

• Opções de solicitação

  • Removemos RequestOptions porque timeout não estava funcionando. Ele será adicionado novamente em breve, mas será movido para o tipo GenerativeModel para corresponder a outras plataformas.

• Sequências de parada

  • Mudamos o parâmetro stopSequences em GenerationConfig para ser opcional e usar null como padrão em vez de uma matriz vazia.

• Citações

  • A propriedade citationSources foi renomeada como citations em CitationMetadata. O tipo CitationSource foi renomeado como Citation para corresponder a outras plataformas.

• Tipos, métodos e propriedades públicos desnecessários

  • Os seguintes tipos, métodos e propriedades, que foram expostos sem intenção, foram removidos: defaultTimeout, CountTokensResponseFields, parseCountTokensResponse, parseEmbedContentResponse, parseGenerateContentResponse, parseContent, BatchEmbedContentsResponse, ContentEmbedding, EmbedContentRequest e EmbedContentResponse.

• Contar tokens

  • Removemos campos extras da função countTokens que não são mais necessários. Apenas contents é necessário.

• Instanciar um modelo

  • Movemos o parâmetro systemInstruction para o final da lista de parâmetros para alinhar com outras plataformas.

• Funcionalidade de incorporação

  • A funcionalidade de incorporação sem suporte (embedContent e batchEmbedContents) foi removida do modelo.

Unity

O suporte ao Unity não estava disponível em "Vertex AI in Firebase".

Saiba como começar a usar o SDK do Firebase AI Logic para Unity.

Possíveis erros relacionados à migração

Ao migrar para usar a versão GA do Firebase AI Logic, você pode encontrar erros se não tiver concluído todas as mudanças necessárias, conforme descrito neste guia de migração.

Erro 403: Requests to this API firebasevertexai.googleapis.com ... are blocked.

Se você receber um erro 403 que diz Requests to this API firebasevertexai.googleapis.com ... are blocked., geralmente significa que a chave de API do Firebase no seu arquivo ou objeto de configuração do Firebase não tem uma API necessária na lista de permissões para o produto que você está tentando usar.

Verifique se a chave de API do Firebase usada pelo app tem todas as APIs necessárias incluídas na lista de permissões "Restrições de API". Para Firebase AI Logic, sua chave de API do Firebase precisa ter pelo menos a API Firebase AI Logic na lista de permissões. Essa API deveria ter sido adicionada automaticamente à lista de permissões da sua chave de API quando você ativou as APIs necessárias no console Firebase.

É possível conferir todas as chaves de API no painel APIs e serviços > Credenciais no console Google Cloud.

Observação: as APIs relacionadas ao Firebase usam chaves de API apenas para identificar o projeto ou app do Firebase, não para autorização para chamar a API (como algumas outras APIs permitem). A autorização de APIs relacionadas ao Firebase é processada separadamente da chave de API, seja por permissões do IAM Google Cloud, Firebase Security Rules ou Firebase App Check. Saiba mais sobre as chaves de API do Firebase.

Enviar feedback sobre sua experiência com Firebase AI Logic