Vous pouvez configurer Gemini pour obtenir des résultats structurés plutôt que du texte non structuré. Cela vous permet d'extraire et de standardiser précisément les informations pour les traiter ultérieurement. Par exemple, vous pouvez utiliser une sortie structurée pour extraire des informations de CV, les standardiser et créer une base de données structurée.
Gemini peut générer des JSON ou des valeurs enum en tant que sortie structurée.
Générer du code JSON
Pour contraindre le modèle à générer du code JSON, configurez un responseSchema. Le modèle répondra ensuite à toute requête avec une sortie au format JSON.
Python
from google import genai from pydantic import BaseModel class Recipe(BaseModel): recipe_name: str ingredients: list[str] client = genai.Client() response = client.models.generate_content( model="gemini-2.5-flash", contents="List a few popular cookie recipes, and include the amounts of ingredients.", config={ "response_mime_type": "application/json", "response_schema": list[Recipe], }, ) # Use the response as a JSON string. print(response.text) # Use instantiated objects. my_recipes: list[Recipe] = response.parsed JavaScript
import { GoogleGenAI, Type } from "@google/genai"; const ai = new GoogleGenAI({}); async function main() { const response = await ai.models.generateContent({ model: "gemini-2.5-flash", contents: "List a few popular cookie recipes, and include the amounts of ingredients.", config: { responseMimeType: "application/json", responseSchema: { type: Type.ARRAY, items: { type: Type.OBJECT, properties: { recipeName: { type: Type.STRING, }, ingredients: { type: Type.ARRAY, items: { type: Type.STRING, }, }, }, propertyOrdering: ["recipeName", "ingredients"], }, }, }, }); console.log(response.text); } main(); Go
package main import ( "context" "fmt" "log" "google.golang.org/genai" ) func main() { ctx := context.Background() client, err := genai.NewClient(ctx, nil) if err != nil { log.Fatal(err) } config := &genai.GenerateContentConfig{ ResponseMIMEType: "application/json", ResponseSchema: &genai.Schema{ Type: genai.TypeArray, Items: &genai.Schema{ Type: genai.TypeObject, Properties: map[string]*genai.Schema{ "recipeName": {Type: genai.TypeString}, "ingredients": { Type: genai.TypeArray, Items: &genai.Schema{Type: genai.TypeString}, }, }, PropertyOrdering: []string{"recipeName", "ingredients"}, }, }, } result, err := client.Models.GenerateContent( ctx, "gemini-2.5-flash", genai.Text("List a few popular cookie recipes, and include the amounts of ingredients."), config, ) if err != nil { log.Fatal(err) } fmt.Println(result.Text()) } REST
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \ -H "x-goog-api-key: $GEMINI_API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "contents": [{ "parts":[ { "text": "List a few popular cookie recipes, and include the amounts of ingredients." } ] }], "generationConfig": { "responseMimeType": "application/json", "responseSchema": { "type": "ARRAY", "items": { "type": "OBJECT", "properties": { "recipeName": { "type": "STRING" }, "ingredients": { "type": "ARRAY", "items": { "type": "STRING" } } }, "propertyOrdering": ["recipeName", "ingredients"] } } } }' 2> /dev/null | head Le résultat peut ressembler à ceci :
[ { "recipeName": "Chocolate Chip Cookies", "ingredients": [ "1 cup (2 sticks) unsalted butter, softened", "3/4 cup granulated sugar", "3/4 cup packed brown sugar", "1 teaspoon vanilla extract", "2 large eggs", "2 1/4 cups all-purpose flour", "1 teaspoon baking soda", "1 teaspoon salt", "2 cups chocolate chips" ] }, ... ] Générer des valeurs enum
Dans certains cas, vous pouvez souhaiter que le modèle choisisse une seule option dans une liste d'options. Pour implémenter ce comportement, vous pouvez transmettre un enum dans votre schéma. Vous pouvez utiliser une option d'énumération partout où vous pouvez utiliser un string dans responseSchema, car une énumération est un tableau de chaînes. Comme un schéma JSON, une énumération vous permet de limiter la sortie du modèle pour répondre aux exigences de votre application.
Par exemple, supposons que vous développiez une application pour classer les instruments de musique dans l'une des cinq catégories suivantes : "Percussion", "String", "Woodwind", "Brass" ou "Keyboard". Vous pouvez créer une énumération pour vous aider dans cette tâche.
Dans l'exemple suivant, vous transmettez une énumération en tant que responseSchema, ce qui contraint le modèle à choisir l'option la plus appropriée.
Python
from google import genai import enum class Instrument(enum.Enum): PERCUSSION = "Percussion" STRING = "String" WOODWIND = "Woodwind" BRASS = "Brass" KEYBOARD = "Keyboard" client = genai.Client() response = client.models.generate_content( model='gemini-2.5-flash', contents='What type of instrument is an oboe?', config={ 'response_mime_type': 'text/x.enum', 'response_schema': Instrument, }, ) print(response.text) # Woodwind JavaScript
import { GoogleGenAI, Type } from "@google/genai"; const ai = new GoogleGenAI({}); const response = await ai.models.generateContent({ model: "gemini-2.5-flash", contents: "What type of instrument is an oboe?", config: { responseMimeType: "text/x.enum", responseSchema: { type: Type.STRING, enum: ["Percussion", "String", "Woodwind", "Brass", "Keyboard"], }, }, }); console.log(response.text); REST
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \ -H "x-goog-api-key: $GEMINI_API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "contents": [{ "parts":[ { "text": "What type of instrument is an oboe?" } ] }], "generationConfig": { "responseMimeType": "text/x.enum", "responseSchema": { "type": "STRING", "enum": ["Percussion", "String", "Woodwind", "Brass", "Keyboard"] } } }' La bibliothèque Python traduira les déclarations de type pour l'API. Toutefois, l'API accepte un sous-ensemble du schéma OpenAPI 3.0 (Schéma).
Il existe deux autres façons de spécifier une énumération. Vous pouvez utiliser un Literal : ```
Python
Literal["Percussion", "String", "Woodwind", "Brass", "Keyboard"] Vous pouvez également transmettre le schéma au format JSON :
Python
from google import genai client = genai.Client() response = client.models.generate_content( model='gemini-2.5-flash', contents='What type of instrument is an oboe?', config={ 'response_mime_type': 'text/x.enum', 'response_schema': { "type": "STRING", "enum": ["Percussion", "String", "Woodwind", "Brass", "Keyboard"], }, }, ) print(response.text) # Woodwind Au-delà des problèmes à choix multiples de base, vous pouvez utiliser une énumération n'importe où dans un schéma JSON. Par exemple, vous pouvez demander au modèle une liste de titres de recettes et utiliser un énumérateur Grade pour attribuer à chaque titre une note de popularité :
Python
from google import genai import enum from pydantic import BaseModel class Grade(enum.Enum): A_PLUS = "a+" A = "a" B = "b" C = "c" D = "d" F = "f" class Recipe(BaseModel): recipe_name: str rating: Grade client = genai.Client() response = client.models.generate_content( model='gemini-2.5-flash', contents='List 10 home-baked cookie recipes and give them grades based on tastiness.', config={ 'response_mime_type': 'application/json', 'response_schema': list[Recipe], }, ) print(response.text) La réponse peut ressembler à ce qui suit :
[ { "recipe_name": "Chocolate Chip Cookies", "rating": "a+" }, { "recipe_name": "Peanut Butter Cookies", "rating": "a" }, { "recipe_name": "Oatmeal Raisin Cookies", "rating": "b" }, ... ] À propos des schémas JSON
La configuration du modèle pour la sortie JSON à l'aide du paramètre responseSchema repose sur l'objet Schema pour définir sa structure. Cet objet représente un sous-ensemble spécifique de l'objet Schéma OpenAPI 3.0 et ajoute également un champ propertyOrdering.
Voici une représentation pseudo-JSON de tous les champs Schema :
{ "type": enum (Type), "format": string, "description": string, "nullable": boolean, "enum": [ string ], "maxItems": integer, "minItems": integer, "properties": { string: { object (Schema) }, ... }, "required": [ string ], "propertyOrdering": [ string ], "items": { object (Schema) } } Le Type du schéma doit être l'un des types de données OpenAPI ou une union de ces types (à l'aide de anyOf). Seul un sous-ensemble de champs est valide pour chaque Type. La liste suivante mappe chaque Type à un sous-ensemble des champs valides pour ce type :
string->enum,format,nullableinteger->format,minimum,maximum,enum,nullablenumber->format,minimum,maximum,enum,nullableboolean->nullablearray->minItems,maxItems,items,nullableobject->properties,required,propertyOrdering,nullable
Voici quelques exemples de schémas montrant des combinaisons valides de types et de champs :
{ "type": "string", "enum": ["a", "b", "c"] } { "type": "string", "format": "date-time" } { "type": "integer", "format": "int64" } { "type": "number", "format": "double" } { "type": "boolean" } { "type": "array", "minItems": 3, "maxItems": 3, "items": { "type": ... } } { "type": "object", "properties": { "a": { "type": ... }, "b": { "type": ... }, "c": { "type": ... } }, "nullable": true, "required": ["c"], "propertyOrdering": ["c", "b", "a"] } Pour obtenir une documentation complète sur les champs de schéma tels qu'ils sont utilisés dans l'API Gemini, consultez la référence du schéma.
Ordre des propriétés
Lorsque vous utilisez des schémas JSON dans l'API Gemini, l'ordre des propriétés est important. Par défaut, l'API classe les propriétés par ordre alphabétique et ne conserve pas l'ordre dans lequel elles sont définies (bien que les SDK Google Gen AI puissent conserver cet ordre). Si vous fournissez des exemples au modèle avec un schéma configuré, et que l'ordre des propriétés des exemples n'est pas cohérent avec l'ordre des propriétés du schéma, la sortie peut être décousue ou inattendue.
Pour garantir un ordre cohérent et prévisible des propriétés, vous pouvez utiliser le champ facultatif propertyOrdering[].
"propertyOrdering": ["recipeName", "ingredients"] propertyOrdering[] (qui n'est pas un champ standard dans la spécification OpenAPI) est un tableau de chaînes utilisé pour déterminer l'ordre des propriétés dans la réponse. En spécifiant l'ordre des propriétés, puis en fournissant des exemples avec des propriétés dans le même ordre, vous pouvez potentiellement améliorer la qualité des résultats. propertyOrdering n'est compatible que lorsque vous créez manuellement types.Schema.
Schémas en Python
Lorsque vous utilisez la bibliothèque Python, la valeur de response_schema doit être l'une des suivantes :
- Type, tel que vous l'utiliseriez dans une annotation de type (voir le module
typingde Python) - Instance de
genai.types.Schema - L'équivalent
dictdegenai.types.Schema
Le moyen le plus simple de définir un schéma consiste à utiliser un type Pydantic (comme indiqué dans l'exemple précédent) :
Python
config={'response_mime_type': 'application/json', 'response_schema': list[Recipe]} Lorsque vous utilisez un type Pydantic, la bibliothèque Python crée un schéma JSON pour vous et l'envoie à l'API. Pour obtenir d'autres exemples, consultez la documentation de la bibliothèque Python.
La bibliothèque Python est compatible avec les schémas définis avec les types suivants (où AllowedType correspond à n'importe quel type autorisé) :
intfloatboolstrlist[AllowedType]AllowedType|AllowedType|...- Pour les types structurés :
dict[str, AllowedType]. Cette annotation déclare que toutes les valeurs de dictionnaire sont du même type, mais ne spécifie pas les clés à inclure.- Modèles Pydantic définis par l'utilisateur. Cette approche vous permet de spécifier les noms de clés et de définir différents types pour les valeurs associées à chacune des clés, y compris les structures imbriquées.
Prise en charge du schéma JSON
JSON Schema est une spécification plus récente qu'OpenAPI 3.0, sur laquelle repose l'objet Schema. La compatibilité avec le schéma JSON est disponible en aperçu à l'aide du champ responseJsonSchema, qui accepte tout schéma JSON avec les limites suivantes :
- Il ne fonctionne qu'avec Gemini 2.5.
- Bien que toutes les propriétés du schéma JSON puissent être transmises, elles ne sont pas toutes prises en charge. Pour en savoir plus sur le champ, consultez la documentation.
- Les références récursives ne peuvent être utilisées que comme valeur d'une propriété d'objet non requise.
- Les références récursives sont développées dans une mesure finie, en fonction de la taille du schéma.
- Les schémas qui contiennent
$refne peuvent pas contenir d'autres propriétés que celles commençant par$.
Voici un exemple de génération d'un schéma JSON avec Pydantic et de son envoi au modèle :
curl "https://generativelanguage.googleapis.com/v1alpha/models/\ gemini-2.5-flash:generateContent" \ -H "x-goog-api-key: $GEMINI_API_KEY"\ -H 'Content-Type: application/json' \ -d @- <<EOF { "contents": [{ "parts":[{ "text": "Please give a random example following this schema" }] }], "generationConfig": { "response_mime_type": "application/json", "response_json_schema": $(python3 - << PYEOF from enum import Enum from typing import List, Optional, Union, Set from pydantic import BaseModel, Field, ConfigDict import json class UserRole(str, Enum): ADMIN = "admin" VIEWER = "viewer" class Address(BaseModel): street: str city: str class UserProfile(BaseModel): username: str = Field(description="User's unique name") age: Optional[int] = Field(ge=0, le=120) roles: Set[UserRole] = Field(min_items=1) contact: Union[Address, str] model_config = ConfigDict(title="User Schema") # Generate and print the JSON Schema print(json.dumps(UserProfile.model_json_schema(), indent=2)) PYEOF ) } } EOF L'envoi direct de schémas JSON n'est pas encore pris en charge lorsque vous utilisez le SDK.
Bonnes pratiques
Lorsque vous utilisez un schéma de réponse, gardez à l'esprit les points et les bonnes pratiques suivants :
- La taille du schéma de réponse est comptabilisée dans la limite des jetons d'entrée.
- Par défaut, les champs sont facultatifs, ce qui signifie que le modèle peut les remplir ou les ignorer. Vous pouvez définir les champs selon vos besoins pour forcer le modèle à fournir une valeur. Si le contexte de la requête d'entrée associée est insuffisant, le modèle génère des réponses principalement basées sur les données sur lesquelles il a été entraîné.
Un schéma complexe peut entraîner une erreur
InvalidArgument: 400. Cette complexité peut être due à des noms de propriété longs, des limites de longueur de tableau longues, des énumérations comportant de nombreuses valeurs, des objets avec de nombreuses propriétés facultatives ou d'une combinaison de ces facteurs.Si vous recevez cette erreur avec un schéma valide, apportez une ou plusieurs des modifications suivantes pour la résoudre :
- Raccourcissez les noms de propriété ou d'énumérations.
- Aplatissez les tableaux imbriqués.
- Réduisez le nombre de propriétés à l'aide de contraintes, par exemple des limites minimale et maximale.
- Réduisez le nombre de propriétés à l'aide de contraintes complexes, telles que des propriétés avec des formats complexes comme
date-time. - Réduisez le nombre de propriétés facultatives.
- Réduisez le nombre de valeurs valides pour les énumérations.
Si les résultats ne sont pas ceux escomptés, ajoutez plus de contexte à vos requêtes d'entrée ou modifiez votre schéma de réponse. Par exemple, examinez la réponse du modèle sans sortie structurée pour voir comment le modèle répond. Vous pouvez ensuite modifier le schéma de réponse pour qu'il corresponde mieux à la sortie du modèle. Pour obtenir d'autres conseils de dépannage concernant les sorties structurées, consultez le guide de dépannage.
Étape suivante
Maintenant que vous avez appris à générer des sorties structurées, vous pouvez essayer d'utiliser les outils de l'API Gemini :