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 basculer de manière fluide vers des modèles hébergés dans le cloud si ce n'est pas le cas (et inversement).

Cette page explique comment faire vos premiers pas avec le SDK client. Une fois cette configuration standard terminée, découvrez les 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. Il est régi 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.

 Accéder aux exemples de code

Cas d'utilisation et fonctionnalités compatibles

En fonction des cas d'utilisation de votre application, vous pouvez profiter de plusieurs avantages des expériences sur l'appareil ou hybrides :

  • Avantages de l'utilisation d'un modèle sur l'appareil pour l'inférence :

    • Confidentialité renforcée
    • Contexte local
    • Inférence sans frais
    • Fonctionnalités hors connexion
  • Avantages d'une approche hybride :

    • Offrir une expérience similaire dans l'application, quel que soit l'appareil de l'utilisateur final
    • Améliorer la disponibilité des fonctionnalités d'IA générative, indépendamment de la connectivité Internet, des limites de quota ou des capacités de l'appareil

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

L'inférence sur l'appareil n'est compatible qu'avec la génération de texte à un seul tour (pas de chat) (avec sortie en streaming ou non), en particulier les fonctionnalités suivantes :

Assurez-vous de consulter la liste des fonctionnalités non encore compatibles avec l'inférence hybride ou sur l'appareil au bas de cette page.

API et appareils compatibles

Les sections suivantes décrivent les API compatibles, ainsi que les appareils compatibles (et leurs modèles sur l'appareil).

API compatibles pour l'inférence dans le cloud ou sur l'appareil

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 la liste des appareils compatibles et de leurs modèles sur l'appareil dans la documentation de ML Kit.

Commencer

Ces étapes de démarrage décrivent la configuration générale requise pour toute requête 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 > AI Logic.

  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 l'exigence de facturation associée) ultérieurement.

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

    Cette étape du workflow applique 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.1.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta07")
  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.1.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta07")
  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

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 à l'onglet Sécurité > App Check > 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 de code 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 au téléchargement du 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 les 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, la mise à jour du modèle, 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 indiquera 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 uniquement pour Kotlin). 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 au 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 que vous avez choisi.

  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, bascule vers le 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 :

Si vous souhaitez générer une sortie structurée (comme JSON ou des énumérations), utilisez l'un des exemples "générer du texte" suivants et configurez le modèle pour qu'il réponde selon un schéma fourni.

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

Avant d'essayer cet exemple, assurez-vous d'avoir suivi les étapes de 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 suivi les étapes de la section Premiers pas de ce guide.

Vous pouvez utiliser generateContent() pour générer du texte à partir d'une requête 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 est également compatible avec 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 compatibles

Comme il s'agit d'une version expérimentale, toutes les fonctionnalités des modèles hébergés dans le cloud ou du SDK Firebase AI Logic ne sont pas disponibles pour l'inférence hybride ou sur l'appareil.

Fonctionnalités non encore compatibles avec les implémentations hybrides

Les fonctionnalités suivantes ne peuvent pas être utilisées avec les implémentations hybrides (ni sur l'appareil, ni via le remplacement dans le cloud) :

  • Gemini Live API : le streaming bidirectionnel en temps réel n'est pas accepté.

  • Modèles de prompts côté serveur : les modèles de prompts côté serveur gérés ne sont pas compatibles.

  • Compter les jetons : ne vous fiez pas au nombre de jetons, car il diffère entre les modèles hébergés dans le cloud et les modèles sur l'appareil. Il n'existe donc pas de solution de remplacement intuitive.

Fonctionnalités non encore compatibles avec l'inférence sur l'appareil

Les fonctionnalités suivantes ne sont pas encore compatibles avec l'inférence sur l'appareil, mais elles sont disponibles pour les modèles hébergés 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ère 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 revenir au 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'un fichier d'entrée contenant uniquement une image. Pour l'inférence sur l'appareil, vous devez fournir du texte dans la requête multimodale.

    • Peut revenir au 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ère une exception.
  • Générer du texte à partir d'entrées multimodales de contenus audio, de vidéos et de documents (PDF)

    • Peut revenir au modèle hébergé dans le cloud. Toutefois, le mode ONLY_ON_DEVICE génère une exception.
  • Fournir des fichiers à l'aide d'URL dans des 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, elle ne bascule pas automatiquement vers le modèle hébergé dans le cloud (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 revenir au modèle hébergé dans le cloud. Toutefois, le mode ONLY_ON_DEVICE génère une exception.
  • Chat multitour

    • Ne bascule pas automatiquement vers le modèle hébergé dans le cloud (l'inférence sur l'appareil concatène l'historique des prompts en un seul prompt textuel ; comme le modèle sur l'appareil ne distingue pas les rôles et voit 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 multitour, 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 de 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 maximale 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 d'inférence sur l'appareil qui nécessitent une sortie longue (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. De plus, ErrorCode.PER_APP_BATTERY_USE_QUOTA_EXCEEDED peut ê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