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

Les modèles Gemini renvoient des réponses sous forme de texte non structuré par défaut. Cependant, 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 des 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'interface utilisateur 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 d'étiquettes (par exemple, un ensemble spécifique d'énumérations comme positive et negative), plutôt qu'avec des étiquettes produites 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 une sortie structurée (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 une sortie structurée

La génération de sorties structurées (comme JSON et des é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 la responseConstraint que vous souhaitez que le modèle utilise.

Sortie JSON

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

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

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 à l'aide de JSON uniquement 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 d'énumération

L'exemple suivant adapte l' exemple général de sortie d'énumération pour prendre en compte l'inférence hybride (dans cet exemple, PREFER_ON_DEVICE) :

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

// ...