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?

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

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

  5. Se solicitado no fluxo de trabalho do console, siga as instruções na tela para registrar seu 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 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.

  1. No Xcode, com seu projeto do app aberto, navegue até Arquivo > Adicionar dependências do pacote.

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

  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) oferece 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 do 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 migrar o app (consulte as seções restantes neste guia), exclua a biblioteca antiga.

Swift

Remova a biblioteca antiga:

  1. No Xcode, com seu projeto do app aberto, navegue até o painel Dependências de pacotes.

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

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

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

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

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.

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 e FinishReason.
  • Motivo do bloqueio

    • O campo blockReason em PromptFeedback agora é opcional.
  • 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 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 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 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