Firebase AI Logic (Conceptos Básicos)

Conceptos Básicos de Firebase AI Logic

Descripción general

Firebase AI Logic es un producto de Firebase que permite a los desarrolladores añadir IA generativa (gen AI) a sus aplicaciones móviles y web mediante SDKs del lado del cliente. La aplicación puede llamar directamente a los modelos Gemini a través de Firebase AI Logic sin que el desarrollador necesite gestionar un backend dedicado. Firebase AI Logic se conocía anteriormente como "Vertex AI para Firebase".

Admite dos proveedores de API de Gemini:

• API de Gemini Developer: Tiene un nivel gratuito ideal para prototipado, y de pago por uso para producción.
• API de Gemini de Agent Platform (anteriormente Vertex AI): Ideal para escalar con preparación empresarial para producción, requiere el plan de precios Blaze.

Usa la API de Gemini Developer por defecto, y solo la API de Gemini de Agent Platform (anteriormente Vertex AI) si la aplicación lo requiere.

---

Configuración e inicialización

Requisitos previos

• Identifica la plataforma en la que el usuario está interesado en desarrollar antes de comenzar: Android, iOS, Web o Flutter.
• Si su plataforma no es compatible, dirige al usuario a la documentación de Firebase para aprender cómo configurar AI Logic para su aplicación (comparte este enlace con el usuario https://firebase.google.com/docs/ai-logic/get-started).
• Los comandos de Firebase CLI que aparecen a continuación se ejecutan mediante npx en todas las plataformas, por lo que se necesita Node.js 20+ y npm. Usa la habilidad firebase-basics para verificar su presencia e iniciar sesión en la Firebase CLI. Si Node.js falta o es anterior a la versión 20, pide al usuario que lo instale según lo descrito en esa habilidad. No instales paquetes del sistema tú mismo, por ejemplo con sudo apt-get, ya que eso modifica la máquina del usuario sin su consentimiento.

1. Aprovisionar Firebase AI Logic (TODAS las plataformas)

Usa la Firebase CLI para aprovisionar Firebase AI Logic para el proyecto de Firebase:

1. Asegúrate de estar en un directorio de Firebase (con un archivo firebase.json).

2. Verifica que estás ejecutando comandos de la Firebase CLI contra el proyecto de Firebase previsto. Cuando ejecutes este comando, el proyecto activo se marca con "current":

   npx -y firebase-tools@latest projects:list
   

3. Asegúrate de que haya al menos una aplicación de Firebase para la plataforma de destino registrada con el proyecto actual de Firebase:

   npx -y firebase-tools@latest apps:list
   

4. Aprovisiona Firebase AI Logic para el proyecto de Firebase:

   npx -y firebase-tools@latest init ailogic
   

   Este comando habilitará la API de Gemini Developer en el proyecto de Firebase.

[!WARNING] CRÍTICO: Es necesario aprovisionar Firebase AI Logic Para todas las plataformas (Android, iOS, Web o Flutter), incluso si la aplicación ya usa Firebase, DEBES ejecutar npx -y firebase-tools@latest init ailogic para aprovisionar el servicio. Los archivos de configuración GoogleService-Info.plist, google-services.json y firebase_options.dart SOLO manejan la configuración del cliente y NO habilitan el servicio de Firebase AI Logic, lo que provoca errores PERMISSION_DENIED.

Si no puedes ejecutar init ailogic tú mismo (por ejemplo, porque falta Node.js o la Firebase CLI no ha iniciado sesión), NO lo omitas. Las solicitudes de la aplicación a los modelos Gemini fallarán hasta que se haya aprovisionado el servicio Firebase AI Logic. Indica al usuario que ejecute este comando en su directorio de proyecto e inclúyelo en tu resumen final:

npx -y firebase-tools@latest init ailogic

2. Añadir el SDK e inicializar el servicio en la aplicación

Añadir la dependencia del SDK e inicializar el servicio son específicos de cada plataforma. Antes de escribir código, lee la referencia de la plataforma de destino que se encuentra en Referencias de código de inicialización.

Más información en Guía de inicio de Firebase AI Logic

---

Capacidades principales

[!WARNING] CRÍTICO: Usa nombres de modelos actuales: Siempre consulta la documentación de modelos de Firebase AI Logic para conocer los nombres de modelos compatibles actualmente. NO uses gemini-2.0-pro ni gemini-2.0-flash ni otros modelos antiguos que ya no están disponibles.

Generación solo texto

Multimodal (entrada de texto + imágenes/audio/video/PDF)

Firebase AI Logic permite que los modelos Gemini analicen archivos de imagen directamente desde la aplicación. Esto habilita funciones como crear pies de foto, responder preguntas sobre imágenes, detectar objetos y categorizar imágenes. Más allá de las imágenes, Gemini puede analizar otros tipos de medios como audio, video y PDF pasándolos como datos en línea con su tipo MIME. Para archivos de más de 20 megabytes (que pueden causar errores HTTP 413 como datos en línea), almacénalos en Cloud Storage para Firebase y pasa sus URLs a la API de Gemini Developer.

Sesión de chat (varias interacciones)

Mantén el historial automáticamente usando startChat.

Respuestas en streaming

Para mejorar la experiencia del usuario mostrando resultados parciales a medida que llegan (como un efecto de escritura), usa generateContentStream en lugar de generateContent para una visualización más rápida de los resultados.

Generación de texto a voz (TTS)

Genera audio hablado directamente en los dispositivos del cliente sin un backend de voz personalizado. Firebase AI Logic admite síntesis de voz usando modelos Gemini TTS dedicados:

• Modelos compatibles: gemini-3.1-flash-tts-preview
• Capacidades:
  • Selección de perfil de voz de un solo hablante (voiceName) y diálogos de múltiples hablantes (hasta 2 hablantes distintos) mediante SpeechConfig / MultiSpeakerVoiceConfig
  • Respuestas de audio directas estableciendo responseModalities en audio
  • Respuestas de voz en streaming con generateContentStream para reproducción de baja latencia
  • Directivas de audio ([Audio Profile: ...], [Scene: ...], [Director's Note: ...]) y etiquetas emocionales ([whispers], [laughs], [slowly])
  • Decodificación y reproducción en el cliente de PCM lineal de 24 kHz y 16 bits (audio/l16) o formato contenedor WAV (audio/x-wav)

Consulta la Guía de generación de texto a voz (TTS) para obtener detalles completos de implementación, patrones de streaming y fragmentos de código listos para copiar y pegar para iOS (Swift), Android (Kotlin) y Web.

Generar imágenes con Nano Banana

[!WARNING] Usa nombres de modelos de imagen actuales: Siempre consulta la documentación de modelos de Firebase AI Logic para conocer los nombres de modelos de generación de imágenes (Nano Banana) compatibles actualmente.

• Requiere un plan de facturación Blaze de pago por uso mejorado.

Búsqueda con fundamentación utilizando la herramienta integrada googleSearch

---

Plataformas y marcos compatibles

Las plataformas y marcos compatibles incluyen Kotlin y Java para Android, Swift para iOS, JavaScript para aplicaciones web, Dart para Flutter y C Sharp para Unity.

Funciones avanzadas

Salida estructurada (JSON)

Impón un esquema JSON específico para la respuesta.

IA en el dispositivo (Híbrida)

La inferencia híbrida ejecuta indicaciones con un modelo en el dispositivo cuando está disponible y recurre a un modelo alojado en la nube en caso contrario (o viceversa). La disponibilidad y los pasos de configuración difieren según la plataforma. Más información en la documentación híbrida y en el dispositivo, que enlaza con la guía de cada plataforma.

---

Seguridad y producción

Firebase App Check

[!WARNING] Requisito de seguridad crítico: Para usar AI Logic de forma segura, DEBES configurar App Check en tu aplicación. Esto evita que clientes no autorizados utilicen tu cuota de API y accedan a tus recursos de backend.

Consulta App Check para Firebase AI Logic para obtener instrucciones de configuración. Cada plataforma utiliza su propio proveedor de atestación, por lo que debes seguir las instrucciones de la plataforma de destino.

Tokens de depuración de App Check para desarrollo local y CI/CD

Debido a que los proveedores de atestación de App Check (como Play Integrity o DeviceCheck) rechazan emuladores, simuladores o entornos de CI, debes usar tokens de depuración de App Check durante el desarrollo y las pruebas para omitir la atestación estándar.

[!WARNING] CRÍTICO: Nunca codifiques ni confirmes tokens de depuración Los tokens de depuración de App Check permiten que los clientes omitan la atestación y accedan a los recursos de backend sin un dispositivo genuino. Trátalos como secretos privados. Nunca confirmes tokens de depuración en el control de versiones ni codifiques cadenas de tokens sin formato en el código del cliente (Web, Android, iOS o Flutter). Insértalos siempre a través de variables de entorno locales, configuraciones locales ignoradas por git o secretos de CI. Si un token se ve comprometido, revócalo inmediatamente en la consola de Firebase.

Desarrollo local (generado automáticamente)

1. Configura el proveedor de App Check de tu código para usar la fábrica de depuración. La API es específica de la plataforma; consulta la sección de App Check de la referencia de la plataforma o la documentación de App Check enlazada anteriormente.
2. Ejecuta tu aplicación en el emulador/localhost.
3. Busca en la consola de depuración / logs de Logcat en tiempo de ejecución el UUID generado:
   • Ejemplo: AppCheck debug token: "123a4567-b89c-12d3-e456-789012345678"
4. Registra este token en la consola de Firebase en Seguridad > App Check > Aplicaciones > Gestionar tokens de depuración.

💡 Consejo (evitar la rotación de tokens de depuración): Los reinicios del simulador o emulador, las instalaciones nuevas y la eliminación de datos del navegador pueden hacer que el SDK genere un nuevo token de depuración que debes registrar nuevamente. Para mantener un token de depuración estable sin codificarlo, consulta la sección de App Check de la referencia de la plataforma.

Canalizaciones de CI/CD (preaprovisionado)

1. Genera y registra un nuevo token de depuración en la consola de Firebase en Seguridad > App Check > Aplicaciones > Gestionar tokens de depuración.
2. Añade esta cadena de token como un secreto cifrado en tu sistema de CI (por ejemplo, APP_CHECK_DEBUG_TOKEN).
3. Configura tu compilación para pasar este secreto como una variable de entorno al SDK durante la ejecución de las pruebas.

Firebase Remote Config

Considera que no necesitas codificar nombres de modelos (por ejemplo, una cadena de versión específica de modelo). Usa Firebase Remote Config para actualizar las versiones de los modelos de forma dinámica sin implementar nuevo código del cliente. Consulta Cambiar nombres de modelos de forma remota

---

Referencias de código de inicialización

• Android (Kotlin)

  • Proveedor de API de Gemini: API de Gemini Developer
  • Referencia: usage_patterns_android.md

• iOS (Swift)

  • Proveedor de API de Gemini: API de Gemini Developer
  • Referencia: ios_setup.md

• Web (API modular)

  • Proveedor de API de Gemini: API de Gemini Developer
  • Referencia: usage_patterns_web.md

• Flutter (Dart)

  • Proveedor de API de Gemini: API de Gemini Developer
  • Referencia: flutter_setup.md

[!WARNING] CRÍTICO: Usa nombres de modelos actuales: Siempre consulta la documentación de modelos de Firebase AI Logic para conocer los nombres de modelos compatibles actualmente. NO uses gemini-2.0-pro ni gemini-2.0-flash ni otros modelos antiguos que ya no están disponibles.

Referencias

Patrones de uso del SDK de Android (Kotlin) Ejemplos de código y patrones de uso del SDK de iOS Configuración, ejemplos de código y patrones de uso del SDK web

Ejemplos de código y patrones de uso del SDK de Flutter Generación de texto a voz (TTS) del lado del cliente