Migrar para os SDKs de lógica de IA do Firebase dos SDKs de cliente de IA do Google


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 móveis e da Web. Eles foram descontinuados em favor dos SDKs do 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 à base de código do app para dispositivos móveis ou 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

  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 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 chave de API Gemini nova e dedicada no projeto.
    Não adicione essa nova chave de API Gemini à base de código do app. Saiba mais.

  5. Se solicitado no fluxo de trabalho do console, siga as instruções na tela para registrar o app e conectá-lo ao Firebase.

  6. 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.

  1. No Xcode, com o projeto do app aberto, navegue até File > Add Package Dependencies.

  2. Quando solicitado, adicione o repositório do SDK do Firebase para as plataformas Apple:

    https://github.com/firebase/firebase-ios-sdk

  3. Selecione a versão mais recente do SDK.

  4. 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.

  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);

Dart

O plug-in Firebase AI Logic para Flutter (firebase_ai) fornece acesso às APIs para interagir com os modelos Gemini e Imagen.

  1. 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

  2. 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';

  3. Ainda no arquivo lib/main.dart, inicialize o Firebase usando o objeto DefaultFirebaseOptions exportado pelo arquivo de configuração:

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

  4. 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:

  1. No Xcode, com o projeto do app aberto, navegue até o painel Packages Dependencies.

  2. Selecione o pacote generative-ai-swift na lista de dependências de pacotes.

  3. 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 para 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 

// BEFORE
import 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 

// BEFORE
import 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 

// BEFORE
import 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 

// BEFORE
import { 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 

// BEFORE
import '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 para 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 de GenerativeModel.

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 seu 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 por structs 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çõ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.

    • A enumeração ModelContent.Part foi substituída por um protocolo chamado Part 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 para ModelContent foram simplificados para evitar erros ocasionais do compilador. As imagens que não são codificadas corretamente ainda vão gerar erros quando usadas em generateContent.

    • Os casos ModelContent.Part foram substituídos pelos seguintes tipos de struct em conformidade 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

    • O HarmCategory foi alterado para não ser mais aninhado no tipo SafetySetting. Se você estiver se referindo a ele como SafetySetting.HarmCategory, ele poderá ser substituído por HarmCategory.

  • Feedback de segurança

    • O tipo SafetyFeedback foi removido, já que não foi usado em nenhuma das respostas.

  • Metadados de citação

    • A propriedade citationSources foi renomeada como citations em CitationMetadata.

  • Total de caracteres faturáveis

    • A propriedade totalBillableCharacters em CountTokensResponse foi alterada 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 continuam configuráveis no inicializador.

Kotlin

  • Enumerações

    • As classes enum e sealed 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 como HarmBlockThreshold.

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

  • Métodos de blob

    • Renomeação de todos os métodos que incluíam Blob como parte do nome para usar InlineData.

  • Configurações de segurança

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

  • Classe de duração

    • Todos os usos da classe Duration do Kotlin foram removidos e substituídos por long. Essa mudança oferece uma melhor interoperabilidade com o Java.

  • Metadados de citação

    • Todos os campos declarados anteriormente em CitationMetadata foram agrupados 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 várias plataformas.

  • Contar tokens

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

  • Total de caracteres faturáveis

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

  • Instanciar um modelo

    • O parâmetro requestOptions foi movido para o final da lista de parâmetros para se alinhar a outras plataformas.

Java

  • Enumerações

    • As classes enum e sealed 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 como HarmBlockThreshold.

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

  • Métodos de blob

    • Renomeação de todos os métodos que incluíam Blob como parte do nome para usar InlineData.

  • Configurações de segurança

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

  • Classe de duração

    • Todos os usos da classe Duration do Kotlin foram removidos e substituídos por long. Essa mudança oferece uma melhor interoperabilidade com o Java.

  • Metadados de citação

    • Todos os campos declarados anteriormente em CitationMetadata foram agrupados 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 várias plataformas.

  • Contar tokens

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

  • Total de caracteres faturáveis

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

  • Instanciar um modelo

    • O parâmetro requestOptions foi movido para o final da lista de parâmetros para se alinhar a outras plataformas.

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 e FinishReason.

  • Motivo do bloqueio

    • O blockReason em PromptFeedback foi alterado para ser opcional.

  • 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 para AIError.

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 data static foi renomeada como inlineData para se alinhar a outras plataformas.

  • Opções de solicitação

    • RequestOptions foi removido porque timeout não era funcional. Ele será adicionado novamente em breve, mas será movido para o tipo GenerativeModel para corresponder a outras plataformas.

  • Parar sequências

    • O parâmetro stopSequences em GenerationConfig foi alterado para ser opcional e padronizado para null 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 involuntariamente foram removidos: defaultTimeout, CountTokensResponseFields, parseCountTokensResponse, parseEmbedContentResponse, parseGenerateContentResponse, parseContent, BatchEmbedContentsResponse, ContentEmbedding, EmbedContentRequest e EmbedContentResponse.

  • Contar tokens

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

  • Instanciar um modelo

    • O parâmetro systemInstruction foi movido para o final da lista de parâmetros para se alinhar a outras plataformas.

  • Funcionalidade de embedding

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

Unity

O suporte para 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