Output strutturati

Puoi configurare i modelli Gemini per generare risposte che rispettino uno schema JSON fornito. Questa funzionalità garantisce risultati prevedibili e analizzabili, assicura la sicurezza del formato e del tipo, consente il rilevamento programmatico dei rifiuti e semplifica i prompt.

L'utilizzo di output strutturati è ideale per un'ampia gamma di applicazioni:

  • Estrazione dei dati:estrai informazioni specifiche da testo non strutturato, ad esempio nomi, date e importi da una fattura.
  • Classificazione strutturata:classifica il testo in categorie predefinite e assegna etichette strutturate, ad esempio la classificazione del feedback dei clienti in base al sentimento e all'argomento.
  • Flussi di lavoro agentici:genera dati strutturati che possono essere utilizzati per chiamare altri strumenti o API, ad esempio per creare una scheda del personaggio per un gioco o compilare un modulo.

Oltre a supportare JSON Schema nell'API REST, gli SDK Google GenAI per Python e JavaScript semplificano anche la definizione degli schemi degli oggetti utilizzando rispettivamente Pydantic e Zod. L'esempio seguente mostra come estrarre informazioni da testo non strutturato conforme a uno schema definito nel codice.

Questo esempio mostra come estrarre dati strutturati dal testo utilizzando i tipi di schema JSON di base come object, array, string e integer.

Python

from google import genai
from pydantic import BaseModel, Field
from typing import List, Optional

class Ingredient(BaseModel):
    name: str = Field(description="Name of the ingredient.")
    quantity: str = Field(description="Quantity of the ingredient, including units.")

class Recipe(BaseModel):
    recipe_name: str = Field(description="The name of the recipe.")
    prep_time_minutes: Optional[int] = Field(description="Optional time in minutes to prepare the recipe.")
    ingredients: List[Ingredient]
    instructions: List[str]

client = genai.Client()

prompt = """
Please extract the recipe from the following text.
The user wants to make delicious chocolate chip cookies.
They need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda,
1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar,
3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.
For the best part, they'll need 2 cups of semisweet chocolate chips.
First, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,
baking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar
until light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry
ingredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons
onto ungreased baking sheets and bake for 9 to 11 minutes.
"""

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents=prompt,
    config={
        "response_mime_type": "application/json",
        "response_json_schema": Recipe.model_json_schema(),
    },
)

recipe = Recipe.model_validate_json(response.text)
print(recipe)

JavaScript

import { GoogleGenAI } from "@google/genai";
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";

const ingredientSchema = z.object({
  name: z.string().describe("Name of the ingredient."),
  quantity: z.string().describe("Quantity of the ingredient, including units."),
});

const recipeSchema = z.object({
  recipe_name: z.string().describe("The name of the recipe."),
  prep_time_minutes: z.number().optional().describe("Optional time in minutes to prepare the recipe."),
  ingredients: z.array(ingredientSchema),
  instructions: z.array(z.string()),
});

const ai = new GoogleGenAI({});

const prompt = `
Please extract the recipe from the following text.
The user wants to make delicious chocolate chip cookies.
They need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda,
1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar,
3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.
For the best part, they'll need 2 cups of semisweet chocolate chips.
First, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,
baking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar
until light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry
ingredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons
onto ungreased baking sheets and bake for 9 to 11 minutes.
`;

const response = await ai.models.generateContent({
  model: "gemini-2.5-flash",
  contents: prompt,
  config: {
    responseMimeType: "application/json",
    responseJsonSchema: zodToJsonSchema(recipeSchema),
  },
});

const recipe = recipeSchema.parse(JSON.parse(response.text));
console.log(recipe);

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)
    }

    prompt := `
  Please extract the recipe from the following text.
  The user wants to make delicious chocolate chip cookies.
  They need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda,
  1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar,
  3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.
  For the best part, they'll need 2 cups of semisweet chocolate chips.
  First, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,
  baking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar
  until light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry
  ingredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons
  onto ungreased baking sheets and bake for 9 to 11 minutes.
  `
    config := &genai.GenerateContentConfig{
        ResponseMIMEType: "application/json",
        ResponseJsonSchema: map[string]any{
            "type": "object",
            "properties": map[string]any{
                "recipe_name": map[string]any{
                    "type":        "string",
                    "description": "The name of the recipe.",
                },
                "prep_time_minutes": map[string]any{
                    "type":        "integer",
                    "description": "Optional time in minutes to prepare the recipe.",
                },
                "ingredients": map[string]any{
                    "type": "array",
                    "items": map[string]any{
                        "type": "object",
                        "properties": map[string]any{
                            "name": map[string]any{
                                "type":        "string",
                                "description": "Name of the ingredient.",
                            },
                            "quantity": map[string]any{
                                "type":        "string",
                                "description": "Quantity of the ingredient, including units.",
                            },
                        },
                        "required": []string{"name", "quantity"},
                    },
                },
                "instructions": map[string]any{
                    "type":  "array",
                    "items": map[string]any{"type": "string"},
                },
            },
            "required": []string{"recipe_name", "ingredients", "instructions"},
        },
    }

    result, err := client.Models.GenerateContent(
        ctx,
        "gemini-2.5-flash",
        genai.Text(prompt),
        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' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          { "text": "Please extract the recipe from the following text.\nThe user wants to make delicious chocolate chip cookies.\nThey need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda,\n1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar,\n3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.\nFor the best part, they will need 2 cups of semisweet chocolate chips.\nFirst, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,\nbaking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar\nuntil light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry\ningredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons\nonto ungreased baking sheets and bake for 9 to 11 minutes." }
        ]
      }],
      "generationConfig": {
        "responseMimeType": "application/json",
        "responseJsonSchema": {
          "type": "object",
          "properties": {
            "recipe_name": {
              "type": "string",
              "description": "The name of the recipe."
            },
            "prep_time_minutes": {
                "type": "integer",
                "description": "Optional time in minutes to prepare the recipe."
            },
            "ingredients": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "name": { "type": "string", "description": "Name of the ingredient."},
                  "quantity": { "type": "string", "description": "Quantity of the ingredient, including units."}
                },
                "required": ["name", "quantity"]
              }
            },
            "instructions": {
              "type": "array",
              "items": { "type": "string" }
            }
          },
          "required": ["recipe_name", "ingredients", "instructions"]
        }
      }
    }'

Esempio di risposta:

{
  "recipe_name": "Delicious Chocolate Chip Cookies",
  "ingredients": [
    {
      "name": "all-purpose flour",
      "quantity": "2 and 1/4 cups"
    },
    {
      "name": "baking soda",
      "quantity": "1 teaspoon"
    },
    {
      "name": "salt",
      "quantity": "1 teaspoon"
    },
    {
      "name": "unsalted butter (softened)",
      "quantity": "1 cup"
    },
    {
      "name": "granulated sugar",
      "quantity": "3/4 cup"
    },
    {
      "name": "packed brown sugar",
      "quantity": "3/4 cup"
    },
    {
      "name": "vanilla extract",
      "quantity": "1 teaspoon"
    },
    {
      "name": "large eggs",
      "quantity": "2"
    },
    {
      "name": "semisweet chocolate chips",
      "quantity": "2 cups"
    }
  ],
  "instructions": [
    "Preheat the oven to 375°F (190°C).",
    "In a small bowl, whisk together the flour, baking soda, and salt.",
    "In a large bowl, cream together the butter, granulated sugar, and brown sugar until light and fluffy.",
    "Beat in the vanilla and eggs, one at a time.",
    "Gradually beat in the dry ingredients until just combined.",
    "Stir in the chocolate chips.",
    "Drop by rounded tablespoons onto ungreased baking sheets and bake for 9 to 11 minutes."
  ]
}

Streaming

Puoi trasmettere in streaming gli output strutturati, il che ti consente di iniziare a elaborare la risposta man mano che viene generata, senza dover attendere il completamento dell'intero output. In questo modo, puoi migliorare le prestazioni percepite della tua applicazione.

I blocchi trasmessi in streaming saranno stringhe JSON parziali valide, che possono essere concatenate per formare l'oggetto JSON finale completo.

Python

from google import genai
from pydantic import BaseModel, Field
from typing import Literal

class Feedback(BaseModel):
    sentiment: Literal["positive", "neutral", "negative"]
    summary: str

client = genai.Client()
prompt = "The new UI is incredibly intuitive and visually appealing. Great job. Add a very long summary to test streaming!"

response_stream = client.models.generate_content_stream(
    model="gemini-2.5-flash",
    contents=prompt,
    config={
        "response_mime_type": "application/json",
        "response_json_schema": Feedback.model_json_schema(),
    },
)

for chunk in response_stream:
    print(chunk.candidates[0].content.parts[0].text)

JavaScript

import { GoogleGenAI } from "@google/genai";
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";

const ai = new GoogleGenAI({});
const prompt = "The new UI is incredibly intuitive and visually appealing. Great job! Add a very long summary to test streaming!";

const feedbackSchema = z.object({
  sentiment: z.enum(["positive", "neutral", "negative"]),
  summary: z.string(),
});

const stream = await ai.models.generateContentStream({
  model: "gemini-2.5-flash",
  contents: prompt,
  config: {
    responseMimeType: "application/json",
    responseJsonSchema: zodToJsonSchema(feedbackSchema),
  },
});

for await (const chunk of stream) {
  console.log(chunk.candidates[0].content.parts[0].text)
}

Supporto dello schema JSON

Per generare un oggetto JSON, imposta response_mime_type nella configurazione di generazione su application/json e fornisci un response_json_schema. Lo schema deve essere uno schema JSON valido che descriva il formato di output desiderato.

Il modello genererà quindi una risposta che è una stringa JSON sintatticamente valida corrispondente allo schema fornito. Quando utilizzi output strutturati, il modello produce output nello stesso ordine delle chiavi nello schema.

La modalità di output strutturato di Gemini supporta un sottoinsieme della specifica JSON Schema.

Sono supportati i seguenti valori di type:

  • string: Per il testo.
  • number: per i numeri in virgola mobile.
  • integer: per i numeri interi.
  • boolean: per i valori vero/falso.
  • object: per dati strutturati con coppie chiave-valore.
  • array: per gli elenchi di elementi.
  • null: per consentire a una proprietà di essere null, includi "null" nell'array di tipi (ad es. {"type": ["string", "null"]}).

Queste proprietà descrittive aiutano a guidare il modello:

  • title: una breve descrizione di una proprietà.
  • description: una descrizione più lunga e dettagliata di una proprietà.

Proprietà specifiche per tipo

Per i valori di object:

  • properties: un oggetto in cui ogni chiave è un nome di proprietà e ogni valore è uno schema per quella proprietà.
  • required: un array di stringhe che elenca le proprietà obbligatorie.
  • additionalProperties: controlla se le proprietà non elencate in properties sono consentite. Può essere un valore booleano o uno schema.

Per i valori di string:

  • enum: elenca un insieme specifico di possibili stringhe per le attività di classificazione.
  • format: specifica una sintassi per la stringa, ad esempio date-time, date, time.

Per i valori number e integer:

  • enum: elenca un insieme specifico di possibili valori numerici.
  • minimum: il valore inclusivo minimo.
  • maximum: il valore inclusivo massimo.

Per i valori di array:

  • items: definisce lo schema per tutti gli elementi dell'array.
  • prefixItems: definisce un elenco di schemi per i primi N elementi, consentendo strutture simili a tuple.
  • minItems: il numero minimo di elementi nell'array.
  • maxItems: il numero massimo di elementi nell'array.

Supporto del modello

I seguenti modelli supportano l'output strutturato:

Modello Output strutturati
Gemini 2.5 Pro ✔️
Gemini 2.5 Flash ✔️
Gemini 2.5 Flash-Lite ✔️
Gemini 2.0 Flash ✔️*
Gemini 2.0 Flash-Lite ✔️*

* Tieni presente che Gemini 2.0 richiede un elenco propertyOrdering esplicito all'interno dell'input JSON per definire la struttura preferita. Puoi trovare un esempio in questo cookbook.

Output strutturati e chiamata di funzione

Sia gli output strutturati che la chiamata di funzioni utilizzano schemi JSON, ma hanno scopi diversi:

Funzionalità Caso d'uso principale
Output strutturati Formattazione della risposta finale all'utente. Utilizza questo prompt quando vuoi che la risposta del modello sia in un formato specifico (ad es. estrazione di dati da un documento da salvare in un database).
Chiamata di funzione Eseguire azioni durante la conversazione. Utilizza questa opzione quando il modello deve chiederti di eseguire un'attività (ad es. "get current weather" (ottieni il meteo attuale) prima di poter fornire una risposta definitiva.

Best practice

  • Descrizioni chiare:utilizza il campo description nello schema per fornire istruzioni chiare al modello su cosa rappresenta ogni proprietà. Questo è fondamentale per guidare l'output del modello.
  • Tipizzazione forte:utilizza tipi specifici (integer, string, enum) quando possibile. Se un parametro ha un insieme limitato di valori validi, utilizza un enum.
  • Ingegneria dei prompt: indica chiaramente nel prompt cosa vuoi che faccia il modello. Ad esempio, "Estrai le seguenti informazioni dal testo…" o "Classifica questo feedback in base allo schema fornito…".
  • Convalida:sebbene l'output strutturato garantisca un JSON sintatticamente corretto, non garantisce che i valori siano semanticamente corretti. Verifica sempre l'output finale nel codice dell'applicazione prima di utilizzarlo.
  • Gestione degli errori:implementa una gestione degli errori efficace nella tua applicazione per gestire correttamente i casi in cui l'output del modello, pur essendo conforme allo schema, potrebbe non soddisfare i requisiti della logica di business.

Limitazioni

  • Sottoinsieme dello schema:non tutte le funzionalità della specifica JSON Schema sono supportate. Il modello ignora le proprietà non supportate.
  • Complessità dello schema:l'API potrebbe rifiutare schemi molto grandi o con un livello di nidificazione elevato. Se si verificano errori, prova a semplificare lo schema riducendo i nomi delle proprietà, diminuendo il livello di nidificazione o limitando il numero di vincoli.