Générer des sorties structurées pour les expériences hybrides dans les applications Android

Les modèles Gemini renvoient par défaut des réponses sous forme de texte non structuré. Cependant, certains cas d'utilisation nécessitent du texte structuré (comme JSON ou des énumérations). 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 par le modèle respecte toujours un schéma spécifique, vous pouvez définir un schéma, qui fonctionne comme un modèle 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 d'utilisation :

• S'assurer 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.

• Limiter 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 telles que positive et negative), plutôt qu'avec des étiquettes produites par le modèle (qui pourraient 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 Android.

arrow_downward Accéder à la sortie JSON arrow_downward Accéder à la sortie d'énumération

Configuration de la sortie structurée

La génération de sorties structurées (comme JSON et les énumérations) est compatible avec l'inférence sur l'appareil et l'inférence hébergée dans le cloud.

Pour générer une sortie structurée, transmettez votre schéma directement à generateObject(). Les exigences de schéma dépendent du mode d'inférence configuré :

• Pour l'inférence sur l'appareil et hybride (ONLY_ON_DEVICE, PREFER_ON_DEVICE et PREFER_IN_CLOUD) :

  • Nécessite l'utilisation de l'annotation @Generable sur un data class Kotlin avec le processeur KSP. Les schémas manuels et les annotations enum class directes ne sont pas acceptés.
  • Lorsque l'inférence s'exécute sur l'appareil, le SDK traduit automatiquement le schéma en contraintes pour le modèle sur l'appareil (à l'aide de l'API ML Kit Prompt).
  • Si une requête hybride bascule vers l'inférence cloud, le SDK définit automatiquement responseMimeType sur application/json et transmet le schéma au modèle Gemini hébergé dans le cloud.

• Pour l'inférence cloud uniquement (ONLY_IN_CLOUD) :

  • Compatible avec les annotations @Generable (recommandé) et les schémas manuels (créés à l'aide des méthodes d'assistance JsonSchema).
  • Le SDK définit automatiquement responseMimeType sur application/json et transmet le schéma au modèle Gemini hébergé dans le cloud.

Avant de commencer

Avant de générer une sortie structurée, assurez-vous d'avoir effectué la configuration suivante :

1. Suivez le guide de démarrage pour créer des expériences hybrides, qui explique comment configurer votre projet Firebase, télécharger le modèle sur l'appareil et configurer App Check.

2. Configurez le plug-in Kotlin Symbol Processing (KSP) et ajoutez la dépendance Firebase AI KSP à votre application.

   Dans le fichier Gradle de votre module (au niveau de l'application) (par exemple, <project>/<app-module>/build.gradle.kts), ajoutez le plug-in KSP, le plug-in de sérialisation Kotlin et les dépendances requises :

   plugins {
      // ... other plugins
      id("com.google.gms.google-services")
      id("com.google.devtools.ksp") version "LATEST_VERSION"
      id("org.jetbrains.kotlin.plugin.serialization") version "LATEST_VERSION"
   }
   
   dependencies {
      // ... other androidx dependencies
   
      // Add the dependencies for the Firebase AI Logic and App Check libraries.
      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")
   
      // Add the Firebase AI KSP processor for schema generation.
      ksp("com.google.firebase:firebase-ai-ksp-processor:17.0.0")
   
      // (Optional) Add kotlinx.serialization JSON library for object decoding.
      implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:LATEST_VERSION")
   }

arrow_downward Accéder à la sortie JSON arrow_downward Accéder à la sortie d'énumération

Sortie JSON

Les exemples suivants adaptent l'exemple de sortie JSON général pour prendre en charge l'inférence hybride (par exemple, PREFER_ON_DEVICE).

Dans le scénario de ces exemples, le modèle génère une liste de profils de personnages pour une histoire fantastique, avec des attributs structurés tels que le nom, l'âge, l'espèce et les accessoires facultatifs.

Vous pouvez définir vos schémas de réponse à l'aide de l'une des approches suivantes :

• Annotations KSP (@Generable et @Guide)

  • Compatible avec tous les modes d'inférence et obligatoire pour l'inférence sur l'appareil et l'inférence hybride (en particulier, ONLY_ON_DEVICE, PREFER_ON_DEVICE et PREFER_IN_CLOUD).
  • Définissez des classes de données Kotlin pour générer automatiquement des schémas au temps de compilation et désérialiser les réponses directement dans des objets fortement typés à l'aide de getObject().

• Méthodes d'assistance JsonSchema manuelles

  • Compatible uniquement avec l'inférence dans le cloud (en particulier, ONLY_IN_CLOUD).
  • Créez manuellement un JsonSchema dans le code sans utiliser le processeur KSP, puis lisez la chaîne JSON brute à partir de response.response.text.

Exemple 1 : Utiliser les annotations @Generable et @Guide avec KSP

Définissez une data class Kotlin annotée avec @Serializable et @Generable. Utilisez des annotations @Guide sur les propriétés pour fournir au modèle des descriptions, des limites de valeur ou des contraintes d'élément.

Cette approche est compatible avec tous les modes d'inférence et est requise pour les expériences sur l'appareil et hybrides (en particulier, ONLY_ON_DEVICE, PREFER_ON_DEVICE et PREFER_IN_CLOUD).

import com.google.firebase.Firebase
import com.google.firebase.ai.type.GenerativeBackend
import com.google.firebase.ai.InferenceMode
import com.google.firebase.ai.OnDeviceConfig
import com.google.firebase.ai.annotations.Generable
import com.google.firebase.ai.annotations.Guide
import com.google.firebase.ai.ai
import kotlinx.serialization.Serializable

// Define data classes representing the schema, annotated with @Serializable and @Generable.
// You can provide descriptions on @Generable and @Guide to guide the model's output.
@Serializable
@Generable(description = "A character profile for a fantasy story")
data class Character(
    val name: String,
    val age: Int,
    val species: String,
    // Use @Guide to add property descriptions, value bounds (minimum/maximum), or formats.
    // Properties with default values or nullable types are treated as optional in the schema.
    @Guide(description = "An accessory the character wears or carries")
    val accessory: String? = null
) {
    // An empty companion object is required for KSP to generate the firebaseAISchema() extension.
    companion object
}

@Serializable
@Generable(description = "A list of character profiles")
data class CharacterList(
    // Use minItems or maxItems to specify collection size bounds for the model.
    @Guide(description = "List of characters", minItems = 1)
    val characters: List<Character>
) {
    // An empty companion object is required for KSP to generate the firebaseAISchema() extension.
    companion object
}

// Initialize the Gemini Developer API backend service.
// Create a GenerativeModel instance configured for hybrid inference (like PREFER_ON_DEVICE).
val model = Firebase.ai(backend = GenerativeBackend.googleAI())
    .generativeModel(
        modelName = "CLOUD_MODEL_NAME",
        onDeviceConfig = OnDeviceConfig(mode = InferenceMode.INFERENCE_MODE)
    )

// Obtain the schema generated by KSP via the firebaseAISchema() extension.
val schema = CharacterList.firebaseAISchema()
val prompt = "Create profiles for some characters for a fantasy story."

// Generate the structured object (the SDK applies the schema to on-device or cloud models).
val response = model.generateObject(schema, prompt)

// Access the strongly-typed deserialized object directly via getObject().
val characterList: CharacterList? = response.getObject()
characterList?.characters?.forEach { character ->
    println("Name: ${character.name}, Species: ${character.species}, Age: ${character.age}")
    println("Accessory: ${character.accessory ?: "None"}")
}

Exemple 2 : Utiliser des méthodes d'assistance JsonSchema manuelles

Si votre application utilise uniquement l'inférence dans le cloud (en particulier, ONLY_IN_CLOUD), vous pouvez créer manuellement un JsonSchema à l'aide des méthodes d'assistance fournies par le SDK Firebase AI Logic.

import com.google.firebase.Firebase
import com.google.firebase.ai.type.GenerativeBackend
import com.google.firebase.ai.InferenceMode
import com.google.firebase.ai.OnDeviceConfig
import com.google.firebase.ai.ai
import com.google.firebase.ai.type.JsonSchema

// Define the schema manually using JsonSchema helper methods.
// Properties are required by default unless specified in optionalProperties.
val jsonSchema = JsonSchema.obj(
    properties = mapOf(
        "characters" to JsonSchema.array(
            items = JsonSchema.obj(
                properties = mapOf(
                    "name" to JsonSchema.string(),
                    "accessory" to JsonSchema.string(),
                    "age" to JsonSchema.integer(),
                    "species" to JsonSchema.string()
                ),
                optionalProperties = listOf("accessory")
            )
        )
    )
)

// Initialize the Gemini Developer API backend service.
// Manual schemas are only supported for cloud-based inference (specifically, ONLY_IN_CLOUD).
val model = Firebase.ai(backend = GenerativeBackend.googleAI())
    .generativeModel(
        modelName = "CLOUD_MODEL_NAME",
        onDeviceConfig = OnDeviceConfig(mode = InferenceMode.ONLY_IN_CLOUD)
    )

// Call generateObject() with the manual schema and prompt.
val response = model.generateObject(
    jsonSchema,
    "Create profiles for some characters for a fantasy story."
)

// Access the generated JSON string conforming to the schema from response.response.text.
println(response.response.text)

Sortie d'énumération

Les exemples suivants adaptent l'exemple de sortie d'énumération générale pour prendre en compte l'inférence hybride (par exemple, PREFER_ON_DEVICE).

Dans le scénario de ces exemples, le modèle classe une description de film en sélectionnant un seul genre dans une liste prédéfinie d'options autorisées (drama, comedy ou documentary).

Vous pouvez définir vos schémas de réponse à l'aide de l'une des approches suivantes :

• Annotations KSP (@Generable)

  • Compatible avec tous les modes d'inférence et obligatoire pour l'inférence sur l'appareil et l'inférence hybride (en particulier, ONLY_ON_DEVICE, PREFER_ON_DEVICE et PREFER_IN_CLOUD).
  • Définissez une énumération encapsulée dans un data class Kotlin pour générer automatiquement le schéma et désérialiser les réponses directement dans des objets fortement typés à l'aide de getObject().

• Méthodes d'assistance JsonSchema manuelles

  • Compatible uniquement avec l'inférence dans le cloud (en particulier, ONLY_IN_CLOUD).
  • Créez manuellement une énumération JsonSchema à l'aide de JsonSchema.enumeration() sans utiliser le processeur KSP, puis lisez la chaîne sélectionnée à partir de response.response.text.

Exemple 1 : Utiliser des annotations @Generable avec KSP

Définissez un enum class représentant les valeurs autorisées, puis encapsulez-le en tant que propriété dans un data class Kotlin annoté avec @Serializable et @Generable.

Cette approche est compatible avec tous les modes d'inférence et est requise pour les expériences sur l'appareil et hybrides (en particulier, ONLY_ON_DEVICE, PREFER_ON_DEVICE et PREFER_IN_CLOUD).

import com.google.firebase.Firebase
import com.google.firebase.ai.type.GenerativeBackend
import com.google.firebase.ai.InferenceMode
import com.google.firebase.ai.OnDeviceConfig
import com.google.firebase.ai.annotations.Generable
import com.google.firebase.ai.annotations.Guide
import com.google.firebase.ai.ai
import kotlinx.serialization.Serializable

// Define an enum class representing the allowed options.
@Serializable
enum class FilmGenre {
    DRAMA,
    COMEDY,
    DOCUMENTARY
}

// Wrap the enum in a data class annotated with @Serializable and @Generable.
// On-device inference requires an @Generable data class.
// Direct enum annotations are not supported on-device.
@Serializable
@Generable(description = "The classification result for the film")
data class FilmClassification(
    @Guide(description = "The genre of the film")
    val genre: FilmGenre
) {
    // An empty companion object is required for KSP to generate the firebaseAISchema() extension.
    companion object
}

// Initialize the Gemini Developer API backend service.
// Create a GenerativeModel instance configured for hybrid inference (like PREFER_ON_DEVICE).
val model = Firebase.ai(backend = GenerativeBackend.googleAI())
    .generativeModel(
        modelName = "CLOUD_MODEL_NAME",
        onDeviceConfig = OnDeviceConfig(mode = InferenceMode.INFERENCE_MODE)
    )

// Obtain the schema generated by KSP via the firebaseAISchema() extension.
val schema = FilmClassification.firebaseAISchema()
val prompt = """
    The film aims to educate and inform viewers about real-life subjects, events, or people.
    It offers a factual record of a particular topic by combining interviews, historical footage,
    and narration. The primary purpose of a film is to present information and provide insights
    into various aspects of reality.
    """

// Generate the structured object (the SDK applies the schema to on-device or cloud models).
val response = model.generateObject(schema, prompt)

// Access the strongly-typed deserialized object and enum value directly via getObject().
val classification: FilmClassification? = response.getObject()
val genre: FilmGenre? = classification?.genre
println("Selected genre: $genre")

Exemple 2 : Utiliser des méthodes d'assistance JsonSchema manuelles

Si votre application utilise uniquement l'inférence dans le cloud (en particulier, ONLY_IN_CLOUD), vous pouvez créer manuellement une énumération JsonSchema à l'aide des méthodes d'assistance fournies par le SDK Firebase AI Logic.

import com.google.firebase.Firebase
import com.google.firebase.ai.type.GenerativeBackend
import com.google.firebase.ai.InferenceMode
import com.google.firebase.ai.OnDeviceConfig
import com.google.firebase.ai.ai
import com.google.firebase.ai.type.JsonSchema

// Define an enum schema with allowed string values and a description.
val enumSchema = JsonSchema.enumeration(
    values = listOf("drama", "comedy", "documentary"),
    description = "The genre of the film"
)

// Initialize the Gemini Developer API backend service.
// Manual schemas are only supported for cloud-based inference (specifically, ONLY_IN_CLOUD).
val model = Firebase.ai(backend = GenerativeBackend.googleAI())
    .generativeModel(
        modelName = "CLOUD_MODEL_NAME",
        onDeviceConfig = OnDeviceConfig(mode = InferenceMode.ONLY_IN_CLOUD)
    )

val prompt = """
    The film aims to educate and inform viewers about real-life subjects, events, or people.
    It offers a factual record of a particular topic by combining interviews, historical footage,
    and narration. The primary purpose of a film is to present information and provide insights
    into various aspects of reality.
    """

// Call generateObject() with the enum schema and prompt.
val response = model.generateObject(enumSchema, prompt)

// Access the selected enum value string from response.response.text.
println(response.response.text)

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