Acessar diretamente as instruções de migração
Por que migrar para usar os SDKs Firebase AI Logic?
Talvez você tenha testado um conjunto alternativo de SDKs de cliente para dispositivos móveis ou Web que deu acesso ao Gemini Developer API.
Esses SDKs do cliente não foram integrados ao robusto ecossistema do Firebase, que oferece serviços essenciais para apps móveis e da Web. Agora, eles estão obsoletos em favor dos SDKs de cliente Firebase AI Logic, que podem dar acesso ao Gemini Developer API.
Recursos de segurança para apps da Web e para dispositivos móveis
Para apps móveis e da Web, a segurança é fundamental e exige considerações especiais porque seu código, incluindo chamadas para o Gemini API, é executado em um ambiente desprotegido. É possível usar o Firebase App Check para proteger APIs contra abuso por clientes não autorizados.
Ao usar Firebase App Check com Firebase AI Logic, você nunca adiciona a chave de API do Gemini para o Gemini Developer API diretamente na base de código do app para dispositivos móveis ou da Web. Em vez disso, a chave de API Gemini permanece no servidor, sem ser exposta a usuários mal-intencionados.
Ecossistema criado para apps da Web e para dispositivos móveis
O Firebase é a plataforma do Google para desenvolver apps para dispositivos móveis e da Web. Usar o Firebase AI Logic significa que seus apps estão em um ecossistema focado nas necessidades de apps e desenvolvedores full-stack. Exemplo:
Defina dinamicamente as configurações de tempo de execução ou troque valores no app (como um nome e uma versão do modelo) sem lançar uma nova versão usando Firebase Remote Config.
Use Cloud Storage for Firebase para incluir arquivos grandes nas suas solicitações multimodais (se você usar o Vertex AI Gemini API). Os SDKs de cliente Cloud Storage ajudam a processar uploads e downloads de arquivos (mesmo em condições de rede ruins) e oferecem mais segurança para os dados dos usuários finais. Saiba mais no nosso guia de soluções sobre como usar Cloud Storage for Firebase.
Gerencie dados estruturados usando SDKs de banco de dados criados para apps da Web e para dispositivos móveis (como o Cloud Firestore).
Migrar para os SDKs do Firebase AI Logic
Visão geral das etapas para migrar para os SDKs Firebase AI Logic:
Etapa 1: configure um projeto do Firebase novo ou atual e conecte seu app a ele.
Etapa 2: adicione os SDKs do Firebase AI Logic ao seu app.
Etapa 3: atualize as importações e a inicialização no app.
Etapa 4: atualize seu código de acordo com os recursos que você usa.
Etapa 1: configurar um projeto do Firebase e conectar seu app
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 Gemini Developer API. Você pode configurar e usar o outro provedor de API mais tarde, se quiser.
O console vai ativar as APIs necessárias e criar uma chave de API Gemini dedicada no projeto.
Não adicione essa nova chave de API Gemini à base de código do seu app. Saiba mais.Se solicitado no fluxo de trabalho do console, siga as instruções na tela para registrar seu app e conectá-lo ao Firebase.
Continue neste guia de migração para atualizar a biblioteca e a inicialização no app.
Etapa 2: adicionar o SDK do Firebase AI Logic ao seu app
Com o projeto do Firebase configurado e o app conectado ao Firebase (consulte a etapa anterior), agora é possível adicionar o SDK Firebase AI Logic ao app.
Swift
Use o Swift Package Manager para instalar e gerenciar as dependências do Firebase.
A biblioteca Firebase AI Logic oferece acesso às APIs para interagir
com modelos Gemini e Imagen. A biblioteca está incluída
como parte do SDK do Firebase para plataformas Apple (firebase-ios-sdk
).
Se você já usa o Firebase, verifique se o pacote dele é v11.13.0 ou mais recente.
No Xcode, com seu projeto do app aberto, navegue até Arquivo > Adicionar dependências do pacote.
Quando solicitado, adicione o repositório do SDK do Firebase para as plataformas Apple:
https://github.com/firebase/firebase-ios-sdk
Selecione a versão mais recente do SDK.
Selecione a biblioteca
FirebaseAI
.
Quando terminar, o Xcode vai começar a resolver e fazer o download das dependências em segundo plano automaticamente.
Kotlin
O SDK do Firebase AI Logic Android (firebase-ai
) oferece
acesso às APIs para interagir com
modelos Gemini e Imagen.
No arquivo Gradle do módulo (nível do app)
(como <project>/<app-module>/build.gradle.kts
),
adicione a dependência da biblioteca Firebase AI Logic para Android.
Recomendamos usar o
Firebase Android BoM
para controlar o controle de versões da biblioteca.
dependencies { // ... other androidx dependencies // Import the BoM for the Firebase platform implementation(platform("com.google.firebase:firebase-bom:33.15.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") }
Com o Firebase Android BoM, seu app sempre vai usar versões compatíveis das bibliotecas do Firebase para Android.
Java
O SDK do Firebase AI Logic Android (firebase-ai
) oferece
acesso às APIs para interagir com
modelos Gemini e Imagen.
No arquivo Gradle do módulo (nível do app)
(como <project>/<app-module>/build.gradle.kts
),
adicione a dependência da biblioteca Firebase AI Logic para Android.
Recomendamos usar o
Firebase Android BoM
para controlar o controle de versões da biblioteca.
Para Java, é necessário adicionar duas bibliotecas extras.
dependencies { // ... other androidx dependencies // Import the BoM for the Firebase platform implementation(platform("com.google.firebase:firebase-bom:33.15.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") // Required for one-shot operations (to use `ListenableFuture` from Guava Android) implementation("com.google.guava:guava:31.0.1-android") // Required for streaming operations (to use `Publisher` from Reactive Streams) implementation("org.reactivestreams:reactive-streams:1.0.4") }
Com o Firebase Android BoM, seu app sempre vai usar versões compatíveis das bibliotecas do Firebase para Android.
Web
A biblioteca Firebase AI Logic oferece acesso às APIs para interagir com modelos Gemini e Imagen. 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:
npm install firebase
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);
Dart
O plug-in Firebase AI Logic para Flutter (firebase_ai
) oferece
acesso às APIs para interagir com os modelos
Gemini e Imagen.
No diretório do projeto do Flutter, execute o seguinte comando para instalar o plug-in principal e o plug-in do Firebase AI Logic:
flutter pub add firebase_core && flutter pub add firebase_ai
No arquivo
lib/main.dart
, importe o plug-in principal do Firebase, o plug-in Firebase AI Logic e o arquivo de configuração gerado antes:import 'package:firebase_core/firebase_core.dart'; import 'package:firebase_ai/firebase_ai.dart'; import 'firebase_options.dart';
Ainda no arquivo
lib/main.dart
, inicialize o Firebase usando o objetoDefaultFirebaseOptions
exportado pelo arquivo de configuração:await Firebase.initializeApp( options: DefaultFirebaseOptions.currentPlatform, );
Recrie o aplicativo do Flutter:
flutter run
Unity
O suporte ao Unity não estava disponível nos SDKs de cliente Google AI.
Saiba como começar a usar o SDK do Firebase AI Logic para Unity.
Remover o SDK antigo do app
Depois de migrar o app (consulte as seções restantes neste guia), exclua a biblioteca antiga.
Swift
Remova a biblioteca antiga:
No Xcode, com seu projeto do app aberto, navegue até o painel Dependências de pacotes.
Selecione o pacote
generative-ai-swift
na lista de dependências.Clique no botão
-
na parte de baixo da lista e em Remover para confirmar.
Kotlin
dependencies {
implementation("com.google.ai.client.generativeai:generativeai:VERSION")
}
Java
dependencies {
implementation("com.google.ai.client.generativeai:generativeai:VERSION")
}
Web
// BEFORE
import { initializeApp } from "firebase/app";
import { GoogleGenerativeAI } from "@google/generative-ai";
Dart
Exclua o pacote antigo:
flutter pub remove google_generative_ai
Unity
O suporte ao Unity não estava disponível nos SDKs de cliente do Google AI.
Saiba como começar a usar o SDK do Firebase AI Logic para Unity.
Etapa 3: atualizar as importações e a inicialização no app
Atualize as importações e a forma como você inicializa o serviço de back-end Gemini Developer API e crie uma instância GenerativeModel
.
Swift
// BEFOREimport GoogleGenerativeAI let model = GenerativeModel(name: "MODEL_NAME", apiKey: APIKey.default)// AFTER 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
// BEFOREimport com.google.ai.client.generativeai.Chat import com.google.ai.client.generativeai.type.Content import com.google.ai.client.generativeai.java.GenerativeModuleFutures...val generativeModel = GenerativeModel(modelName = "MODEL_NAME", // Access your API key as a Build Configuration variable apiKey = BuildConfig.apiKey )// AFTER import com.google.firebase.Firebase import com.google.firebase.ai.ai import com.google.firebase.ai.type.GenerativeBackend ... // 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
// BEFOREimport com.google.ai.client.generativeai.Chat; import com.google.ai.client.generativeai.type.Content; import com.google.ai.client.generativeai.java.GenerativeModuleFutures;...GenerativeModel gm = new GenerativeModel("MODEL_NAME", // Access your API key as a Build Configuration variable BuildConfig.apiKey ); GenerativeModelFutures model = GenerativeModelFutures.from(gm);// AFTER import com.google.firebase.ai.FirebaseAI; import com.google.firebase.ai.GenerativeModel; import com.google.firebase.ai.java.GenerativeModelFutures; import com.google.firebase.ai.type.GenerativeBackend; ... // 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
// BEFOREimport { GoogleGenerativeAI } from "@google/generative-ai"; // Fetch your API_KEY and access your API const API_KEY = "..."; const genAI = new GoogleGenerativeAI(API_KEY);...const model = genAI.getGenerativeModel({ model: "MODEL_NAME"});// AFTER 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
// BEFOREimport 'package:google_generative_ai/google_generative_ai.dart'; final apiKey = Platform.environment['API_KEY']; if (apiKey == null) { print('No \$API_KEY environment variable'); exit(1); } final model = GenerativeModel(model: 'MODEL_NAME', apiKey: apiKey);// AFTER 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 nos SDKs de cliente do Google AI.
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 4: atualizar o 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.
Os SDKs de cliente Firebase AI Logic não são compatíveis com a execução de código. Se você usar esse recurso, não se esqueça de incluir isso no seu app.
Revise as listas a seguir para conferir se é necessário fazer alguma mudança no seu código para migrar para os SDKs de cliente Firebase AI Logic.
Obrigatório para todas as linguagens e plataformas
Chamada de função
Se você implementou esse recurso, será necessário atualizar a forma como 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, 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
porstruct
s 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çõesswitch
, agora é necessário incluir um casodefault:
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 comoHarmBlockThreshold
. Esse tipo agora é umstruct
.Os casos
unknown
eunspecified
foram removidos das seguintes enumerações (agorastruct
s):HarmCategory
,HarmBlockThreshold
,HarmProbability
,BlockReason
eFinishReason
.Substituímos a enumeração
ModelContent.Part
por um protocolo chamadoPart
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 deModelContent
foram simplificados para evitar erros ocasionais do compilador. Imagens que não são codificadas corretamente ainda vão gerar erros quando usadas emgenerateContent
.Substituímos os casos de
ModelContent.Part
pelos seguintes tipos destruct
, de acordo com o protocoloPart
:.text
aTextPart
- De
.data
paraInlineDataPart
- De
.fileData
paraFileDataPart
- De
.functionCall
paraFunctionCallPart
.functionResponse
aFunctionResponsePart
Categoria de dano
- Mudou o
HarmCategory
para não ficar mais aninhado no tipoSafetySetting
. Se você estiver se referindo a ele comoSafetySetting.HarmCategory
, isso pode ser substituído porHarmCategory
.
- Mudou o
Feedback sobre segurança
- O tipo
SafetyFeedback
foi removido porque não era usado em nenhuma das respostas.
- O tipo
Metadados de citação
- A propriedade
citationSources
foi renomeada comocitations
emCitationMetadata
.
- A propriedade
Total de caracteres faturáveis
- Mudamos a propriedade
totalBillableCharacters
emCountTokensResponse
para ser opcional e refletir situações em que nenhum caractere é enviado.
- Mudamos a propriedade
Resposta do candidato
CandidateResponse
foi renomeado comoCandidate
para corresponder a outras plataformas.
Configuração de geração
- As propriedades públicas de
GenerationConfig
foram alteradas parainternal
. Todos eles permanecem configuráveis no inicializador.
- As propriedades públicas de
Kotlin
Enumerações
Substituímos as classes
enum
esealed
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 comoHarmBlockThreshold
.Valores removidos das seguintes enumerações:
HarmBlockThreshold
,HarmProbability
,HarmSeverity
,BlockReason
eFinishReason
.
Métodos de blob
- Todos os métodos que incluíam
Blob
como parte do nome foram renomeados para usarInlineData
.
- Todos os métodos que incluíam
Configurações de segurança
- O campo
method
foi mudado para ser anulável.
- O campo
Classe de duração
- Removemos todos os usos da classe
Duration
do Kotlin e a substituímos porlong
. Essa mudança oferece uma interoperabilidade melhor com o Java.
- Removemos todos os usos da classe
Metadados de citação
- Encapsulou todos os campos declarados anteriormente em
CitationMetadata
em uma nova classe chamadaCitation
. As citações podem ser encontradas na lista chamadacitations
emCitationMetadata
. Essa mudança permite um melhor alinhamento de tipos em todas as plataformas.
- Encapsulou todos os campos declarados anteriormente em
Contar tokens
- O campo
totalBillableCharacters
foi mudado para ser anulável.
- O campo
Total de caracteres faturáveis
- Mudamos a propriedade
totalBillableCharacters
emCountTokensResponse
para ser opcional e refletir situações em que nenhum caractere é enviado.
- Mudamos a propriedade
Instanciar um modelo
- Movemos o parâmetro
requestOptions
para o final da lista de parâmetros para alinhar com outras plataformas.
- Movemos o parâmetro
Java
Enumerações
Substituímos as classes
enum
esealed
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 comoHarmBlockThreshold
.Valores removidos das seguintes enumerações:
HarmBlockThreshold
,HarmProbability
,HarmSeverity
,BlockReason
eFinishReason
.
Métodos de blob
- Todos os métodos que incluíam
Blob
como parte do nome foram renomeados para usarInlineData
.
- Todos os métodos que incluíam
Configurações de segurança
- O campo
method
foi mudado para ser anulável.
- O campo
Classe de duração
- Removemos todos os usos da classe
Duration
do Kotlin e a substituímos porlong
. Essa mudança oferece uma interoperabilidade melhor com o Java.
- Removemos todos os usos da classe
Metadados de citação
- Encapsulou todos os campos declarados anteriormente em
CitationMetadata
em uma nova classe chamadaCitation
. As citações podem ser encontradas na lista chamadacitations
emCitationMetadata
. Essa mudança permite um melhor alinhamento de tipos em todas as plataformas.
- Encapsulou todos os campos declarados anteriormente em
Contar tokens
- O campo
totalBillableCharacters
foi mudado para ser anulável.
- O campo
Total de caracteres faturáveis
- Mudamos a propriedade
totalBillableCharacters
emCountTokensResponse
para ser opcional e refletir situações em que nenhum caractere é enviado.
- Mudamos a propriedade
Instanciar um modelo
- Movemos o parâmetro
requestOptions
para o final da lista de parâmetros para alinhar com outras plataformas.
- Movemos o parâmetro
Web
O SDK do cliente Google AI para JavaScript passou por muitas mudanças desde que os SDKs do cliente Firebase AI Logic foram ramificados dele. A lista a seguir mostra algumas mudanças que você talvez precise considerar ao migrar para os SDKs de cliente do Firebase AI Logic.
Enumerações
- Valores removidos das seguintes enumerações:
HarmCategory
,BlockThreshold
,HarmProbability
,HarmSeverity
,BlockReason
eFinishReason
.
- Valores removidos das seguintes enumerações:
Motivo do bloqueio
- O campo
blockReason
emPromptFeedback
agora é opcional.
- O campo
Embasamento da pesquisa
- Removemos todos os usos desse recurso, já que ele ainda não é compatível com os SDKs do Firebase AI Logic.
Erros
- Remova todos os usos de
GoogleGenerativeAIError
e, opcionalmente, mude paraAIError
.
- Remova todos os usos de
Dart
Enumerações
- Valores removidos das seguintes enumerações:
HarmCategory
,HarmProbability
,BlockReason
eFinishReason
.
- Valores removidos das seguintes enumerações:
Parte de dados
DataPart
foi renomeado comoInlineDataPart
, e a funçãostatic
data
foi renomeada comoinlineData
para se alinhar a outras plataformas.
Opções de solicitação
- Removemos
RequestOptions
porquetimeout
não estava funcionando. Ele será adicionado novamente em breve, mas será movido para o tipoGenerativeModel
para corresponder a outras plataformas.
- Removemos
Sequências de parada
- Mudamos o parâmetro
stopSequences
emGenerationConfig
para ser opcional e usarnull
como padrão em vez de uma matriz vazia.
- Mudamos o parâmetro
Citações
- A propriedade
citationSources
foi renomeada comocitations
emCitationMetadata
. O tipoCitationSource
foi renomeado comoCitation
para corresponder a outras plataformas.
- A propriedade
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
eEmbedContentResponse
.
- Os seguintes tipos, métodos e propriedades, que foram expostos sem intenção, foram removidos:
Contar tokens
- Removemos campos extras da função
countTokens
que não são mais necessários. Apenascontents
é necessário.
- Removemos campos extras da função
Instanciar um modelo
- Movemos o parâmetro
systemInstruction
para o final da lista de parâmetros para alinhar com outras plataformas.
- Movemos o parâmetro
Funcionalidade de incorporação
- A funcionalidade de incorporação sem suporte (
embedContent
ebatchEmbedContents
) foi removida do modelo.
- A funcionalidade de incorporação sem suporte (
Unity
O suporte ao Unity não estava disponível nos SDKs de cliente do Google AI.
Saiba como começar a usar o SDK do Firebase AI Logic para Unity.
Enviar feedback sobre sua experiência com Firebase AI Logic