Créer des expériences hybrides dans les applications Android avec des modèles hébergés sur l'appareil et dans le cloud


Vous pouvez créer des applications et des fonctionnalités Android optimisées par l'IA avec l'inférence hybride à l'aide de Firebase AI Logic. L'inférence hybride permet d'exécuter l'inférence à l'aide de modèles sur l'appareil lorsqu'ils sont disponibles et de revenir de manière transparente aux modèles hébergés dans le cloud dans le cas contraire (et vice versa).

Cette page explique comment commencer à utiliser le SDK client et présente des options de configuration et fonctionnalités supplémentaires.

Notez que l'inférence sur l'appareil via Firebase AI Logic est compatible avec les applications Android utilisant le SDK Firebase AI Logic v17.10.0 ou version ultérieure (BoM v34.10.0 ou version ultérieure) et s'exécutant sur des appareils spécifiques. Elle est régie par les Conditions d'utilisation de ML Kit, ainsi que par les Conditions spécifiques aux aspects d'IA générative de ML Kit.

Cas d'utilisation recommandés et fonctionnalités compatibles

Cas d'utilisation recommandés

  • L'utilisation d'un modèle sur l'appareil pour l'inférence offre les avantages suivants :

    • Confidentialité renforcée
    • Contexte local
    • Inférence sans frais
    • Fonctionnalités hors connexion

  • L'utilisation de la fonctionnalité hybride offre les avantages suivants :

    • Touchez une plus grande partie de votre audience en tenant compte de la disponibilité des modèles sur l'appareil et de la connectivité Internet.

Fonctionnalités compatibles pour l'inférence sur l'appareil

L'inférence sur l'appareil n'est compatible qu'avec la génération de texte à tour unique (pas le chat), avec une sortie en streaming ou non. Il prend en charge les fonctionnalités de génération de texte suivantes :

Consultez la liste des fonctionnalités pas encore disponibles pour l'inférence sur l'appareil en bas de cette page.

Avant de commencer

Veuillez noter les points suivants :

Appareils Android compatibles et leurs modèles sur l'appareil

Pour l'inférence sur l'appareil (qui utilise l'API Prompt de ML Kit), vous trouverez une liste des appareils compatibles et de leurs modèles sur l'appareil dans la documentation ML Kit.

Commencer

Ces étapes de démarrage décrivent la configuration générale requise pour toute demande de prompt compatible que vous souhaitez envoyer.

Étape 1 : Configurez un projet Firebase et associez votre application à Firebase

  1. Connectez-vous à la console Firebase, puis sélectionnez votre projet Firebase.

  2. Dans la console Firebase, accédez à Services d'IA > Logique d'IA.

  3. Cliquez sur Commencer pour lancer un workflow guidé qui vous aide à configurer les API requises et les ressources de votre projet.

  4. Si vous y êtes invité, suivez les instructions à l'écran pour enregistrer votre application et ajouter votre configuration Firebase à votre application.

  5. Lorsque vous êtes invité à choisir un "fournisseur d'API Gemini", nous vous recommandons de sélectionner l'API Gemini Developer, qui vous permet de commencer rapidement et sans frais.

    Vous pourrez toujours configurer Agent Platform Gemini API (formerly Vertex AI) (et ses exigences de facturation) à tout moment.

  6. Poursuivez le workflow pour configurer les API requises et les services associés pour Firebase AI Logic.

    À partir de début juillet 2026, cette étape du workflow appliquera automatiquement Firebase App Check pour AI Logic, un service essentiel pour protéger Gemini API lorsqu'il est accessible directement depuis votre application. Pour commencer (voir les étapes plus loin dans ce guide), vous devrez configurer le fournisseur de débogage App Check pour le développement local lorsque App Check est appliqué.

  7. Passez à l'étape suivante de ce guide pour ajouter les SDK requis à votre application.

Étape 2 : Ajouter les SDK nécessaires

Le SDK Firebase AI Logic pour Android (firebase-ai) et le SDK Firebase AI Logic On-Device (firebase-ai-ondevice) permettent d'accéder aux API pour interagir avec les modèles génératifs.

Dans le fichier Gradle de votre module (au niveau de l'application) (comme <project>/<app-module>/build.gradle.kts), ajoutez les dépendances pour les bibliothèques Firebase AI Logic et App Check pour 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:18.0.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta06")
  implementation("com.google.firebase:firebase-appcheck-debug:20.0.0")
}

Java

Pour Java, vous devez ajouter deux bibliothèques supplémentaires.

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:18.0.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta06")
  implementation("com.google.firebase:firebase-appcheck-debug:20.0.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")
}

Étape 3 : Configurer le fournisseur de débogage App Check pour le développement local

À partir de début juillet 2026, dans le cadre du workflow de configuration guidée de AI Logic dans la console, Firebase App Check est automatiquement appliqué pour protéger Gemini API. Pour le développement local, vous devez configurer le fournisseur de débogage App Check afin de contourner l'attestation tout en maintenant l'application de App Check.

  1. Dans votre version de débogage, configurez App Check pour utiliser la fabrique de fournisseurs de débogage :

    Kotlin

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

    Java

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

  2. Obtenez votre jeton de débogage :

    1. Exécutez votre application dans l'émulateur ou sur votre appareil de test.

    2. Recherchez le jeton de débogage App Check dans vos journaux. Exemple :

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

    3. Copiez le jeton (par exemple, 123a4567-b89c-12d3-e456-789012345678).

  3. Enregistrez votre jeton de débogage avec App Check :

    1. Dans la console Firebase, accédez à Sécurité > App Check > onglet Applications.

    2. Recherchez votre application, cliquez sur le menu à développer (), puis sélectionnez Gérer les jetons de débogage.

    3. Suivez les instructions à l'écran pour enregistrer votre jeton de débogage.

Pour en savoir plus sur le fournisseur de débogage (y compris sur la façon d'obtenir un nouveau jeton de débogage), consultez la documentation officielle de App Check.

Étape 4 : Vérifiez si le modèle sur l'appareil est disponible

À l'aide de FirebaseAIOnDevice, vérifiez si le modèle sur l'appareil est disponible et téléchargez-le s'il ne l'est pas.

Une fois téléchargé, AICore maintiendra automatiquement le modèle à jour. Consultez les notes après l'extrait pour en savoir plus sur AICore et la gestion du téléchargement du modèle sur l'appareil.

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, downloading, and warming up the model is not yet available for Java.

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

Notez les points suivants concernant le téléchargement du modèle sur l'appareil :

  • Le temps nécessaire pour télécharger le modèle sur l'appareil dépend de nombreux facteurs, y compris de votre réseau.

  • Si votre code utilise un modèle sur l'appareil pour son inférence principale ou de remplacement, assurez-vous que le modèle est téléchargé au début du cycle de vie de votre application afin qu'il soit disponible avant que vos utilisateurs finaux ne rencontrent le code dans votre application.

  • Si le modèle sur l'appareil n'est pas disponible lorsqu'une requête d'inférence sur l'appareil est effectuée, le SDK ne déclenchera pas automatiquement le téléchargement du modèle sur l'appareil. Le SDK utilisera le modèle hébergé dans le cloud ou générera une exception (voir les détails sur le comportement des modes d'inférence).

  • AICore (un service système Android) gère pour vous le modèle et la version téléchargés, maintient le modèle à jour, etc. Notez qu'un seul modèle sera téléchargé sur l'appareil. Par conséquent, si une autre application de l'appareil a déjà téléchargé le modèle sur l'appareil, cette vérification indique que le modèle est disponible.

Optimisation de la latence

Pour optimiser le premier appel d'inférence, vous pouvez demander à votre application d'appeler onDeviceExtension?.warmUp() (actuellement disponible pour Kotlin uniquement). Cela charge le modèle sur l'appareil en mémoire et initialise les composants d'exécution.

Étape 5 : Initialisez le service et créez une instance de modèle

Cliquez sur votre fournisseur Gemini API pour afficher le contenu et le code spécifiques à ce fournisseur sur cette page.

Configurez les éléments suivants avant d'envoyer une requête de prompt au modèle.

  1. Initialisez le service pour le fournisseur d'API de votre choix.

  2. Créez une instance GenerativeModel et définissez mode sur l'une des valeurs suivantes. Les descriptions fournies ici sont très générales, mais vous pouvez en savoir plus sur le comportement de ces modes dans Définir un mode d'inférence.

    • PREFER_ON_DEVICE : tente d'utiliser le modèle sur l'appareil. Sinon, bascule vers le modèle hébergé dans le cloud.

    • ONLY_ON_DEVICE : tente d'utiliser le modèle sur l'appareil. Sinon, génère une exception.

    • PREFER_IN_CLOUD : tente d'utiliser le modèle hébergé dans le cloud. Sinon, revenir au modèle sur l'appareil.

    • ONLY_IN_CLOUD : tente d'utiliser le modèle hébergé dans le cloud. Sinon, génère une exception.

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 = "CLOUD_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(
        "CLOUD_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);

Étape 6 : Envoyer une requête de prompt à un modèle

Cette section vous explique comment envoyer différents types d'entrées pour générer différents types de sorties, y compris :

Générer du texte à partir d'une entrée textuelle

Avant d'essayer cet exemple, assurez-vous d'avoir terminé la section Premiers pas de ce guide.

Vous pouvez utiliser generateContent() pour générer du texte à partir d'un prompt contenant du texte :

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);

Notez que Firebase AI Logic est également compatible avec le streaming des réponses textuelles à l'aide de generateContentStream (au lieu de generateContent).

Générer du texte à partir d'une entrée texte et image (multimodale)

Avant d'essayer cet exemple, assurez-vous d'avoir terminé la section Premiers pas de ce guide.

Vous pouvez utiliser generateContent() pour générer du texte à partir d'un prompt contenant du texte et jusqu'à un fichier image (bitmap uniquement), en fournissant le mimeType de chaque fichier d'entrée et le fichier lui-même.

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);

Notez que Firebase AI Logic accepte également le streaming des réponses textuelles à l'aide de generateContentStream (au lieu de generateContent).

Qu'est-ce que tu sais faire d'autre ?

Vous pouvez utiliser différentes options et fonctionnalités de configuration supplémentaires pour vos expériences hybrides :

Fonctionnalités pas encore disponibles pour l'inférence sur l'appareil

Comme il s'agit d'une version expérimentale, toutes les fonctionnalités des modèles cloud ne sont pas disponibles pour l'inférence sur l'appareil. Les fonctionnalités suivantes ne sont pas encore disponibles pour l'inférence sur l'appareil (mais elles sont généralement disponibles pour l'inférence dans le cloud).

  • Génération d'images…

    • Peut revenir au modèle hébergé dans le cloud. Toutefois, le mode ONLY_ON_DEVICE générera une exception.

  • Générer du texte à partir de types d'entrée de fichier image autres que Bitmap (image chargée en mémoire)

    • Peut basculer vers le modèle hébergé dans le cloud. Toutefois, le mode ONLY_ON_DEVICE génère une exception.

  • Générer du texte à partir d'une entrée de fichier image uniquement. Pour l'inférence sur l'appareil, vous devez fournir du texte dans la requête multimodale.

    • Peut basculer vers le modèle hébergé dans le cloud. Toutefois, le mode ONLY_ON_DEVICE génère une exception.

  • Générer du texte à partir de plusieurs entrées de fichier image

    • Peut revenir au modèle hébergé dans le cloud. Toutefois, le mode ONLY_ON_DEVICE générera une exception.

  • Générer du texte à partir d'entrées audio, vidéo et de documents (comme des PDF)

    • Peut revenir au modèle hébergé dans le cloud. Toutefois, le mode ONLY_ON_DEVICE générera une exception.

  • Fournir des fichiers à l'aide d'URL dans les requêtes multimodales. Pour l'inférence sur l'appareil, vous devez fournir une seule image au format Bitmap.

    • Si vous fournissez une URL de fichier à l'aide de fileData (FileDataPart), il peut revenir au modèle hébergé dans le cloud (le mode ONLY_ON_DEVICE génère une exception).
    • Si vous intégrez une URL directement dans un prompt textuel, le modèle hébergé dans le cloud n'est pas automatiquement utilisé (les URL intégrées sont ignorées par le modèle sur l'appareil).

  • Envoi de requêtes dépassant 4 000 jetons (soit environ 3 000 mots en anglais)

    • Peut basculer vers le modèle hébergé dans le cloud. Toutefois, le mode ONLY_ON_DEVICE génère une exception.

  • Chat multitour

    • Ne repasse pas automatiquement au modèle hébergé dans le cloud (l'inférence sur l'appareil concatène l'historique des prompts en un seul prompt textuel. Étant donné que le modèle sur l'appareil ne fait pas la distinction entre les rôles et considère l'historique comme un seul message, il ne sera pas aussi précis qu'un modèle hébergé dans le cloud).
    • Si vous souhaitez utiliser le chat multitours, nous vous recommandons d'utiliser le mode ONLY_IN_CLOUD.

  • Fournir au modèle des outils pour l'aider à générer sa réponse (comme l'appel de fonction, l'exécution de code, le contexte de l'URL, l'ancrage avec Google Search et l'ancrage avec Google Maps)

    • Ne bascule pas automatiquement vers le modèle hébergé dans le cloud. Si vous souhaitez utiliser des outils, nous vous recommandons d'utiliser le mode ONLY_IN_CLOUD.

La surveillance de l'IA dans la console Firebase n'affiche aucune donnée pour l'inférence sur l'appareil (y compris les journaux sur l'appareil). Toutefois, toute inférence utilisant un modèle hébergé dans le cloud peut être surveillée comme n'importe quelle autre inférence via Firebase AI Logic.

Autres limites

En plus de ce qui précède, l'inférence sur l'appareil présente les limites suivantes (pour en savoir plus, consultez la documentation ML Kit) :

  • L'utilisateur final de votre application doit utiliser un appareil compatible pour l'inférence sur l'appareil.

  • Votre application ne peut exécuter l'inférence sur l'appareil que lorsqu'elle est au premier plan.

  • Seuls l'anglais et le coréen ont été validés pour l'inférence sur l'appareil.

  • La limite de jetons pour l'ensemble de la requête d'inférence sur l'appareil est de 4 000 jetons. Si vos requêtes risquent de dépasser cette limite, veillez à configurer un mode d'inférence pouvant utiliser un modèle hébergé dans le cloud.

  • Nous vous recommandons d'éviter les cas d'utilisation de l'inférence sur l'appareil qui nécessitent une longue sortie (plus de 256 jetons).

  • AICore (un service système Android qui gère les modèles sur l'appareil) applique un quota d'inférence par application. Si vous effectuez trop de requêtes API en peu de temps, vous obtiendrez une réponse ErrorCode.BUSY. Si vous recevez cette erreur, envisagez d'utiliser un intervalle exponentiel entre les tentatives pour relancer la requête. ErrorCode.PER_APP_BATTERY_USE_QUOTA_EXCEEDED peut également être renvoyé si une application dépasse un quota de longue durée (par exemple, un quota quotidien).


Envoyer des commentaires sur votre expérience avec Firebase AI Logic