Générer une sortie structurée

Si vous devez analyser les réponses de Gemini Nano dans certains formats, tels que JSON, pour un traitement ultérieur, utilisez l'API Structured Output avec un accès direct au modèle.

Avec l'API Structured Output, vous définissez la structure de sortie cible à l'aide de classes et d'annotations Kotlin. L'accès direct au modèle renvoie ensuite une réponse sous la forme de votre objet Kotlin.

La génération de sorties structurées est particulièrement utile pour les tâches suivantes :

  • Extraction d'entités : extraire des champs structurés (par exemple, le nom, la date et le lieu d'un événement) à partir d'un texte non structuré.
  • Classification : catégorisation du texte d'entrée dans des catégories prédéfinies.
  • Sérialisation des données : conversion d'une entrée utilisateur non structurée dans un format adapté au stockage dans une base de données ou aux appels d'API.

Prérequis

Pour vérifier que l'API Structured Output est disponible sur l'appareil, utilisez l'API isStructuredOutputFeatureAvailable(). L'API renvoie true si l'API Structured Output est disponible sur l'appareil, et false sinon.

suspend fun isStructuredOutputFeatureAvailable(): Boolean

L'API Structured Output présente également les exigences suivantes :

  • Niveau d'API Android 26 ou supérieur (minSdk 26)
  • Plug-in KSP version 2.3.6 ou ultérieure

Limites

L'API Structured Output présente les limites suivantes :

  • Fonctionne uniquement en Kotlin.
  • ProGuard peut interférer avec l'analyse de votre classe annotée. Ajoutez votre classe annotée à vos règles de conservation pour l'exclure de ProGuard si vous obtenez des erreurs d'analyse, par exemple :
# Keep classes used by structured output for deserialization for release builds.
-keep class com.google.mlkit.genai.demo.kotlin.Plant { *; }

Configurer le projet

Pour commencer à utiliser l'API Structured Output, procédez comme suit :

  1. Ajoutez la dépendance com.google.mlkit:genai-prompt dans le fichier build.gradle.kts (ou build.gradle) au niveau de l'application, si ce n'est pas déjà fait.

  2. Ajoutez le plug-in KSP au fichier build.gradle.kts au niveau du projet. Utilisez une version du plug-in KSP compatible avec votre version de Kotlin. Nous vous recommandons la version 2.3.6 ou ultérieure de KSP.

    dependencies {
        ...
        classpath "com.google.devtools.ksp:com.google.devtools.ksp.gradle.plugin:2.3.6"
    }
    
  3. Ajoutez les dépendances du compilateur structuré au fichier build.gradle.kts au niveau de l'application :

    dependencies {
        ...
        ksp("com.google.mlkit:genai-schema-compiler:1.0.0-alpha1")
    }
    

Définir la structure de sortie

Définissez la structure des données que vous souhaitez que le modèle renvoie à l'aide des classes de données Kotlin. Il existe deux annotations principales pour définir la structure de sortie :

  • Utilisez l'annotation @Generable pour définir la classe comme cible pour la sortie structurée.
  • Utilisez les annotations @Guide sur les propriétés de la classe pour fournir des descriptions et des contraintes qui guident la sortie du modèle.

L'exemple suivant définit une structure pour extraire des informations sur les plantes :

import com.google.mlkit.genai.schema.annotations.Generable
import com.google.mlkit.genai.schema.annotations.Guide

@Generable
data class PlantList(
    @Guide(description = "The list of plants found", minItems = 1, maxItems = 5)
    val plants: List<Plant>
)

@Generable("Information about a plant species")
data class Plant(
    @Guide(description = "The common name of the plant")
    val commonName: String,
    
    @Guide(description = "The full latin scientific name of the plant")
    val scientificName: String,
    
    @Guide(
        description = "The maximum height of the plant in centimeters.",
        minimum = 1.0,
        maximum = 10000.0
    )
    val maxHeightCm: Int,
    
    @Guide(description = "Whether the plant is poisonous or not")
    val isPoisonous: Boolean?,
    
    @Guide(
        description = "The primary continent where this plant is native to",
        enumValues = ["Africa", "Antarctica", "Asia", "Australia", "Europe", "North America", "South America"]
    )
    val nativeContinent: String
)

Types et contraintes acceptés

Les types suivants sont acceptés dans une classe annotée @Generable, ainsi que leurs contraintes @Guide respectives :

Type Description Contraintes @Guide compatibles
String Pour le texte, description, enumValues
Double/Float Pour les nombres à virgule flottante. description, minimum, maximum
Int/Long Pour les nombres entiers. description, minimum, maximum
Boolean Pour les valeurs "true"/"false". description
List<T> Pour les listes de types compatibles ou de classes @Generable imbriquées. description, minItems, maxItems
List<String> Pour les listes de valeurs String. description, enumValues, minItems, maxItems
Classe @Generable Pour les objets structurés imbriqués. description

Générer du contenu structuré

Pour demander une sortie structurée, utilisez la fonction d'assistance generateTypedContentRequest pour encapsuler votre requête standard et spécifier la classe de sortie cible.

// 1. Initialize your GenerativeModel as usual
val generativeModel = Generation.getClient()

// 2. Prepare the prompt text
val promptText = "List some common plants found in California."
val baseRequest = GenerateContentRequest.Builder(TextPart(promptText)).build()

// 3. Create the typed request, specifying the target class (e.g., PlantList)
val typedRequest = generateTypedContentRequest(
    generateContentRequest = baseRequest,
    outputClass = PlantList::class
)

// 4. Run the inference
try {
    val typedResponse = generativeModel.generateContent(typedRequest)
    
    // 5. Access the parsed object
    // The response candidates contain the parsed object of type T (PlantList in this case)
    val plantList: PlantList? = typedResponse.candidates.firstOrNull()?.response
    
    if (plantList != null) {
        // Process the structured data
        for (plant in plantList.plants) {
            Log.d("StructuredOutput", "Found plant: ${plant.commonName} (${plant.scientificName})")
        }
    } else {
        Log.e("StructuredOutput", "Failed to parse response into the desired structure.")
        
        // Inspect finish reason for details
        val finishReason = typedResponse.candidates.firstOrNull()?.finishReason
        Log.d("StructuredOutput", "Finish reason: $finishReason")
    }
} catch (e: GenAiException) {
    // Handle API errors
    when (e.errorCode) {
        GenAiException.STRUCTURED_OUTPUT_INVALID_CLASS -> {
            Log.e("StructuredOutput", "The class structure is not supported.")
        }
        GenAiException.STRUCTURED_OUTPUT_INVALID_VALUE -> {
            Log.e("StructuredOutput", "The model generated values that violate the schema constraints.")
        }
        else -> {
            Log.e("StructuredOutput", "API error: ${e.message}")
        }
    }
}

Gérer les motifs d'arrêt et les erreurs

Lorsque vous utilisez l'API Structured Output, vous devez gérer les exceptions potentielles générées par l'API et inspecter la propriété finishReason dans les candidats de réponse si la réponse analysée est nulle.

Valeurs de finishReason

La propriété finishReason peut prendre l'une des valeurs suivantes :

  • TypedFinishReason.STOP : le modèle a terminé la génération et la sortie correspond au schéma.
  • TypedFinishReason.MAX_TOKENS : le modèle s'est arrêté, car il a atteint la limite de jetons. Le résultat peut être incomplet.
  • TypedFinishReason.PARSE_CLASS_ERROR : le modèle a terminé la génération, mais le JSON obtenu n'a pas pu être analysé dans la classe Kotlin cible.
  • TypedFinishReason.STRUCTURE_NOT_ANNOTATED : l'annotation @Generable requise est manquante dans la classe cible ou ses classes imbriquées.
  • TypedFinishReason.STRUCTURE_VALUES_INVALID : les valeurs générées ne respectent pas les contraintes définies dans les annotations @Guide (par exemple, valeur hors plage, taille de liste hors limites).
  • TypedFinishReason.OTHER : la génération a été arrêtée pour d'autres raisons.

Exceptions

L'API Structured Output peut générer une exception GenAiException avec les codes d'erreur suivants :

  • GenAiException.STRUCTURED_OUTPUT_INVALID_CLASS (-104) : la structure de la classe annotée n'est pas valide ou contient des types non compatibles. Il s'agit généralement d'une erreur de configuration au moment du développement. Examinez la définition de votre classe de données @Generable pour vérifier que tous les types de propriétés sont compatibles et qu'il n'y a pas de dépendances circulaires.
  • GenAiException.STRUCTURED_OUTPUT_INVALID_VALUE (-105) : les valeurs générées par le modèle ne sont pas valides ou ne respectent pas la vérification des contraintes. Il s'agit d'une erreur d'exécution. Si vous rencontrez fréquemment cette erreur, envisagez les solutions suivantes :
    • Affiner les instructions de votre prompt pour guider le modèle de manière plus stricte.
    • Assouplir les contraintes (comme les limites minimales, maximales ou de taille de liste) dans vos annotations @Guide si elles sont trop restrictives pour les capacités du modèle.
    • Implémenter une stratégie de remplacement dans votre application, par exemple en relançant la requête ou en affichant un état par défaut.

Compter les jetons

Pour vérifier si votre prompt structuré respecte la limite de jetons d'entrée, calculez le nombre de jetons à l'aide de la méthode countTokens().

Étant donné que les requêtes de sortie structurée doivent indiquer au modèle la structure du schéma, le comptage des jetons sur le texte brut du prompt (à l'aide d'une instance GenerateContentRequest) n'est pas précis. Pour obtenir un nombre de jetons précis, vous devez transmettre l'instance GenerateTypedContentRequest complète, qui inclut vos configurations de classe et de schéma cibles, à la méthode countTokens() :

suspend fun <T : Any> countTokens(request: GenerateTypedContentRequest<T>): CountTokensResponse