Genera output strutturato con l'API Gemini

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

Gemini genera testo non strutturato per impostazione predefinita, ma alcune applicazioni richiedono testo strutturato. Per questi casi d'uso, puoi limitare Gemini a rispondere con JSON, un formato di dati strutturati adatto all'elaborazione automatica. Puoi anche limitare il modello a rispondere con una delle opzioni specificate in un enum.

Ecco alcuni casi d'uso che potrebbero richiedere un'uscita strutturata dal modello:

• Crea un database di aziende estrapolando le informazioni dalle notizie dei giornali.
• Estrai informazioni standardizzate dai curriculum.
• Estrai gli ingredienti dalle ricette e mostra un link a un sito web di spesa per ogni ingrediente.

Nel prompt, puoi chiedere a Gemini di produrre output in formato JSON, ma tieni presente che non è garantito che il modello produca solo JSON. Per una risposta più deterministica, puoi passare uno schema JSON specifico in un campo responseSchema in modo che Gemini risponda sempre con una struttura prevista. Per scoprire di più sull'utilizzo degli schemi, consulta Scopri di più sugli schemi JSON.

Questa guida illustra come generare JSON utilizzando il metodo generateContent tramite l'SDK scelto o direttamente tramite l'API REST. Gli esempi mostrano input solo di testo, anche se Gemini può anche produrre risposte JSON a richieste multimodali che includono immagini, video e audio.

Prima di iniziare: configura il progetto e la chiave API

Prima di chiamare l'API Gemini, devi configurare il progetto e la chiave API.

Genera JSON

Quando il modello è configurato per generare output JSON, risponde a qualsiasi prompt con un output in formato JSON.

Puoi controllare la struttura della risposta JSON fornendo uno schema. Esistono due modi per fornire uno schema al modello:

• Come testo nel prompt
• Come schema strutturato fornito tramite la configurazione del modello

Fornisci uno schema come testo nel prompt

Nel seguente esempio, il modello viene invitato a restituire le ricette dei biscotti in un formato JSON specifico.

Poiché il modello ottiene la specifica del formato dal testo nel prompt, potresti avere una certa flessibilità nella rappresentazione della specifica. Può essere utilizzato qualsiasi formato ragionevole per rappresentare uno schema JSON.

// 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

L'output potrebbe avere il seguente aspetto:

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

Fornire uno schema tramite la configurazione del modello

L'esempio seguente esegue le seguenti operazioni:

1. Consente di creare un'istanza di un modello configurato tramite uno schema per rispondere con JSON.
2. Chiede al modello di restituire ricette per biscotti.

Questo metodo più formale per dichiarare lo schema JSON ti offre un controllo più preciso rispetto all'utilizzo del solo testo nel prompt.

// 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

L'output potrebbe avere il seguente aspetto:

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

Scopri di più sugli schemi JSON

Quando configuri il modello in modo che restituisca una risposta JSON, puoi utilizzare un oggetto Schema per definire la forma dei dati JSON. Schema rappresenta un sottoinsieme selezionato dell'oggetto schema OpenAPI 3.0.

Ecco una rappresentazione pseudo-JSON di tutti i campi 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)
  }
}

Il Type dello schema deve essere uno dei tipi di dati di OpenAPI. Per ogni Type è valido solo un sottoinsieme di campi. L'elenco seguente mappa ogni Type ai campi validi per quel tipo:

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

Ecco alcuni esempi di schemi che mostrano combinazioni di tipo e campo valide:

{ "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"]
}

Per la documentazione completa dei campi dello schema come vengono utilizzati nell'API Gemini, consulta il riferimento allo schema.

Ordinamento delle proprietà

Quando utilizzi gli schemi JSON nell'API Gemini, l'ordine delle proprietà è importante. Per impostazione predefinita, l'API ordina le proprietà in ordine alfabetico e non conserva l'ordine in cui sono definite (anche se gli SDK di IA generativa di Google potrebbero conservare questo ordine). Se fornisci esempi al modello con uno schema configurato e l'ordinamento delle proprietà degli esempi non è coerente con l'ordinamento delle proprietà dello schema, l'output potrebbe essere sconnesso o inaspettato.

Per garantire un ordinamento coerente e prevedibile delle proprietà, puoi utilizzare il campo facoltativo propertyOrdering[].

"propertyOrdering": ["recipe_name", "ingredients"]

propertyOrdering[], che non è un campo standard nella specifica OpenAPI, è un array di stringhe utilizzato per determinare l'ordine delle proprietà nella risposta. Se specifichi l'ordine delle proprietà e fornisci esempi con le proprietà nello stesso ordine, puoi potenzialmente migliorare la qualità dei risultati.