Générer un résultat structuré avec l'API Gemini

Python Node.js Go Dart (Flutter) Android Swift Web REST

Gemini génère du texte non structuré par défaut, mais certaines applications nécessitent du texte structuré. Pour ces cas d'utilisation, vous pouvez contraindre Gemini à répondre avec du JSON, un format de données structurées adapté au traitement automatisé. Vous pouvez également contraindre le modèle à répondre avec l'une des options spécifiées dans un énumérateur.

Voici quelques cas d'utilisation qui peuvent nécessiter une sortie structurée du modèle:

• Créez une base de données d'entreprises en extrayant des informations sur les entreprises à partir d'articles de journaux.
• Extrayez des informations standardisées des CV.
• Extraction des ingrédients des recettes et affichage d'un lien vers un site Web d'épicerie pour chaque ingrédient.

Dans votre requête, vous pouvez demander à Gemini de générer une sortie au format JSON, mais notez qu'il n'est pas garanti que le modèle génère du JSON et rien d'autre. Pour obtenir une réponse plus déterministe, vous pouvez transmettre un schéma JSON spécifique dans un champ responseSchema afin que Gemini réponde toujours avec une structure attendue. Pour en savoir plus sur l'utilisation des schémas, consultez En savoir plus sur les schémas JSON.

Ce guide vous explique comment générer du code JSON à l'aide de la méthode generateContent via le SDK de votre choix ou directement à l'aide de l'API REST. Les exemples montrent une entrée textuelle uniquement, bien que Gemini puisse également produire des réponses JSON aux requêtes multimodales qui incluent des images, des vidéos et des contenus audio.

Avant de commencer: configurez votre projet et votre clé API

Avant d'appeler l'API Gemini, vous devez configurer votre projet et votre clé API.

Générer le fichier JSON

Lorsque le modèle est configuré pour générer du code JSON, il répond à toute invite avec une sortie au format JSON.

Vous pouvez contrôler la structure de la réponse JSON en fournissant un schéma. Vous pouvez fournir un schéma au modèle de deux façons:

• Sous forme de texte dans l'invite
• En tant que schéma structuré fourni via la configuration du modèle

Fournir un schéma sous forme de texte dans l'invite

L'exemple suivant invite le modèle à renvoyer des recettes de biscuits dans un format JSON spécifique.

Étant donné que le modèle obtient la spécification de format à partir du texte de la requête, vous pouvez avoir une certaine flexibilité dans la façon de représenter la spécification. Tout format raisonnable pour représenter un schéma JSON peut fonctionner.

// Make sure to include these imports:
// import { GoogleGenerativeAI } from "@google/generative-ai";
const genAI = new GoogleGenerativeAI(process.env.API_KEY);

const model = genAI.getGenerativeModel({
  model: "gemini-1.5-flash",
});

const prompt = `List a few popular cookie recipes using this JSON schema:

Recipe = {'recipeName': string}
Return: Array<Recipe>`;

const result = await model.generateContent(prompt);
console.log(result.response.text());
controlled_generation.js

Le résultat peut ressembler à ceci:

[{"recipeName": "Chocolate Chip Cookies"}, {"recipeName": "Oatmeal Raisin Cookies"}, {"recipeName": "Snickerdoodles"}, {"recipeName": "Sugar Cookies"}, {"recipeName": "Peanut Butter Cookies"}]

Fournir un schéma via la configuration du modèle

L'exemple suivant effectue les opérations suivantes:

1. Instantie un modèle configuré via un schéma pour répondre avec du JSON.
2. Demande au modèle de renvoyer des recettes de cookies.

Cette méthode plus formelle de déclaration du schéma JSON vous permet de contrôler plus précisément le schéma que si vous vous appuyiez uniquement sur le texte de l'invite.

// Make sure to include these imports:
// import { GoogleGenerativeAI, SchemaType } from "@google/generative-ai";
const genAI = new GoogleGenerativeAI(process.env.API_KEY);

const schema = {
  description: "List of recipes",
  type: SchemaType.ARRAY,
  items: {
    type: SchemaType.OBJECT,
    properties: {
      recipeName: {
        type: SchemaType.STRING,
        description: "Name of the recipe",
        nullable: false,
      },
    },
    required: ["recipeName"],
  },
};

const model = genAI.getGenerativeModel({
  model: "gemini-1.5-pro",
  generationConfig: {
    responseMimeType: "application/json",
    responseSchema: schema,
  },
});

const result = await model.generateContent(
  "List a few popular cookie recipes.",
);
console.log(result.response.text());
controlled_generation.js

Le résultat peut ressembler à ceci:

[{"recipeName": "Chocolate Chip Cookies"}, {"recipeName": "Oatmeal Raisin Cookies"}, {"recipeName": "Snickerdoodles"}, {"recipeName": "Sugar Cookies"}, {"recipeName": "Peanut Butter Cookies"}]

En savoir plus sur les schémas JSON

Lorsque vous configurez le modèle pour qu'il renvoie une réponse JSON, vous pouvez utiliser un objet Schema pour définir la forme des données JSON. Schema représente un sous-ensemble spécifique de l'objet de schéma OpenAPI 3.0.

Voici une représentation pseudo-JSON de tous les champs Schema:

{
  "type": enum (Type),
  "format": string,
  "description": string,
  "nullable": boolean,
  "enum": [
    string
  ],
  "maxItems": string,
  "minItems": string,
  "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. Seul un sous-ensemble de champs est valide pour chaque Type. La liste suivante met en correspondance chaque Type avec les champs valides pour ce type:

• string -> enum, format
• integer -> format
• number -> format
• boolean
• array -> minItems, maxItems, items
• object -> properties, required, propertyOrdering, nullable

Voici quelques exemples de schémas illustrant des combinaisons de type et de champ valides:

{ "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.

Commande de propriétés

Lorsque vous travaillez avec des schémas JSON dans l'API Gemini, l'ordre des propriétés est important. Par défaut, l'API trie 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 classement cohérent et prévisible des propriétés, vous pouvez utiliser le champ propertyOrdering[] facultatif.

"propertyOrdering": ["recipe_name", "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 cet ordre, vous pouvez potentiellement améliorer la qualité des résultats.