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

Vous pouvez créer des applications et des fonctionnalités Web 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 transparente vers des modèles hébergés dans le cloud dans le cas contraire (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 Web utilisant le SDK Firebase AI Logic v12.5.0 ou version ultérieure et s'exécutant sur Chrome pour ordinateur (version 139 ou ultérieure).

 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 plates-formes compatibles

Les sections suivantes décrivent les API, les plates-formes et les navigateurs compatibles.

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

  • L'inférence dans le cloud utilise le fournisseur Gemini API de votre choix (Gemini Developer API ou Agent Platform Gemini API (formerly Vertex AI)).

  • L'inférence sur l'appareil utilise l'API Prompt de Chrome.

Plates-formes et navigateurs compatibles

Pour l'inférence sur l'appareil (qui utilise l'API Prompt de Chrome), l'utilisateur final de votre application doit exécuter Chrome sur ordinateur (version 139 ou ultérieure). Pour en savoir plus, consultez la documentation Chrome.

Premiers pas sur localhost

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

Pour en savoir plus sur l'utilisation des API sur localhost, consultez la documentation Chrome.

Étape 1 : Configurez Chrome et l'API Prompt pour l'inférence sur l'appareil

  1. Assurez-vous d'utiliser une version récente de Chrome. Mettez à jour Chrome sur la page chrome://settings/help.
    L'inférence sur l'appareil est disponible à partir de Chrome v139.

  2. Activez le modèle multimodal sur l'appareil en définissant l'option suivante sur Activé :

    • chrome://flags/#prompt-api-for-gemini-nano-multimodal-input

  3. Redémarrez Chrome.

  4. (Facultatif) Téléchargez le modèle sur l'appareil avant la première requête.

    L'API Prompt est intégrée à Chrome, mais le modèle sur l'appareil n'est pas disponible par défaut. Si vous n'avez pas encore téléchargé le modèle avant votre première requête d'inférence sur l'appareil, la requête lancera automatiquement le téléchargement du modèle en arrière-plan.

Étape 2 : 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 3 : Ajoutez le SDK

La bibliothèque Firebase permet d'accéder aux API pour interagir avec les modèles génératifs. La bibliothèque est incluse dans le SDK JavaScript Firebase pour le Web.

  1. Installez le SDK JS Firebase pour le Web à l'aide de npm :

    npm install firebase

  2. Initialisez Firebase dans votre application :

    import { initializeApp } from "firebase/app";
import { initializeAppCheck } from "firebase/app-check";

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

Étape 4 : 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.

Voici comment utiliser le fournisseur de débogage lorsque vous exécutez votre application de manière interactive depuis localhost (par exemple, lors du développement local) :

  1. Dans votre version de débogage, activez le mode débogage en définissant self.FIREBASE_APPCHECK_DEBUG_TOKEN sur true avant d'initialiser App Check. Exemple :

    self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
initializeAppCheck(firebaseApp, { /* App Check options */ });

  2. Accédez à votre application Web localement et ouvrez les outils pour les développeurs du navigateur. Dans la console de débogage, un jeton de débogage s'affiche :

    AppCheck debug token: "123a4567-b89c-12d3-e456-789012345678".
You will need to safelist it in the Firebase console for it to work.

  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 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éer une instance GenerativeModel. Veillez à définir mode sur l'une des valeurs suivantes :

    • PREFER_ON_DEVICE : utilisez le modèle sur l'appareil s'il est disponible. Sinon, utilisez le modèle hébergé dans le cloud.

    • ONLY_ON_DEVICE : utilisez le modèle sur l'appareil s'il est disponible. Sinon, générez une exception.

    • PREFER_IN_CLOUD : utilisez le modèle hébergé dans le cloud s'il est disponible. Sinon, utilisez le modèle sur l'appareil.

    • ONLY_IN_CLOUD : utilisez le modèle hébergé dans le cloud s'il est disponible. Sinon, générez une exception.

import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend, InferenceMode } 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
// Set the mode (for example, use the on-device model if it's available)
const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_ON_DEVICE });

Étape 6 : Initialiser le modèle sur l'appareil

Vous devez appeler initializeDeviceModel() après ou pendant une interaction de l'utilisateur final avec la page (comme un clic sur un bouton) et avant d'envoyer une requête de prompt au modèle. Pour en savoir plus sur l'exigence d'activation par l'utilisateur, consultez la documentation Chrome.

import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend, InferenceMode } 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
// Set the mode (for example, use the on-device model if it's available)
const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_ON_DEVICE });

// `initializeDeviceModel` must be called:
// (1) after or on an end-user page interaction such as a button click
// and
// (2) before any queries to the model (such as `generateContent()`)
// You may want to `await` this promise if using `ONLY_ON_DEVICE` (see note below).
model.initializeDeviceModel((val) =>
  // Example: "Download progress: 72.62%""
  console.log(`Download progress: ${Math.round(val*10000) / 100}%`)
);

Étape 7 : 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 :

// Imports + initialization of FirebaseApp and backend service + creation of model instance

// Wrap in an async function so you can use await
async function run() {
  // Provide a prompt that contains text
  const prompt = "Write a story about a magic backpack."

  // To generate text output, call `generateContent` with the text input
  const result = await model.generateContent(prompt);

  const response = result.response;
  const text = response.text();
  console.log(text);
}

run();

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'un prompt contenant des fichiers texte et image, en fournissant le mimeType de chaque fichier d'entrée et le fichier lui-même.

Les types d'images d'entrée compatibles avec l'inférence sur l'appareil sont PNG et JPEG.

// Imports + initialization of FirebaseApp and backend service + creation of model instance

// Converts a File object to a Part object.
async function fileToGenerativePart(file) {
  const base64EncodedDataPromise = new Promise((resolve) => {
    const reader = new FileReader();
    reader.onloadend = () => resolve(reader.result.split(',')[1]);
    reader.readAsDataURL(file);
  });
  return {
    type: "inlineData",
    inlineData: { data: await base64EncodedDataPromise, mimeType: file.type },
  };
}

async function run() {
  // Provide a text prompt to include with the image
  const prompt = "Write a poem about this picture:";

  const fileInputEl = document.querySelector("input[type=file]");
  const imagePart = await fileToGenerativePart(fileInputEl.files[0]);

  // To generate text output, call `generateContent` with the text and image
  const result = await model.generateContent([prompt, imagePart]);

  const response = result.response;
  const text = response.text();
  console.log(text);
}

run();

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

Les fonctionnalités du SDK Web ou des modèles hébergés dans le cloud ne sont pas toutes 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érer des images à l'aide des modèles Gemini Nano Banana

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

  • Générer du texte à partir de types d'entrées de fichiers image autres que JPEG et PNG

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

  • Générer du texte à partir d'entrées multimodales de contenus audio, de vidéos et de documents (PDF)

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

  • Fournir des fichiers à l'aide d'URL dans des requêtes multimodales. Vous devez fournir les fichiers en tant que données intégrées aux modèles sur l'appareil.

  • Chat multitour

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

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

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

  • L'utilisateur final de votre application doit exécuter Chrome sur ordinateur (version 139 ou ultérieure) avec les flags requis activés.

  • Le modèle sur l'appareil nécessite un espace de stockage suffisant sur l'appareil de l'utilisateur pour le téléchargement initial du modèle.


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