Strukturierte Ausgaben

Sie können Gemini-Modelle so konfigurieren, dass sie Antworten generieren, die einem bereitgestellten JSON-Schema entsprechen. Diese Funktion garantiert vorhersehbare und analysierbare Ergebnisse, sorgt für Format- und Typsicherheit, ermöglicht die programmatische Erkennung von Ablehnungen und vereinfacht das Prompting.

Die Verwendung strukturierter Ausgaben ist ideal für eine Vielzahl von Anwendungen:

  • Datenextraktion:Bestimmte Informationen aus unstrukturiertem Text abrufen, z. B. Namen, Datumsangaben und Beträge aus einer Rechnung.
  • Strukturierte Klassifizierung:Text in vordefinierte Kategorien einteilen und strukturierte Labels zuweisen, z. B. Kundenfeedback nach Stimmung und Thema kategorisieren.
  • Agentic-Workflows:Generieren Sie strukturierte Daten, mit denen andere Tools oder APIs aufgerufen werden können, z. B. zum Erstellen eines Charakterblatts für ein Spiel oder zum Ausfüllen eines Formulars.

Die Google GenAI SDKs für Python und JavaScript unterstützen nicht nur JSON-Schema in der REST API, sondern ermöglichen auch die einfache Definition von Objektschemas mit Pydantic bzw. Zod. Im folgenden Beispiel wird gezeigt, wie Informationen aus unstrukturiertem Text extrahiert werden, der einem im Code definierten Schema entspricht.

In diesem Beispiel wird gezeigt, wie strukturierte Daten aus Text extrahiert werden. Dazu werden grundlegende JSON-Schematypen wie object, array, string und integer verwendet.

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

Ok

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

Beispielantwort:

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

Sie können strukturierte Ausgaben streamen. So können Sie mit der Verarbeitung der Antwort beginnen, während sie generiert wird, ohne auf die vollständige Ausgabe warten zu müssen. Dadurch kann die wahrgenommene Leistung Ihrer Anwendung verbessert werden.

Die gestreamten Chunks sind gültige partielle JSON-Strings, die verkettet werden können, um das endgültige, vollständige JSON-Objekt zu bilden.

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

Unterstützung von JSON-Schemas

Wenn Sie ein JSON-Objekt generieren möchten, setzen Sie response_mime_type in der Generierungskonfiguration auf application/json und geben Sie ein response_json_schema an. Das Schema muss ein gültiges JSON-Schema sein, das das gewünschte Ausgabeformat beschreibt.

Das Modell generiert dann eine Antwort, die ein syntaktisch gültiger JSON-String ist, der dem bereitgestellten Schema entspricht. Bei strukturierten Ausgaben erzeugt das Modell Ausgaben in derselben Reihenfolge wie die Schlüssel im Schema.

Der Modus für strukturierte Ausgabe von Gemini unterstützt eine Teilmenge der JSON-Schema-Spezifikation.

Folgende Werte für type werden unterstützt:

  • string: Für Text.
  • number: Für Gleitkommazahlen.
  • integer: Für Ganzzahlen.
  • boolean: Für „Wahr“-/„Falsch“-Werte.
  • object: Für strukturierte Daten mit Schlüssel/Wert-Paaren.
  • array: Für Listen von Elementen.
  • null: Wenn eine Property null sein darf, fügen Sie "null" in das Typ-Array ein (z.B. {"type": ["string", "null"]}).

Diese beschreibenden Attribute helfen, das Modell zu steuern:

  • title: Eine kurze Beschreibung einer Property.
  • description: Eine längere und detailliertere Beschreibung einer Property.

Typspezifische Eigenschaften

Für object-Werte:

  • properties: Ein Objekt, in dem jeder Schlüssel ein Attributname und jeder Wert ein Schema für dieses Attribut ist.
  • required: Ein Array von Strings, in dem die erforderlichen Properties aufgeführt sind.
  • additionalProperties: Steuert, ob Properties, die nicht in properties aufgeführt sind, zulässig sind. Kann ein boolescher Wert oder ein Schema sein.

Für string-Werte:

  • enum: Listet eine bestimmte Gruppe möglicher Strings für Klassifizierungsaufgaben auf.
  • format: Gibt eine Syntax für den String an, z. B. date-time, date, time.

Für number- und integer-Werte:

  • enum: Listet eine bestimmte Gruppe möglicher numerischer Werte auf.
  • minimum: Der kleinste inklusive Wert.
  • maximum: Der maximale inklusive Wert.

Für array-Werte:

  • items: Definiert das Schema für alle Elemente im Array.
  • prefixItems: Definiert eine Liste von Schemas für die ersten N Elemente, die Tupel-ähnliche Strukturen ermöglicht.
  • minItems: Die Mindestanzahl von Elementen im Array.
  • maxItems: Die maximale Anzahl von Elementen im Array.

Modellunterstützung

Die folgenden Modelle unterstützen strukturierte Ausgaben:

Modell Strukturierte Ausgaben
Gemini 2.5 Pro ✔️
Gemini 2.5 Flash ✔️
Gemini 2.5 Flash-Lite ✔️
Gemini 2.0 Flash ✔️*
Gemini 2.0 Flash-Lite ✔️*

* Hinweis: Für Gemini 2.0 ist eine explizite propertyOrdering-Liste in der JSON-Eingabe erforderlich, um die bevorzugte Struktur zu definieren. Ein Beispiel finden Sie in diesem Cookbook.

Strukturierte Ausgaben im Vergleich zu Funktionsaufrufen

Sowohl strukturierte Ausgaben als auch Funktionsaufrufe verwenden JSON-Schemas, aber sie dienen unterschiedlichen Zwecken:

Funktion Primärer Anwendungsfall
Strukturierte Ausgaben Formatieren der endgültigen Antwort an den Nutzer Verwenden Sie diese Option, wenn die Antwort des Modells in einem bestimmten Format sein soll, z.B. wenn Daten aus einem Dokument extrahiert und in einer Datenbank gespeichert werden sollen.
Funktionsaufrufe Aktionen während der Unterhaltung ausführen: Verwenden Sie diese Option, wenn das Modell Sie auffordern muss, eine Aufgabe auszuführen (z.B. „get current weather“) ausführen, bevor es eine endgültige Antwort geben kann.

Best Practices

  • Klare Beschreibungen:Verwenden Sie das Feld description in Ihrem Schema, um dem Modell klare Anweisungen dazu zu geben, wofür die einzelnen Attribute stehen. Das ist wichtig, um die Ausgabe des Modells zu steuern.
  • Starke Typisierung:Verwenden Sie nach Möglichkeit spezifische Typen (integer, string, enum). Wenn ein Parameter nur eine begrenzte Anzahl gültiger Werte hat, verwenden Sie ein enum.
  • Prompt-Engineering:Geben Sie in Ihrem Prompt deutlich an, was das Modell tun soll, z. B. „Extrahiere die folgenden Informationen aus dem Text…“ oder „Klassifiziere dieses Feedback gemäß dem bereitgestellten Schema…“.
  • Validierung:Die strukturierte Ausgabe garantiert zwar syntaktisch korrektes JSON, aber nicht, dass die Werte semantisch korrekt sind. Validieren Sie die endgültige Ausgabe immer in Ihrem Anwendungscode, bevor Sie sie verwenden.
  • Fehlerbehandlung:Implementieren Sie eine robuste Fehlerbehandlung in Ihrer Anwendung, um Fälle zu bewältigen, in denen die Ausgabe des Modells zwar schemakonform ist, aber möglicherweise nicht Ihren Anforderungen an die Geschäftslogik entspricht.

Beschränkungen

  • Schema-Teilmenge:Nicht alle Funktionen der JSON-Schemaspezifikation werden unterstützt. Nicht unterstützte Eigenschaften werden vom Modell ignoriert.
  • Schemakomplexität:Die API lehnt möglicherweise sehr große oder tief verschachtelte Schemas ab. Wenn Fehler auftreten, versuchen Sie, das Schema zu vereinfachen, indem Sie Eigenschaftsnamen kürzen, die Verschachtelung reduzieren oder die Anzahl der Einschränkungen begrenzen.