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 se llamaban anteriormente "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 tus apps web o para dispositivos móviles, ahora puedes elegir un proveedor de "Gemini API": Vertex AI Gemini API, que está disponible desde hace mucho tiempo, o 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 de frecuencia y cuotas razonables.

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

  • Paso 1: Elige el mejor proveedor de la "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 la "API de Gemini" para tu app

Con esta migración, puedes elegir el proveedor de "Gemini API":

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

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

Revisa las diferencias entre los dos proveedores de Gemini API, en especial en cuanto a las funciones compatibles, los precios y los límites de frecuencia. Por ejemplo, Gemini Developer API no admite la entrega de archivos con URLs de 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 para tu proyecto.

  4. Selecciona el proveedor de la "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 Spark sin costo)
      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. Obtén más información.

    • Vertex AI Gemini API: Se requiere facturación (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 tu proyecto de app abierto, actualiza tu paquete de Firebase a la versión 11.13.0 o 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 Package Dependencies. 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 posterior. Si no es así, verifica que los Requisitos del paquete especificados permitan la actualización a la versión 11.13.0 o posterior.

  3. Selecciona el destino de tu app en el editor de proyectos y, luego, navega a la sección Frameworks, Libraries, and Embedded Content.

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

  5. Después de terminar 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 del módulo (nivel de app) (generalmente <project>/<app-module>/build.gradle.kts o <project>/<app-module>/build.gradle), reemplaza las dependencias anteriores (según corresponda) por las siguientes.

    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.16.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 del módulo (nivel de app) (generalmente <project>/<app-module>/build.gradle.kts o <project>/<app-module>/build.gradle), reemplaza las dependencias anteriores (según corresponda) por las siguientes.

    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.16.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. Dondequiera que 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 antiguas.

    // 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 el uso del 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

No se pudo obtener asistencia para Unity desde "Vertex AI in Firebase".

Aprende a 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 la 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 asistencia para Unity no estaba disponible en "Vertex AI in Firebase".

Aprende a comenzar a usar el SDK de Firebase AI Logic para Unity.

Ten en cuenta que según la capacidad que uses, es posible que no siempre crees 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 de Cloud Storage y cambiaste a usar 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 AA de los SDKs de "Vertex AI in Firebase". Estos mismos cambios son necesarios para usar los SDKs de Firebase AI Logic. Revisa las siguientes listas para ver si hay cambios que debas realizar en tu código para admitir el SDK de Firebase AI Logic.

Obligatorio para todos los idiomas y plataformas

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

  • Genera resultados estructurados (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 para 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 structs con variables estáticas. Este cambio permite una mayor flexibilidad para desarrollar la API de forma retrocompatible. Cuando uses instrucciones switch, ahora debes incluir un caso default: para abarcar 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 structs): 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 compatible con versiones anteriores. Este cambio se describe con más detalle en la sección Partes de contenido.

  • Partes de 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 generando 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 él como SafetySetting.HarmCategory, puedes reemplazarlo por HarmCategory.

  • Comentarios sobre seguridad

    • Se quitó el tipo SafetyFeedback, ya que no se usaba 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 siguen siendo configurables en el inicializador.

Kotlin

  • Enumeraciones

    • Se reemplazaron las clases enum y sealed por clases regulares. Este cambio permite una mayor flexibilidad para desarrollar la API de forma retrocompatible.

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

    • Se quitaron 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 anulable.

  • Clase de duración

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

  • Metadatos de citas

    • Se encapsularon todos los campos declarados anteriormente en CitationMetadata en una nueva clase 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 las diferentes plataformas.

  • Recuento de tokens

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

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

  • Crea una instancia de un modelo

    • Se trasladó 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 anidaron 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 regulares. Este cambio permite una mayor flexibilidad para desarrollar la API de forma retrocompatible.

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

    • Se quitaron 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 anulable.

  • Clase de duración

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

  • Metadatos de citas

    • Se encapsularon todos los campos declarados anteriormente en CitationMetadata en una nueva clase 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 las diferentes plataformas.

  • Recuento de tokens

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

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

  • Crea una instancia de un modelo

    • Se trasladó 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 anidaron 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 devuelvan correctamente la instancia de su clase, en lugar de void.

Web

  • Enumeraciones

    • Se quitaron 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 necesarios 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 admitido.

  • Datos intercalados

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

Dart

  • Enumeraciones

    • Se quitaron 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 static data por inlineData para alinearse con otras plataformas.

  • Opciones de solicitud

    • Se quitó RequestOptions porque timeout no era funcional. Se volverá a agregar en el futuro cercano, pero se cambiará 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 se establezca de forma predeterminada en 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 involuntaria: defaultTimeout, CountTokensResponseFields, parseCountTokensResponse, parseEmbedContentResponse, parseGenerateContentResponse, parseContent, BatchEmbedContentsResponse, ContentEmbedding, EmbedContentRequest y EmbedContentResponse.

  • Recuento de tokens

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

  • Crea una instancia de un modelo

    • Se trasladó 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 embedding no admitida (embedContent y batchEmbedContents) del modelo.

Unity

No se pudo obtener asistencia para Unity desde "Vertex AI in Firebase".

Aprende a comenzar a usar el SDK de Firebase AI Logic para Unity.

Posibles errores relacionados con la migración

A medida que migras para usar la versión de DG 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., suele significar 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