Acessar diretamente as instruções de migração
Por que migrar para usar os SDKs Firebase AI Logic?
Você pode ter tentado um conjunto alternativo de SDKs de cliente para dispositivos móveis ou da Web que deu acesso ao Gemini Developer API.
Esses SDKs de cliente não foram integrados ao robusto ecossistema do Firebase, que oferece serviços essenciais para apps da Web e para dispositivos móveis. Eles foram descontinuados 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 para dispositivos móveis e da Web, a segurança é fundamental e requer considerações especiais, porque o código, incluindo chamadas para o Gemini API, é executado em um ambiente desprotegido. É possível usar Firebase App Check para proteger as APIs contra abuso por clientes não autorizados.
Quando você usa Firebase App Check com Firebase AI Logic, não é necessário adicionar a chave de API 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 fica no servidor, sem exposição a agentes maliciosos.
Ecossistema criado para apps da Web e para dispositivos móveis
O Firebase é a plataforma do Google para desenvolvimento de apps para dispositivos móveis e Web. O uso de Firebase AI Logic significa que seus apps estão em um ecossistema focado nas necessidades de apps e desenvolvedores full-stack. Exemplo:
Defina dinamicamente configurações de tempo de execução ou troque valores no app (como um nome e 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 solicitações multimodais (se você usar 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.
Gerenciar 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 existente e conecte seu app ao Firebase.
Etapa 2: adicione os SDKs do Firebase AI Logic ao app.
Etapa 3: atualize as importações e a inicialização no app.
Etapa 4: atualize o código de acordo com os recursos que você usa.
Etapa 1: configurar um projeto do Firebase e conectar o 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 a 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 nova chave de API Gemini dedicada no projeto.
Não adicione essa nova chave de API Gemini à base de código do app. Saiba mais.Se solicitado no fluxo de trabalho do console, siga as instruções na tela para registrar o 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 app
Com o projeto do Firebase configurado e o app conectado ao Firebase (consulte a etapa anterior), agora você pode 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 os modelos Gemini e Imagen. A biblioteca é incluída
como parte do SDK do Firebase para plataformas Apple (firebase-ios-sdk
).
Se você já estiver usando o Firebase, verifique se o pacote do Firebase é v11.13.0 ou mais recente.
No Xcode, com o projeto do app aberto, navegue até File > Add Package Dependencies.
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 Firebase AI Logic para Android (firebase-ai
) oferece acesso às APIs para interagir com os 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 o uso do
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 Firebase AI Logic para Android (firebase-ai
) oferece acesso às APIs para interagir com os 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 o uso do
Firebase Android BoM
para controlar o controle de versões da biblioteca.
Para Java, é necessário adicionar duas bibliotecas.
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 os modelos Gemini e Imagen. A biblioteca é incluída como parte do SDK do Firebase para JavaScript da 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
) fornece
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 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 concluir a migração do app (consulte as outras seções deste guia), exclua a biblioteca antiga.
Swift
Remova a biblioteca antiga:
No Xcode, com o projeto do app aberto, navegue até o painel Packages Dependencies.
Selecione o pacote
generative-ai-swift
na lista de dependências de pacotes.Clique no botão
-
na parte de baixo da lista e clique 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 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 cria uma instância de 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.0-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.0-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.0-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.0-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.0-flash');
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.
Dependendo do recurso que você está usando, talvez não seja possível
criar uma instância GenerativeModel
.
- Para acessar um modelo Imagen,
crie uma instância
ImagenModel
.
Etapa 4: atualizar o código de acordo com os recursos usados
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 oferecem suporte à execução de código. Se você usar esse recurso, acomode-o no seu app.
Analise as listas a seguir para conferir as mudanças que talvez você precise fazer no código para acomodar a migração para os SDKs do cliente Firebase AI Logic.
Obrigatório para todos os idiomas e plataformas
Chamada de função
Se você implementou esse recurso, será necessário fazer atualizações na maneira como define seu esquema. Recomendamos que você revise o guia atualizado de chamadas de função para saber como escrever as declarações de função.Como gerar saída estruturada (como JSON) usando
responseSchema
Se você implementou esse recurso, será necessário fazer atualizações na maneira como define o esquema. Recomendamos que você revise o novo guia de saída estruturada para saber como escrever esquemas JSON.Tempo limite
- O tempo limite padrão para solicitações foi alterado para 180 segundos.
Obrigatório com base na plataforma ou no idioma
Swift
Enumerações
A maioria dos tipos
enum
foi substituída porstruct
s com variáveis estáticas. Essa mudança permite mais flexibilidade para a evolução da API de uma forma 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
.A enumeração
ModelContent.Part
foi substituída por um protocolo chamadoPart
para permitir que novos tipos sejam adicionados de forma compatível com versões anteriores. Essa mudança é descrita em mais detalhes na seção Partes do conteúdo.
Partes do conteúdo
O protocolo
ThrowingPartsRepresentable
foi removido, e os inicializadores deModelContent
foram simplificados para evitar erros ocasionais do compilador. As imagens que não são codificadas corretamente ainda vão gerar erros quando usadas emgenerateContent
.Os casos
ModelContent.Part
foram substituídos pelos seguintes tipos destruct
em conformidade com o protocoloPart
:.text
aTextPart
- De
.data
paraInlineDataPart
- De
.fileData
paraFileDataPart
- De
.functionCall
paraFunctionCallPart
.functionResponse
aFunctionResponsePart
Categoria de dano
- O
HarmCategory
foi alterado para não ser mais aninhado no tipoSafetySetting
. Se você estiver se referindo a ele comoSafetySetting.HarmCategory
, ele poderá ser substituído porHarmCategory
.
- O
Feedback de segurança
- O tipo
SafetyFeedback
foi removido, já que não foi 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
- A propriedade
totalBillableCharacters
emCountTokensResponse
foi alterada para ser opcional e refletir situações em que nenhum caractere é enviado.
- 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 continuam configuráveis no inicializador.
- As propriedades públicas de
Kotlin
Enumerações
As classes
enum
esealed
foram substituídas por classes normais. Essa mudança permite mais flexibilidade para evoluir a API de uma forma 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
- Renomeação de todos os métodos que incluíam
Blob
como parte do nome para usarInlineData
.
- Renomeação de 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
- Todos os usos da classe
Duration
do Kotlin foram removidos e substituídos porlong
. Essa mudança oferece uma melhor interoperabilidade com o Java.
- Todos os usos da classe
Metadados de citação
- Todos os campos declarados anteriormente em
CitationMetadata
foram agrupados 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 várias plataformas.
- Todos os campos declarados anteriormente em
Contar tokens
- O campo
totalBillableCharacters
foi mudado para ser anulável.
- O campo
Total de caracteres faturáveis
- A propriedade
totalBillableCharacters
emCountTokensResponse
foi alterada para ser opcional e refletir situações em que nenhum caractere é enviado.
- A propriedade
Instanciar um modelo
- O parâmetro
requestOptions
foi movido para o final da lista de parâmetros para se alinhar a outras plataformas.
- O parâmetro
Java
Enumerações
As classes
enum
esealed
foram substituídas por classes normais. Essa mudança permite mais flexibilidade para evoluir a API de uma forma 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
- Renomeação de todos os métodos que incluíam
Blob
como parte do nome para usarInlineData
.
- Renomeação de 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
- Todos os usos da classe
Duration
do Kotlin foram removidos e substituídos porlong
. Essa mudança oferece uma melhor interoperabilidade com o Java.
- Todos os usos da classe
Metadados de citação
- Todos os campos declarados anteriormente em
CitationMetadata
foram agrupados 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 várias plataformas.
- Todos os campos declarados anteriormente em
Contar tokens
- O campo
totalBillableCharacters
foi mudado para ser anulável.
- O campo
Total de caracteres faturáveis
- A propriedade
totalBillableCharacters
emCountTokensResponse
foi alterada para ser opcional e refletir situações em que nenhum caractere é enviado.
- A propriedade
Instanciar um modelo
- O parâmetro
requestOptions
foi movido para o final da lista de parâmetros para se alinhar a outras plataformas.
- 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 criados. A lista a seguir mostra algumas mudanças que talvez você precise considerar ao migrar para os SDKs do cliente 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
blockReason
emPromptFeedback
foi alterado para ser opcional.
- O
Embasamento da pesquisa
- Todos os usos desse recurso foram removidos, já que ele ainda não tem suporte nos SDKs Firebase AI Logic.
Erros
- Todos os usos de
GoogleGenerativeAIError
foram removidos, e, opcionalmente, movidos paraAIError
.
- 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çãodata
static
foi renomeada comoinlineData
para se alinhar a outras plataformas.
Opções de solicitação
RequestOptions
foi removido porquetimeout
não era funcional. Ele será adicionado novamente em breve, mas será movido para o tipoGenerativeModel
para corresponder a outras plataformas.
Parar sequências
- O parâmetro
stopSequences
emGenerationConfig
foi alterado para ser opcional e padronizado paranull
em vez de uma matriz vazia.
- 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
involuntariamente foram removidos:
defaultTimeout
,CountTokensResponseFields
,parseCountTokensResponse
,parseEmbedContentResponse
,parseGenerateContentResponse
,parseContent
,BatchEmbedContentsResponse
,ContentEmbedding
,EmbedContentRequest
eEmbedContentResponse
.
- Os seguintes tipos, métodos e propriedades que foram expostos
involuntariamente foram removidos:
Contar tokens
- Foram removidos campos extras da função
countTokens
que não são mais necessários. Apenascontents
é necessário.
- Foram removidos campos extras da função
Instanciar um modelo
- O parâmetro
systemInstruction
foi movido para o final da lista de parâmetros para se alinhar a outras plataformas.
- O parâmetro
Funcionalidade de embedding
- 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 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