Genera output strutturato con l'API Gemini


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.

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.