Générer des résultats structurés pour les expériences hybrides dans les applications Web

Par défaut, les modèles Gemini renvoient des réponses sous forme de texte non structuré. Toutefois, certains cas d'utilisation nécessitent du texte structuré, comme JSON. Par exemple, vous pouvez utiliser la réponse pour d'autres tâches en aval qui nécessitent un schéma de données établi.

Pour vous assurer que la sortie générée du modèle respecte toujours un schéma spécifique, vous pouvez définir un schéma, qui fonctionne comme un plan pour les réponses du modèle. Vous pouvez ensuite extraire directement les données de la sortie du modèle avec moins de post-traitement.

Voici quelques exemples :

  • Assurez-vous que la réponse d'un modèle produit du code JSON valide et qu'elle est conforme au schéma que vous avez fourni.
    Par exemple, le modèle peut générer des entrées structurées pour les recettes qui incluent toujours le nom de la recette, la liste des ingrédients et les étapes. Vous pouvez ensuite analyser et afficher plus facilement ces informations dans l'UI de votre application.

  • Limitez la façon dont un modèle peut répondre lors des tâches de classification.
    Par exemple, vous pouvez demander au modèle d'annoter du texte avec un ensemble spécifique de libellés (par exemple, un ensemble spécifique d'énums comme positive et negative), plutôt qu'avec des libellés produits par le modèle (qui peuvent présenter un certain degré de variabilité, comme good, positive, negative ou bad).

Cette page explique comment générer des sorties structurées (comme JSON et des énumérations) dans vos expériences hybrides pour les applications Web.

Avant de commencer

Assurez-vous d'avoir suivi le guide de démarrage pour créer des expériences hybrides.

Définir la configuration pour la sortie structurée

La génération de sorties structurées (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é (par 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

Les exemples suivants adaptent l'exemple général de sortie JSON pour tenir compte de l'inférence hybride (dans cet exemple, PREFER_ON_DEVICE) :

Exemple 1 : Utiliser les méthodes d'assistance Firebase Schema

Cet exemple utilise des méthodes d'assistance fournies par le SDK Firebase AI Logic pour rendre la définition du schéma plus compacte.

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

// This schema can also be defined as a plain JSON object.
// See next snippet for an example of a plain JSON schema.
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.PREFER_ON_DEVICE,
  inCloudParams: {
    generationConfig: {
      model: "gemini-3.1-flash-lite",
      responseMimeType: "application/json",
      responseSchema: jsonSchema
    },
  }
  onDeviceParams: {
    promptOptions: {
      responseConstraint: jsonSchema
    }
  }
});

const result = await model
  .generateContent(
    "Create profiles for some characters for a fantasy story.");

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

// ...

Exemple 2 : Utiliser un schéma JSON simple

Cet exemple définit le schéma en utilisant uniquement JSON et renvoie les mêmes résultats.

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

// The JSON schema defined as a plain JSON object.
const jsonSchema = {
    "type": "object",
    "properties": {
        "characters": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string",
                        "nullable": false
                    },
                    "accessory": {
                        "type": "string",
                        "nullable": false
                    },
                    "age": {
                        "type": "number",
                        "nullable": false
                    },
                    "species": {
                        "type": "string",
                        "nullable": false
                    }
                },
                "nullable": false,
                "required": [
                    "name",
                    "age",
                    "species"
                ]
            },
            "nullable": false
        }
    },
    "nullable": false,
    "required": [
        "characters"
    ]
};

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

const result = await model
  .generateContent(
    "Create profiles for some characters for a fantasy story.");

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

Sortie enum

L'exemple suivant adapte l'exemple de sortie enum générale pour tenir compte de l'inférence hybride (PREFER_ON_DEVICE dans cet exemple) :

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

// enumSchema can also be defined as a plain JSON schema instead of
// using the `Schema` helper methods, just as in the JSON output example.
const enumSchema = Schema.enumString({
  enum: ["drama", "comedy", "documentary"],
});

const model = getGenerativeModel(ai, {
  mode: InferenceMode.PREFER_ON_DEVICE,
  inCloudParams: {
    generationConfig: {
      responseMimeType: "text/x.enum",
      responseSchema: enumSchema
    },
  }
  onDeviceParams: {
    promptOptions: {
      responseConstraint: enumSchema
    }
  }
});

// ...