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 (
minSdk26) - 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 :
Ajoutez la dépendance
com.google.mlkit:genai-promptdans le fichierbuild.gradle.kts(oubuild.gradle) au niveau de l'application, si ce n'est pas déjà fait.Ajoutez le plug-in KSP au fichier
build.gradle.ktsau 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" }Ajoutez les dépendances du compilateur structuré au fichier
build.gradle.ktsau 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
@Generablepour définir la classe comme cible pour la sortie structurée. - Utilisez les annotations
@Guidesur 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@Generablerequise 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@Generablepour 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
@Guidesi 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