Crea experiencias híbridas en apps para Android con modelos alojados en la nube y en el dispositivo


Puedes compilar apps y funciones de Android potenciadas por IA con inferencia híbrida usando Firebase AI Logic. La inferencia híbrida permite ejecutar la inferencia con modelos en el dispositivo cuando están disponibles y, de lo contrario, recurrir sin problemas a los modelos alojados en la nube (y viceversa).

En esta página, se describe cómo comenzar a usar el SDK del cliente, además de mostrar opciones y capacidades de configuración adicionales, como la temperatura.

Ten en cuenta que la inferencia en el dispositivo a través de Firebase AI Logic es compatible con las apps para Android que usan el SDK de Firebase AI Logic v17.10.0+ (BoM v34.10.0+) y que se ejecutan en dispositivos específicos. Se rige por las condiciones del Kit de AA, así como por las condiciones específicas de los aspectos de IA generativa del Kit de AA.

Casos de uso recomendados y capacidades compatibles

Casos de uso recomendados

  • El uso de un modelo en el dispositivo para la inferencia ofrece lo siguiente:

    • Mejora la privacidad
    • Contexto local
    • Inferencia sin costo
    • Funcionalidad sin conexión

  • El uso de la funcionalidad híbrida ofrece lo siguiente:

    • Llega a más público adaptando la disponibilidad del modelo en el dispositivo y la conectividad a Internet.

Funciones y capacidades compatibles para la inferencia en el dispositivo

La inferencia en el dispositivo solo admite la generación de texto de un solo turno (no chat), con salida de transmisión o sin transmisión. Admite las siguientes capacidades de generación de texto:

Asegúrate de revisar la lista de funciones que aún no están disponibles para la inferencia en el dispositivo en la parte inferior de esta página.

Antes de comenzar

Observa lo siguiente:

Dispositivos Android compatibles y sus modelos en el dispositivo

Para la inferencia en el dispositivo (que usa la API de Prompt del Kit de AA), puedes encontrar una lista de dispositivos compatibles y sus modelos en el dispositivo en la documentación del Kit de AA.

Comenzar

En estos pasos para comenzar, se describe la configuración general requerida para cualquier solicitud de instrucción compatible que desees enviar.

Paso 1: Configura un proyecto de Firebase y conecta tu app a Firebase

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

  2. En la consola Firebase, ve a AI Services > AI Logic.

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

  4. Si se te solicita, sigue las instrucciones en pantalla para registrar tu app y agregar la configuración de Firebase a la app.

  5. Cuando se te solicite elegir un "proveedor de la API de Gemini", te recomendamos que selecciones la API para desarrolladores de Gemini, que te permite comenzar rápidamente sin costo.

    En cualquier momento posterior, puedes configurar la Vertex AI Gemini API (y su requisito de facturación).

  6. Continúa en el flujo de trabajo para configurar las APIs requeridas y los servicios asociados para Firebase AI Logic.

    A partir de principios de julio de 2026, esta etapa del flujo de trabajo aplicará automáticamente la Firebase App Check para AI Logic, que es un servicio fundamental para proteger la Gemini API cuando se accede directamente desde tu app. Como parte de los primeros pasos (consulta los pasos más adelante en esta guía), deberás configurar el App Check proveedor de depuración para el desarrollo local cuando se aplique la App Check.

  7. Continúa con el siguiente paso de esta guía para agregar los SDKs requeridos a tu app.

Paso 2: Agrega los SDKs requeridos

El Firebase AI Logic SDK para Android (firebase-ai) junto con el Firebase AI Logic On-Device SDK (firebase-ai-ondevice) proporcionan acceso a las APIs para interactuar con modelos generativos.

En el archivo Gradle del módulo (nivel de la app) (como <project>/<app-module>/build.gradle.kts), agrega las dependencias de las Firebase AI Logic y App Check bibliotecas para Android:

Kotlin 

dependencies {
  // ... other androidx dependencies

  // Add the dependencies for the Firebase AI Logic and App Check libraries
  // Note that the on-device SDK is not yet included in the Firebase Android BoM
  implementation("com.google.firebase:firebase-ai:17.13.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta03")
  implementation("com.google.firebase:firebase-appcheck-debug:19.2.0")
}

Java

En el caso de Java, debes agregar dos bibliotecas adicionales.

dependencies {
  // ... other androidx dependencies

  // Add the dependencies for the Firebase AI Logic and App Check libraries
  // Note that the on-device SDK is not yet included in the Firebase Android BoM
  implementation("com.google.firebase:firebase-ai:17.13.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta03")
  implementation("com.google.firebase:firebase-appcheck-debug:19.2.0")

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

Paso 3: Configura el proveedor de depuración App Check para el desarrollo local

A partir de principios de julio de 2026, como parte del flujo de trabajo de configuración guiada para AI Logic en la consola, Firebase App Check se aplicará automáticamente para proteger la Gemini API. Para el desarrollo local, debes configurar el App Check proveedor de depuración para omitir la certificación y, al mismo tiempo, mantener la aplicación de App Check.

  1. En la compilación de depuración, configura App Check para que use la fábrica de proveedores de depuración:

    Kotlin

    Firebase.initialize(context = this)
Firebase.appCheck.installAppCheckProviderFactory(
    DebugAppCheckProviderFactory.getInstance(),
)

    Java

    FirebaseApp.initializeApp(/*context=*/ this);
FirebaseAppCheck firebaseAppCheck = FirebaseAppCheck.getInstance();
firebaseAppCheck.installAppCheckProviderFactory(
        DebugAppCheckProviderFactory.getInstance());

  2. Obtén tu token de depuración:

    1. Ejecuta tu app en el emulador o en tu dispositivo de prueba.

    2. Busca el token de depuración App Check en tus registros. Por ejemplo:

      D DebugAppCheckProvider: Enter this debug secret into the allow list
in the Firebase Console for your project: 123a4567-b89c-12d3-e456-789012345678

    3. Copia el token (por ejemplo, 123a4567-b89c-12d3-e456-789012345678).

  3. Registra tu token de depuración con App Check:

    1. En la consola Firebase, ve a la pestaña Security > App Check > Apps.

    2. Busca tu app, haz clic en el menú ampliado () y, luego, selecciona Administrar tokens de depuración.

    3. Sigue las instrucciones en pantalla para registrar tu token de depuración.

Para obtener detalles sobre el proveedor de depuración (incluido cómo obtener un token de depuración nuevo), consulta la documentación App Check oficial.

Paso 4: Verifica si el modelo en el dispositivo está disponible

Con FirebaseAIOnDevice, verifica si el modelo en el dispositivo está disponible y descárgalo si no lo está disponible.

Una vez descargado, AICore mantendrá automáticamente actualizado el modelo. Consulta las notas después del fragmento para obtener más detalles sobre AICore y administrar la descarga del modelo en el dispositivo.

Kotlin 

val status = FirebaseAIOnDevice.checkStatus()
when (status) {
  OnDeviceModelStatus.UNAVAILABLE -> {
    Log.w(TAG, "On-device model is unavailable")
  }

  OnDeviceModelStatus.DOWNLOADABLE -> {
    FirebaseAIOnDevice.download().collect { status ->
      when (status) {
        is DownloadStatus.DownloadStarted ->
          Log.w(TAG, "Starting download - ${status.bytesToDownload}")

        is DownloadStatus.DownloadInProgress ->
          Log.w(TAG, "Download in progress ${status.totalBytesDownloaded} bytes downloaded")

        is DownloadStatus.DownloadCompleted ->
          Log.w(TAG, "On-device model download complete")

        is DownloadStatus.DownloadFailed ->
          Log.e(TAG, "Download failed ${status}")
      }
    }
  }
  OnDeviceModelStatus.DOWNLOADING -> {
    Log.w(TAG, "On-device model is being downloaded")
  }

  OnDeviceModelStatus.AVAILABLE -> {
    Log.w(TAG, "On-device model is available")
  }
}

Java 

Checking for and downloading the model is not yet available for Java.

However, all other APIs and interactions in this guide are available for Java.

Ten en cuenta lo siguiente sobre la descarga del modelo en el dispositivo:

  • El tiempo que tarda en descargarse el modelo en el dispositivo depende de muchos factores, incluida tu red.

  • Si tu código usa un modelo en el dispositivo para su inferencia principal o de resguardo, asegúrate de que el modelo se descargue al principio del ciclo de vida de tu app para que esté disponible antes de que los usuarios finales encuentren el código en tu app.

  • Si el modelo en el dispositivo no está disponible cuando se realiza una solicitud de inferencia en el dispositivo, el SDK no activará automáticamente la descarga del modelo en el dispositivo. El SDK recurrirá al modelo alojado en la nube o generará una excepción (consulta los detalles sobre el comportamiento de los modos de inferencia).

  • AICore (un servicio del sistema Android) administra el modelo y la versión que se descargan, mantiene actualizado el modelo, etc. Ten en cuenta que el dispositivo solo tendrá un modelo descargado, por lo que, si otra app del dispositivo descargó correctamente el modelo en el dispositivo, esta verificación mostrará que el modelo está disponible.

Optimización de latencia

Para optimizar la primera llamada de inferencia, puedes hacer que tu app llame a warmup(). Esto carga el modelo en el dispositivo en la memoria e inicializa los componentes del entorno de ejecución.

Paso 5: Inicializa el servicio y crea una instancia del modelo

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

Configura lo siguiente antes de enviar una solicitud de instrucción al modelo.

  1. Inicializa el servicio para el proveedor de la API que elegiste.

  2. Crea una instancia de GenerativeModel y establece el mode en uno de los siguientes valores. Las descripciones aquí son de muy alto nivel, pero puedes obtener detalles sobre el comportamiento de estos modos en Establece un modo de inferencia.

    • PREFER_ON_DEVICE: Intenta usar el modelo en el dispositivo; de lo contrario, recurre al modelo alojado en la nube.

    • ONLY_ON_DEVICE: Intenta usar el modelo en el dispositivo; de lo contrario, genera una excepción.

    • PREFER_IN_CLOUD: Intenta usar el modelo alojado en la nube; de lo contrario, recurre al modelo en el dispositivo.

    • ONLY_IN_CLOUD: Intenta usar el modelo alojado en la nube; de lo contrario, genera una excepción.

Kotlin 

// Using this SDK to access on-device inference is an Experimental release and requires opt-in
@OptIn(PublicPreviewAPI::class)

// ...

// Initialize the Gemini Developer API backend service
// Create a GenerativeModel instance with a model that supports your use case
// Set the inference mode (like PREFER_ON_DEVICE to use the on-device model if available)
val model = Firebase.ai(backend = GenerativeBackend.googleAI())
    .generativeModel(
        modelName = "MODEL_NAME",
        onDeviceConfig = OnDeviceConfig(mode = InferenceMode.PREFER_ON_DEVICE)
    )

Java 

// Initialize the Gemini Developer API backend service
// Create a GenerativeModel instance with a model that supports your use case
// Set the inference mode (like PREFER_ON_DEVICE to use the on-device model if available)
GenerativeModel ai = FirebaseAI.getInstance(GenerativeBackend.googleAI())
    .generativeModel(
        "MODEL_NAME",
        new OnDeviceConfig(InferenceMode.PREFER_ON_DEVICE)
    );

// Use the GenerativeModelFutures Java compatibility layer which offers
// support for ListenableFuture and Publisher APIs
GenerativeModelFutures model = GenerativeModelFutures.from(ai);

Paso 6: Envía una solicitud de instrucción a un modelo

En esta sección, se muestra cómo enviar varios tipos de entrada para generar diferentes tipos de salida, incluidos los siguientes:

Generar texto a partir de entradas de solo texto

Antes de probar esta muestra, asegúrate de haber completado la sección Comienza de esta guía.

Puedes usar generateContent() para generar texto a partir de una instrucción que contenga texto:

Kotlin 

// Imports + initialization of Gemini API backend service + creation of model instance

// Provide a prompt that contains text
val prompt = "Write a story about a magic backpack."

// To generate text output, call generateContent with the text input
val response = model.generateContent(prompt)
print(response.text)

Java 

// Imports + initialization of Gemini API backend service + creation of model instance

// Provide a prompt that contains text
Content prompt = new Content.Builder()
    .addText("Write a story about a magic backpack.")
    .build();

// To generate text output, call generateContent with the text input
ListenableFuture<GenerateContentResponse> response = model.generateContent(prompt);
Futures.addCallback(response, new FutureCallback<GenerateContentResponse>() {
    @Override
    public void onSuccess(GenerateContentResponse result) {
        String resultText = result.getText();
        System.out.println(resultText);
    }

    @Override
    public void onFailure(Throwable t) {
        t.printStackTrace();
    }
}, executor);

Ten en cuenta que Firebase AI Logic también admite la transmisión de respuestas de texto con generateContentStream (en lugar de generateContent).

Generar texto a partir de entradas de texto e imagen (multimodales)

Antes de probar esta muestra, asegúrate de haber completado la sección Comienza de esta guía.

Puedes usar generateContent() para generar texto a partir de una instrucción que contenga texto y hasta un archivo de imagen (solo mapa de bits) , proporcionando el mimeType de cada archivo de entrada y el archivo en sí.

Kotlin 

// Imports + initialization of Gemini API backend service + creation of model instance

// Loads an image from the app/res/drawable/ directory
val bitmap: Bitmap = BitmapFactory.decodeResource(resources, R.drawable.sparky)

// Provide a prompt that includes the image specified above and text
val prompt = content {
  image(bitmap)
  text("What developer tool is this mascot from?")
}

// To generate text output, call generateContent with the prompt
val response = model.generateContent(prompt)
print(response.text)

Java 

// Imports + initialization of Gemini API backend service + creation of model instance

Bitmap bitmap = BitmapFactory.decodeResource(getResources(), R.drawable.sparky);

// Provide a prompt that includes the image specified above and text
Content content = new Content.Builder()
        .addImage(bitmap)
        .addText("What developer tool is this mascot from?")
        .build();

// To generate text output, call generateContent with the prompt
ListenableFuture<GenerateContentResponse> response = model.generateContent(content);
Futures.addCallback(response, new FutureCallback<GenerateContentResponse>() {
    @Override
    public void onSuccess(GenerateContentResponse result) {
        String resultText = result.getText();
        System.out.println(resultText);
    }

    @Override
    public void onFailure(Throwable t) {
        t.printStackTrace();
    }
}, executor);

Ten en cuenta que Firebase AI Logic también admite la transmisión de respuestas de texto con generateContentStream (en lugar de generateContent).

¿Qué más puedes hacer?

Puedes usar varias opciones y capacidades de configuración adicionales para tus experiencias híbridas:

Funciones que aún no están disponibles para la inferencia en el dispositivo

Como lanzamiento experimental, no todas las capacidades de los modelos en la nube están disponibles para la inferencia en el dispositivo.

Las funciones que se enumeran en esta sección aún no están disponibles para la inferencia en el dispositivo. Si deseas usar alguna de estas funciones, te recomendamos que uses el modo de inferencia ONLY_IN_CLOUD para obtener una experiencia más coherente.

  • Generar resultados estructurados (como JSON o enumeraciones)

  • Generar texto a partir de tipos de entrada de archivos de imagen que no sean mapas de bits (imagen cargada en la memoria)

  • Generar texto a partir de más de un archivo de imagen

  • Generar texto a partir de entradas de audio, video y documentos (como PDFs)

  • Generar imágenes con modelos de Gemini o Imagen

  • Proporcionar archivos con URLs en solicitudes multimodales. Debes proporcionar archivos como datos intercalados a los modelos en el dispositivo.

  • Enviar solicitudes que superen los 4,000 tokens (o aproximadamente 3,000 palabras en inglés)

  • Chat de varios turnos

  • Proporcionar al modelo herramientas para ayudarlo a generar su respuesta (como llamadas a funciones, ejecución de código, contexto de URL, Grounding con Google Search, y Grounding con Google Maps)

La supervisión de IA en la consola de Firebase no muestra ningún dato para la inferencia en el dispositivo (incluidos los registros en el dispositivo). Sin embargo, cualquier inferencia que use un modelo alojado en la nube se puede supervisar como cualquier otra inferencia a través de Firebase AI Logic.

Limitaciones adicionales

Además de lo anterior, la inferencia en el dispositivo tiene las siguientes limitaciones (obtén más información en la documentación del Kit de AA):

  • El usuario final de tu app debe usar un dispositivo compatible para la inferencia en el dispositivo.

  • Tu app solo puede ejecutar la inferencia en el dispositivo cuando está en primer plano.

  • Solo se validaron el inglés y el coreano para la inferencia en el dispositivo.

  • El límite máximo de tokens para toda la solicitud de inferencia en el dispositivo es de 4,000 tokens. Si tus solicitudes pueden superar este límite, asegúrate de configurar un modo de inferencia que pueda usar un modelo alojado en la nube.

  • Te recomendamos que evites los casos de uso de inferencia en el dispositivo que requieran una salida larga (más de 256 tokens).

  • AICore (un servicio del sistema Android que administra los modelos en el dispositivo) aplica una cuota de inferencia por app. Si realizas demasiadas solicitudes a la API en un período breve, se generará una respuesta ErrorCode.BUSY. Si recibes este error, considera usar la retirada exponencial para reintentar la solicitud. Además, se puede mostrar ErrorCode.PER_APP_BATTERY_USE_QUOTA_EXCEEDED si una app supera una cuota de larga duración (por ejemplo, la cuota diaria).


Envía comentarios sobre tu experiencia con Firebase AI Logic