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


Créez 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 revenir de manière transparente aux modèles hébergés dans le cloud dans le cas contraire (et inversement).

Cette page explique comment démarrer avec le SDK client et présente d'autres options et fonctionnalités de configuration, comme la sortie structurée.

Notez que l'inférence sur l'appareil est compatible avec les applications Web exécutées sur Chrome pour ordinateur.

Accéder aux exemples de code

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

  • Voici les avantages de l'utilisation des fonctionnalités hybrides :

    • Touchez 100 % de votre audience, quelle que soit la disponibilité des modèles sur l'appareil ou la connectivité Internet.

Fonctionnalités et caractéristiques compatibles pour l'inférence sur l'appareil :

Avant de commencer

Veuillez noter les points suivants :

Premiers pas sur localhost

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

É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. Mise à jour dans chrome://settings/help.
    L'inférence sur l'appareil est disponible à partir de Chrome 139.

  2. Activez le modèle multimodal sur l'appareil en définissant le flag suivant sur Enabled :

    • 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 à la page Firebase AI Logic.

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

  4. Configurez votre projet pour utiliser un fournisseur "Gemini API".

    Nous vous recommandons de commencer par utiliser Gemini Developer API. À tout moment, vous pouvez configurer Vertex AI Gemini API (et ses exigences de facturation).

    Pour Gemini Developer API, la console activera les API requises et créera une clé API Gemini dans votre projet.
    N'ajoutez pas cette clé API Gemini dans le code de votre application. En savoir plus

  5. Si vous y êtes invité dans le workflow de la console, suivez les instructions à l'écran pour enregistrer votre application et l'associer à Firebase.

  6. Passez à l'étape suivante de ce guide pour ajouter le SDK à votre application.

Étape 3 : Ajouter 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 Firebase JavaScript 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";

// 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 : 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éer une instance GenerativeModel. Assurez-vous de procéder comme suit :

    1. Appelez getGenerativeModel après ou lors d'une interaction de l'utilisateur final (comme un clic sur un bouton). Il s'agit d'un prérequis pour inferenceMode.

    2. Définissez 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, revenez au 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
// Call `getGenerativeModel` after or on an end-user interaction
// Set the mode (for example, use the on-device model if it's available)
const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_ON_DEVICE });

Étape 5 : 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 de "génération de texte" suivants et configurez le modèle pour qu'il réponde en fonction d'un schéma fourni.

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'une requête textuelle :

// 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 accepte également 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'une requête 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 acceptés pour 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 {
    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 accepte également le streaming des réponses textuelles à l'aide de generateContentStream (au lieu de generateContent).

Permettre aux utilisateurs finaux d'essayer votre fonctionnalité

Pour que les utilisateurs finaux puissent tester votre fonctionnalité dans votre application, vous devez vous inscrire aux versions d'essai Chrome Origin. Notez que la durée et l'utilisation de ces versions d'essai sont limitées.

  1. Inscrivez-vous à la phase d'évaluation de l'origine Chrome pour l'API Prompt. Vous recevrez un jeton.

  2. Indiquez le jeton sur chaque page Web pour laquelle vous souhaitez activer la fonctionnalité bêta. Utilisez l'une des options suivantes :

    • Fournissez le jeton en tant que balise Meta dans la balise <head> : <meta http-equiv="origin-trial" content="TOKEN">

    • Fournissez le jeton en tant qu'en-tête HTTP : Origin-Trial: TOKEN

    • Fournissez le jeton de manière programmatique.

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

Dans cette section, vous allez apprendre à définir un mode d'inférence, à remplacer le modèle de secours hébergé dans le cloud par défaut et à utiliser la configuration du modèle pour contrôler les réponses (par exemple, générer une sortie structurée).

Définir un mode d'inférence

Les exemples de configuration générale utilisent le mode PREFER_ON_DEVICE, mais il ne s'agit que de l'un des quatre modes d'inférence disponibles.

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

    const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_ON_DEVICE });

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

    const model = getGenerativeModel(ai, { mode: InferenceMode.ONLY_ON_DEVICE });

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

    const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_IN_CLOUD });

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

    const model = getGenerativeModel(ai, { mode: InferenceMode.ONLY_IN_CLOUD });

Déterminer si l'inférence sur l'appareil ou dans le cloud a été utilisée

Si vous utilisez les modes d'inférence PREFER_ON_DEVICE ou PREFER_IN_CLOUD, il peut être utile de savoir quel mode a été utilisé pour les requêtes données. Ces informations sont fournies par la propriété inferenceSource de chaque réponse (disponible à partir du SDK JS v12.5.0).

Lorsque vous accédez à cette propriété, la valeur renvoyée est ON_DEVICE ou IN_CLOUD.

// ...

console.log('You used: ' + result.response.inferenceSource);

console.log(result.response.text());

Remplacer le modèle de remplacement par défaut

Le modèle hébergé dans le cloud par défaut est gemini-2.5-flash-lite (à partir du SDK JS version 12.8.0).

Il s'agit du modèle hébergé sur le cloud de secours lorsque vous utilisez le mode PREFER_ON_DEVICE. Il s'agit également du modèle par défaut lorsque vous utilisez le mode ONLY_IN_CLOUD ou le mode PREFER_IN_CLOUD.

Vous pouvez utiliser l'option de configuration inCloudParams pour spécifier un autre modèle hébergé dans le cloud par défaut.

const model = getGenerativeModel(ai, {
  mode: InferenceMode.INFERENCE_MODE,
  inCloudParams: {
    model: "GEMINI_MODEL_NAME"
  }
});

Trouvez les noms de modèles pour tous les modèles Gemini compatibles.

Utiliser la configuration du modèle pour contrôler les réponses

Dans chaque requête envoyée à un modèle, vous pouvez inclure une configuration de modèle pour contrôler la manière dont le modèle génère une réponse. Les modèles hébergés dans le cloud et les modèles sur l'appareil offrent différentes options de configuration.

La configuration est conservée pendant toute la durée de vie de l'instance. Si vous souhaitez utiliser une autre configuration, créez une instance GenerativeModel avec cette configuration.

Définir la configuration d'un modèle hébergé dans le cloud

Utilisez l'option inCloudParams pour configurer un modèle Gemini hébergé dans le cloud. En savoir plus sur les paramètres disponibles

const model = getGenerativeModel(ai, {
  mode: InferenceMode.INFERENCE_MODE,
  inCloudParams: {
    model: "GEMINI_MODEL_NAME"
    temperature: 0.8,
    topK: 10
  }
});

Définir la configuration d'un modèle sur l'appareil

Notez que l'inférence à l'aide d'un modèle sur l'appareil utilise l'API Prompt de Chrome.

Utilisez l'option onDeviceParams pour configurer un modèle sur l'appareil. En savoir plus sur les paramètres disponibles

const model = getGenerativeModel(ai, {
  mode: InferenceMode.INFERENCE_MODE,
  onDeviceParams: {
    createOptions: {
      temperature: 0.8,
      topK: 8
    }
  }
});

Définir la configuration pour la sortie structurée (comme JSON)

La génération de résultats structurés (comme JSON et les énumérations) est compatible avec l'inférence à l'aide de modèles hébergés dans le cloud et sur l'appareil.

Pour l'inférence hybride, utilisez inCloudParams et onDeviceParams pour configurer le modèle afin qu'il réponde avec une sortie structurée. Pour les autres modes, n'utilisez que la configuration applicable.

  • Pour inCloudParams : spécifiez le responseMimeType approprié (dans cet exemple, application/json) ainsi que le responseSchema que vous souhaitez que le modèle utilise.

  • Pour onDeviceParams : spécifiez le responseConstraint que vous souhaitez que le modèle utilise.

Sortie JSON

L'exemple suivant adapte l'exemple général de sortie JSON pour l'inférence hybride :

import {
  getAI,
  getGenerativeModel,
  Schema
} from "firebase/ai";

const jsonSchema = Schema.object({
 properties: {
    characters: Schema.array({
      items: Schema.object({
        properties: {
          name: Schema.string(),
          accessory: Schema.string(),
          age: Schema.number(),
          species: Schema.string(),
        },
        optionalProperties: ["accessory"],
      }),
    }),
  }
});

const model = getGenerativeModel(ai, {
  mode: InferenceMode.INFERENCE_MODE,
  inCloudParams: {
    model: "gemini-2.5-flash"
    generationConfig: {
      responseMimeType: "application/json",
      responseSchema: jsonSchema
    },
  }
  onDeviceParams: {
    promptOptions: {
      responseConstraint: jsonSchema
    }
  }
});
Sortie enum

Comme ci-dessus, mais en adaptant la documentation sur la sortie enum pour l'inférence hybride :

// ...

const enumSchema = Schema.enumString({
  enum: ["drama", "comedy", "documentary"],
});

const model = getGenerativeModel(ai, {

// ...

    generationConfig: {
      responseMimeType: "text/x.enum",
      responseSchema: enumSchema
    },

// ...
});

// ...

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 du SDK Web ne sont pas disponibles pour 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 généralement disponibles pour l'inférence basée sur le cloud).

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

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

  • 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 erreur.

  • Générer des images à l'aide des modèles Gemini ou Imagen

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

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

  • Chat multitour

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

  • Streaming bidirectionnel avec Gemini Live API

  • 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 d'URL et l'ancrage avec la recherche Google)

  • Compter les jetons

    • Génère toujours une erreur. Le nombre de mots sera différent entre les modèles hébergés dans le cloud et ceux sur l'appareil. Il n'y a donc pas de solution de repli intuitive.

  • Surveillance de l'IA dans la console Firebase pour l'inférence sur l'appareil.

    • Notez que toute inférence utilisant les modèles hébergés dans le cloud peut être surveillée comme toute autre inférence utilisant le SDK client Firebase AI Logic pour le Web.


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