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

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 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 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 d'utilisation :

• 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'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 Android.

arrow_downward Accéder à la sortie JSON arrow_downward Accéder à la sortie enum

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 sur l'appareil et hébergée dans le cloud.

Pour générer une sortie structurée, transmettez votre schéma directement à generateObject(). Les exigences liées au 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 compatibles.
  • 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 est redirigée 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 dans le cloud uniquement (ONLY_IN_CLOUD) :

  • Compatible avec les annotations @Generable (recommandées) 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 votre fichier Gradle au niveau du module (application) (comme <project>/<app-module>/build.gradle.kts), ajoutez le plug-in KSP, le plug-in Kotlin Serialization 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:17.17.0")
      implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta05")
      implementation("com.google.firebase:firebase-appcheck-debug:19.4.1")
   
      // Add the Firebase AI KSP processor for schema generation.
      ksp("com.google.firebase:firebase-ai-ksp-processor:16.0.2")
   
      // (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 enum

Sortie JSON

Les exemples suivants adaptent l'exemple général de sortie JSON pour tenir compte de 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 des principaux arguments de vente (@Generable et @Guide)

  • Compatible avec tous les modes d'inférence et obligatoire pour l'inférence sur l'appareil et hybride (plus précisément, 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

  • Uniquement compatible avec l'inférence basée dans le cloud (plus précisément, ONLY_IN_CLOUD).
  • Construisez manuellement un JsonSchema dans le code sans utiliser le processeur KSP, et lisez la chaîne JSON brute à partir de response.response.text.

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

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

Cette approche est compatible avec tous les modes d'inférence et est requise pour les expériences sur l'appareil et hybrides (plus précisément, 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 basée sur le cloud (plus précisément, 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 enum

Les exemples suivants adaptent l'exemple général de sortie enum pour tenir compte de 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 de KSP (@Generable)

  • Compatible avec tous les modes d'inférence et obligatoire pour l'inférence sur l'appareil et hybride (plus précisément, ONLY_ON_DEVICE, PREFER_ON_DEVICE et PREFER_IN_CLOUD).
  • Définissez un enum enveloppé 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

  • Uniquement compatible avec l'inférence basée dans le cloud (plus précisément, ONLY_IN_CLOUD).
  • Créez manuellement un enum 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 obligatoire pour les expériences sur l'appareil et hybrides (plus précisément, 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 basée sur le cloud (plus précisément, 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