Migra a los SDKs de Firebase AI Logic desde la versión preliminar de Vertex AI en los SDKs de Firebase


Firebase AI Logic y sus SDKs de cliente antes se llamaban "Vertex AI in Firebase". Para reflejar mejor nuestros servicios y funciones expandidos (por ejemplo, ahora admitimos Gemini Developer API), cambiamos el nombre de nuestros servicios y los volvimos a empaquetar en Firebase AI Logic.

Para acceder de forma segura a los modelos de IA generativa de Google directamente desde tu app web o para dispositivos móviles, ahora puedes elegir un proveedor de "Gemini API", el Vertex AI Gemini API disponible desde hace mucho tiempo o ahora el Gemini Developer API. Esto significa que ahora tienes la opción de usar Gemini Developer API, que proporciona un nivel sin costo con límites y cuotas de tarifas razonables.

Descripción general de los pasos para migrar a los SDKs de Firebase AI Logic

  • Paso 1: Elige el mejor proveedor de "API de Gemini" para tu app y tus casos de uso.

  • Paso 2: Habilita las APIs necesarias.

  • Paso 3: Actualiza la biblioteca que se usa en tu app.

  • Paso 4: Actualiza la inicialización en tu app.

  • Paso 5: Actualiza tu código según las funciones que uses.

Paso 1: Elige el mejor proveedor de "API de Gemini" para tu app

Con esta migración, tienes la opción de elegir el proveedor "Gemini API":

  • Los SDKs "Vertex AI in Firebase" anteriores solo podían usar Vertex AI Gemini API.

  • Los nuevos SDKs de Firebase AI Logic te permiten elegir a qué proveedor de "Gemini API" quieres llamar directamente desde tu app web o para dispositivos móviles, ya sea Gemini Developer API o Vertex AI Gemini API.

Revisa las diferencias entre usar los dos proveedores de Gemini API, sobre todo en términos de las funciones compatibles, los precios y los límites de tarifas. Por ejemplo, Gemini Developer API no admite la entrega de archivos con URLs Cloud Storage, pero podría ser una buena opción si deseas aprovechar su nivel sin costo y su cuota razonable.

Paso 2: Habilita las APIs necesarias

Asegúrate de que todas las APIs necesarias estén habilitadas en tu proyecto de Firebase para usar el proveedor de "Gemini API" que elegiste.

Ten en cuenta que puedes tener habilitados ambos proveedores de API en tu proyecto al mismo tiempo.

  1. Accede a la consola de Firebase y, luego, selecciona tu proyecto de Firebase.

  2. En la consola de Firebase, ve a la página Firebase AI Logic.

  3. Haz clic en Comenzar para iniciar un flujo de trabajo guiado que te ayudará a configurar las APIs requeridas y los recursos de tu proyecto.

  4. Selecciona el proveedor de "API de Gemini" que deseas usar con los SDKs de Firebase AI Logic. Si lo deseas, puedes configurar y usar el otro proveedor de API más adelante.

    • Gemini Developer API: Facturación opcional (disponible en el plan de precios sin costo Spark)
      El flujo de trabajo de la consola habilitará las APIs requeridas y creará una clave de API de Gemini en tu proyecto.
      No agregues esta clave de API de Gemini a la base de código de tu app. Más información.

    • Vertex AI Gemini API: Facturación obligatoria (requiere el plan de precios Blaze de pago por uso)
      El flujo de trabajo de la consola habilitará las APIs requeridas en tu proyecto.

  5. Continúa con esta guía de migración para actualizar la biblioteca y la inicialización en tu app.

Paso 3: Actualiza la biblioteca que se usa en tu app

Actualiza la base de código de tu app para usar la biblioteca Firebase AI Logic.

Swift

  1. En Xcode, con el proyecto de tu app abierto, actualiza el paquete de Firebase a la versión 11.13.0 o una posterior con una de las siguientes opciones:

    • Opción 1: Actualiza todos los paquetes: Navega a File > Packages > Update to Latest Package Versions.

    • Opción 2: Actualiza Firebase de forma individual: Navega al paquete de Firebase en la sección llamada Dependencias del paquete. Haz clic con el botón derecho en el paquete de Firebase y, luego, selecciona Update Package.

  2. Asegúrate de que el paquete de Firebase ahora muestre la versión 11.13.0 o una posterior. Si no es así, verifica que los Requisitos del paquete especificados permitan la actualización a la versión 11.13.0 o una posterior.

  3. Selecciona el destino de tu app en el editor de proyectos y, luego, navega a la sección Frameworks, bibliotecas y contenido incorporado.

  4. Agrega la biblioteca nueva: Selecciona el botón + y, luego, agrega FirebaseAI desde el paquete de Firebase.

  5. Una vez que hayas terminado de migrar tu app (consulta las secciones restantes de esta guía), asegúrate de quitar la biblioteca anterior:
    Selecciona FirebaseVertexAI-Preview y, luego, presiona el botón —.

Kotlin

  1. En el archivo Gradle (generalmente <project>/<app-module>/build.gradle.kts o <project>/<app-module>/build.gradle) del módulo (nivel de app), reemplaza las dependencias anteriores (según corresponda) por lo siguiente.

    Ten en cuenta que podría ser más fácil migrar la base de código de tu app (consulta las secciones restantes de esta guía) antes de borrar la dependencia anterior.

    // 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.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")
}

  2. Sincroniza tu proyecto de Android con archivos Gradle.

Ten en cuenta que, si decides no usar Firebase Android BoM, solo debes agregar la dependencia de la biblioteca firebase-ai y aceptar la versión más reciente que sugiere Android Studio.

Java

  1. En el archivo Gradle (generalmente <project>/<app-module>/build.gradle.kts o <project>/<app-module>/build.gradle) del módulo (nivel de app), reemplaza las dependencias anteriores (según corresponda) por lo siguiente.

    Ten en cuenta que podría ser más fácil migrar la base de código de tu app (consulta las secciones restantes de esta guía) antes de borrar la dependencia anterior.

    // 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.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")
}

  2. Sincroniza tu proyecto de Android con archivos Gradle.

Ten en cuenta que, si decides no usar Firebase Android BoM, solo debes agregar la dependencia de la biblioteca firebase-ai y aceptar la versión más reciente que sugiere Android Studio.

Web

  1. Obtén la versión más reciente del SDK de Firebase JS para la Web con npm:

    npm i firebase@latest

    O

    yarn add firebase@latest

  2. Donde hayas importado la biblioteca, actualiza las instrucciones de importación para usar firebase/ai en su lugar.

    Ten en cuenta que podría ser más fácil migrar la base de código de tu app (consulta las secciones restantes de esta guía) antes de borrar las importaciones anteriores.

    // 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. Para actualizar y usar el paquete firebase_ai en tu archivo pubspec.yaml, ejecuta el siguiente comando desde el directorio de tu proyecto de Flutter:

    flutter pub add firebase_ai

  2. Vuelve a compilar tu proyecto de Flutter:

    flutter run

  3. Después de terminar de migrar tu app (consulta las secciones restantes de esta guía), asegúrate de borrar el paquete anterior:

    flutter pub remove firebase_vertexai

Unity

La compatibilidad con Unity no estaba disponible en “Vertex AI in Firebase”.

Obtén información para comenzar a usar el SDK de Firebase AI Logic para Unity.

Paso 4: Actualiza la inicialización en tu app

Haz clic en tu proveedor de Gemini API para ver el contenido y el código específicos del proveedor en esta página.

Actualiza la forma en que inicializas el servicio para el proveedor de API que elegiste y crea una instancia de 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

La compatibilidad con Unity no estaba disponible en "Vertex AI in Firebase".

Obtén información para comenzar a usar el SDK de Firebase AI Logic para Unity.

Ten en cuenta que , según la capability que uses, es posible que no siempre se cree una instancia de GenerativeModel.

Paso 5: Actualiza tu código según las funciones que uses

En este paso, se describen los cambios que pueden ser necesarios según las funciones que uses.

  • Si usas URLs Cloud Storage y cambiaste a Gemini Developer API en esta migración, debes actualizar tus solicitudes multimodales para incluir archivos como datos intercalados (o usar URLs de YouTube para los videos).

  • Se introdujeron varios cambios en las versiones de GA de los SDK de "Vertex AI in Firebase". Estos mismos cambios son necesarios para usar los SDK de Firebase AI Logic. Revisa las siguientes listas para ver si hay cambios que debas realizar en tu código para poder usar el SDK de Firebase AI Logic.

Obligatorio para todos los idiomas y plataformas

  • Llamadas a funciones
    Si implementaste esta función antes de la versión GA, deberás actualizar la manera en que defines tu esquema. Te recomendamos que revises la guía actualizada de llamadas a función para aprender a escribir las declaraciones de tus funciones.

  • Cómo generar un resultado estructurado (como JSON) con responseSchema
    Si implementaste esta función antes de la DG, deberás actualizar la forma en que defines tu esquema. Te recomendamos que revises la nueva guía de salida estructurada para aprender a escribir esquemas JSON.

  • Tiempo de espera

    • Se cambió el tiempo de espera predeterminado de las solicitudes a 180 segundos.

Obligatorio según la plataforma o el idioma

Swift

  • Enumeraciones

    • Se reemplazaron la mayoría de los tipos enum por struct con variables estáticas. Este cambio permite más flexibilidad para evolucionar la API de forma retrocompatible. Cuando uses sentencias switch, ahora debes incluir un caso default: para cubrir valores desconocidos o no controlados, incluidos los valores nuevos que se agreguen al SDK en el futuro.

    • Se cambió el nombre de la enumeración BlockThreshold a HarmBlockThreshold. Este tipo ahora es struct.

    • Se quitaron los casos unknown y unspecified de las siguientes enumeraciones (ahora struct): HarmCategory, HarmBlockThreshold, HarmProbability, BlockReason y FinishReason.

    • Se reemplazó la enumeración ModelContent.Part por un protocolo llamado Part para permitir que se agreguen tipos nuevos de forma retrocompatible. Este cambio se describe con más detalle en la sección Partes del contenido.

  • Partes del contenido

    • Se quitó el protocolo ThrowingPartsRepresentable y se simplificaron los inicializadores de ModelContent para evitar errores ocasionales del compilador. Las imágenes que no se codifican correctamente seguirán arrojando errores cuando se usen en generateContent.

    • Se reemplazaron los casos ModelContent.Part por los siguientes tipos struct que cumplen con el protocolo Part:

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

  • Categoría de daño

    • Se cambió HarmCategory para que ya no esté anidado en el tipo SafetySetting. Si te refieres a ella como SafetySetting.HarmCategory, se puede reemplazar por HarmCategory.

  • Comentarios sobre seguridad

    • Se quitó el tipo SafetyFeedback, ya que no se usó en ninguna de las respuestas.

  • Metadatos de citas

    • Se cambió el nombre de la propiedad citationSources a citations en CitationMetadata.

  • Total de caracteres facturables

    • Se cambió la propiedad totalBillableCharacters en CountTokensResponse para que sea opcional y refleje situaciones en las que no se envían caracteres.

  • Respuesta del candidato

    • Se cambió el nombre de CandidateResponse por Candidate para que coincida con otras plataformas.

  • Configuración de generación

    • Se cambiaron las propiedades públicas de GenerationConfig a internal. Todos se pueden configurar en el inicializador.

Kotlin

  • Enumeraciones

    • Se reemplazaron las clases enum y sealed por clases normales. Este cambio permite más flexibilidad para evolucionar la API de forma retrocompatible.

    • Se cambió el nombre de la enumeración BlockThreshold a HarmBlockThreshold.

    • Se quitaron los valores de las siguientes enumeraciones: HarmBlockThreshold, HarmProbability, HarmSeverity, BlockReason y FinishReason.

  • Métodos de BLOB

    • Se cambió el nombre de todos los métodos que incluían Blob como parte de su nombre para usar InlineData en su lugar.

  • Configuración de seguridad

    • Se cambió el campo method para que sea nulo.

  • Clase de duración

    • Se quitaron todos los usos de la clase Duration de Kotlin y se reemplazó por long. Este cambio proporciona una mejor interoperabilidad con Java.

  • Metadatos de citas

    • Se unió todos los campos declarados anteriormente en CitationMetadata en una clase nueva llamada Citation. Las citas se pueden encontrar en la lista llamada citations en CitationMetadata. Este cambio permite una mejor alineación de los tipos en todas las plataformas.

  • Cómo contar tokens

    • Se cambió el campo totalBillableCharacters para que sea nulo.

  • Total de caracteres facturables

    • Se cambió la propiedad totalBillableCharacters en CountTokensResponse para que sea opcional y refleje situaciones en las que no se envían caracteres.

  • Cómo crear una instancia de un modelo

    • Se movió el parámetro requestOptions al final de la lista de parámetros para alinearse con otras plataformas.

  • Live API

    • Se quitó el valor UNSPECIFIED para la clase enum ResponseModality. En su lugar, usa null.

    • Se cambió el nombre de LiveGenerationConfig.setResponseModalities a LiveGenerationConfig.setResponseModality.

    • Se quitó la clase LiveContentResponse.Status y, en su lugar, se anidan los campos de estado como propiedades de LiveContentResponse.

    • Se quitó la clase LiveContentResponse y, en su lugar, se proporcionaron subclases de LiveServerMessage que coinciden con las respuestas del modelo.

    • Se cambió LiveModelFutures.connect para mostrar ListenableFuture<LiveSessionFutures> en lugar de ListenableFuture<LiveSession>.

Java

  • Enumeraciones

    • Se reemplazaron las clases enum y sealed por clases normales. Este cambio permite más flexibilidad para evolucionar la API de forma retrocompatible.

    • Se cambió el nombre de la enumeración BlockThreshold a HarmBlockThreshold.

    • Se quitaron los valores de las siguientes enumeraciones: HarmBlockThreshold, HarmProbability, HarmSeverity, BlockReason y FinishReason.

  • Métodos de BLOB

    • Se cambió el nombre de todos los métodos que incluían Blob como parte de su nombre para usar InlineData en su lugar.

  • Configuración de seguridad

    • Se cambió el campo method para que sea nulo.

  • Clase de duración

    • Se quitaron todos los usos de la clase Duration de Kotlin y se reemplazó por long. Este cambio proporciona una mejor interoperabilidad con Java.

  • Metadatos de citas

    • Se unió todos los campos declarados anteriormente en CitationMetadata en una clase nueva llamada Citation. Las citas se pueden encontrar en la lista llamada citations en CitationMetadata. Este cambio permite una mejor alineación de los tipos en todas las plataformas.

  • Cómo contar tokens

    • Se cambió el campo totalBillableCharacters para que sea nulo.

  • Total de caracteres facturables

    • Se cambió la propiedad totalBillableCharacters en CountTokensResponse para que sea opcional y refleje situaciones en las que no se envían caracteres.

  • Cómo crear una instancia de un modelo

    • Se movió el parámetro requestOptions al final de la lista de parámetros para alinearse con otras plataformas.

  • Live API

    • Se quitó el valor UNSPECIFIED para la clase enum ResponseModality. En su lugar, usa null.

    • Se cambió el nombre de LiveGenerationConfig.setResponseModalities a LiveGenerationConfig.setResponseModality.

    • Se quitó la clase LiveContentResponse.Status y, en su lugar, se anidan los campos de estado como propiedades de LiveContentResponse.

    • Se quitó la clase LiveContentResponse y, en su lugar, se proporcionaron subclases de LiveServerMessage que coinciden con las respuestas del modelo.

    • Se cambió LiveModelFutures.connect para mostrar ListenableFuture<LiveSessionFutures> en lugar de ListenableFuture<LiveSession>.

  • Se cambiaron varios métodos de compilador de Java para que ahora muestren correctamente la instancia de su clase, en lugar de void.

Web

  • Enumeraciones

    • Se quitaron los valores de las siguientes enumeraciones: HarmCategory, BlockThreshold, HarmProbability, HarmSeverity, BlockReason y FinishReason.

  • Motivo del bloqueo

    • Se cambió blockReason en PromptFeedback para que sea opcional.

Cambios obligatorios solo si comienzas a usar Gemini Developer API (en lugar de Vertex AI Gemini API):

  • Configuración de seguridad

    • Se quitaron los usos de SafetySetting.method no admitidos.

  • Datos intercalados

    • Se quitaron los usos de InlineDataPart.videoMetadata no admitidos.

Dart

  • Enumeraciones

    • Se quitaron los valores de las siguientes enumeraciones: HarmCategory, HarmProbability, BlockReason y FinishReason.

  • Parte de datos

    • Se cambió el nombre de DataPart por InlineDataPart y el de la función data de static por inlineData para alinearse con otras plataformas.

  • Opciones de solicitud

    • Se quitó RequestOptions porque timeout no era funcional. Se volverá a agregar en un futuro cercano, pero se moverá al tipo GenerativeModel para que coincida con otras plataformas.

  • Secuencias de detención

    • Se cambió el parámetro stopSequences en GenerationConfig para que sea opcional y tenga el valor predeterminado null en lugar de un array vacío.

  • Citas

    • Se cambió el nombre de la propiedad citationSources a citations en CitationMetadata. Se cambió el nombre del tipo CitationSource a Citation para que coincida con otras plataformas.

  • Tipos, métodos y propiedades públicos innecesarios

    • Se quitaron los siguientes tipos, métodos y propiedades que se expusieron de forma no intencional: defaultTimeout, CountTokensResponseFields, parseCountTokensResponse, parseEmbedContentResponse, parseGenerateContentResponse, parseContent, BatchEmbedContentsResponse, ContentEmbedding, EmbedContentRequest y EmbedContentResponse.

  • Cómo contar tokens

    • Se quitaron los campos adicionales de la función countTokens que ya no son necesarios. Solo se necesita contents.

  • Cómo crear una instancia de un modelo

    • Se movió el parámetro systemInstruction al final de la lista de parámetros para alinearse con otras plataformas.

  • Funcionalidad de incorporación

    • Se quitó la funcionalidad de incorporación no admitida (embedContent y batchEmbedContents) del modelo.

Unity

La compatibilidad con Unity no estaba disponible en “Vertex AI in Firebase”.

Obtén información para comenzar a usar el SDK de Firebase AI Logic para Unity.

Posibles errores relacionados con la migración

Cuando realices la migración para usar la versión GA de Firebase AI Logic, es posible que encuentres errores si no completaste todos los cambios necesarios, como se describe en esta guía de migración.

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

Si recibes un error 403 que dice Requests to this API firebasevertexai.googleapis.com ... are blocked., por lo general, significa que la clave de API de Firebase en tu objeto o archivo de configuración de Firebase no tiene una API requerida en su lista de entidades permitidas para el producto que intentas usar.

Asegúrate de que la clave de API de Firebase que usa tu app tenga todas las APIs requeridas incluidas en la lista de entidades permitidas de "restricciones de API" de la clave. En el caso de Firebase AI Logic, tu clave de API de Firebase debe tener, como mínimo, la API de Firebase AI Logic en su lista de entidades permitidas. Esta API debería haberse agregado automáticamente a la lista de entidades permitidas de tu clave de API cuando habilitaste las APIs requeridas en la consola de Firebase.

Puedes ver todas tus claves de API en el panel APIs y servicios > Credenciales de la consola de Google Cloud.


Envía comentarios sobre tu experiencia con Firebase AI Logic