Strukturierte Ausgabe

Sie können Gemini so konfigurieren, dass strukturierte statt unstrukturierter Text ausgegeben wird. So lassen sich Informationen präzise extrahieren und standardisieren, um sie weiter zu verarbeiten. Sie können beispielsweise strukturierte Ausgaben verwenden, um Informationen aus Lebensläufen zu extrahieren und sie zu standardisieren, um eine strukturierte Datenbank zu erstellen.

Gemini kann entweder JSON oder enum-Werte als strukturierte Ausgabe generieren.

JSON generieren

Wenn das Modell nur JSON generieren soll, konfigurieren Sie eine responseSchema. Das Modell antwortet dann auf jeden Prompt mit einer JSON-formatierten Ausgabe.

Python

from google import genai
from pydantic import BaseModel

class Recipe(BaseModel):
    recipe_name: str
    ingredients: list[str]

client = genai.Client()
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="List a few popular cookie recipes, and include the amounts of ingredients.",
    config={
        "response_mime_type": "application/json",
        "response_schema": list[Recipe],
    },
)
# Use the response as a JSON string.
print(response.text)

# Use instantiated objects.
my_recipes: list[Recipe] = response.parsed

JavaScript

import { GoogleGenAI, Type } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents:
      "List a few popular cookie recipes, and include the amounts of ingredients.",
    config: {
      responseMimeType: "application/json",
      responseSchema: {
        type: Type.ARRAY,
        items: {
          type: Type.OBJECT,
          properties: {
            recipeName: {
              type: Type.STRING,
            },
            ingredients: {
              type: Type.ARRAY,
              items: {
                type: Type.STRING,
              },
            },
          },
          propertyOrdering: ["recipeName", "ingredients"],
        },
      },
    },
  });

  console.log(response.text);
}

main();

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

    config := &genai.GenerateContentConfig{
        ResponseMIMEType: "application/json",
        ResponseSchema: &genai.Schema{
            Type: genai.TypeArray,
            Items: &genai.Schema{
                Type: genai.TypeObject,
                Properties: map[string]*genai.Schema{
                    "recipeName": {Type: genai.TypeString},
                    "ingredients": {
                        Type:  genai.TypeArray,
                        Items: &genai.Schema{Type: genai.TypeString},
                    },
                },
                PropertyOrdering: []string{"recipeName", "ingredients"},
            },
        },
    }

    result, err := client.Models.GenerateContent(
        ctx,
        "gemini-2.5-flash",
        genai.Text("List a few popular cookie recipes, and include the amounts of ingredients."),
        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' \
-d '{
      "contents": [{
        "parts":[
          { "text": "List a few popular cookie recipes, and include the amounts of ingredients." }
        ]
      }],
      "generationConfig": {
        "responseMimeType": "application/json",
        "responseSchema": {
          "type": "ARRAY",
          "items": {
            "type": "OBJECT",
            "properties": {
              "recipeName": { "type": "STRING" },
              "ingredients": {
                "type": "ARRAY",
                "items": { "type": "STRING" }
              }
            },
            "propertyOrdering": ["recipeName", "ingredients"]
          }
        }
      }
}' 2> /dev/null | head

Die Ausgabe könnte so aussehen:

[
  {
    "recipeName": "Chocolate Chip Cookies",
    "ingredients": [
      "1 cup (2 sticks) unsalted butter, softened",
      "3/4 cup granulated sugar",
      "3/4 cup packed brown sugar",
      "1 teaspoon vanilla extract",
      "2 large eggs",
      "2 1/4 cups all-purpose flour",
      "1 teaspoon baking soda",
      "1 teaspoon salt",
      "2 cups chocolate chips"
    ]
  },
  ...
]

Enum-Werte generieren

In einigen Fällen soll das Modell eine einzelne Option aus einer Liste von Optionen auswählen. Um dieses Verhalten zu implementieren, können Sie ein enum in Ihrem Schema übergeben. Sie können eine Enum-Option überall dort verwenden, wo Sie ein string in der responseSchema verwenden könnten, da ein Enum ein String-Array ist. Wie bei einem JSON-Schema können Sie mit einem Enum die Modellausgabe so einschränken, dass sie den Anforderungen Ihrer Anwendung entspricht.

Angenommen, Sie entwickeln eine Anwendung, mit der Musikinstrumente in eine von fünf Kategorien eingeteilt werden: "Percussion", "String", "Woodwind", "Brass" oder "Keyboard". Sie können ein Enum erstellen, um diese Aufgabe zu erleichtern.

Im folgenden Beispiel wird ein Enum als responseSchema übergeben, wodurch das Modell gezwungen wird, die am besten geeignete Option auszuwählen.

Python

from google import genai
import enum

class Instrument(enum.Enum):
  PERCUSSION = "Percussion"
  STRING = "String"
  WOODWIND = "Woodwind"
  BRASS = "Brass"
  KEYBOARD = "Keyboard"

client = genai.Client()
response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents='What type of instrument is an oboe?',
    config={
        'response_mime_type': 'text/x.enum',
        'response_schema': Instrument,
    },
)

print(response.text)
# Woodwind

JavaScript

import { GoogleGenAI, Type } from "@google/genai";

const ai = new GoogleGenAI({});

const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: "What type of instrument is an oboe?",
    config: {
      responseMimeType: "text/x.enum",
      responseSchema: {
        type: Type.STRING,
        enum: ["Percussion", "String", "Woodwind", "Brass", "Keyboard"],
      },
    },
  });

console.log(response.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' \
    -d '{
          "contents": [{
            "parts":[
              { "text": "What type of instrument is an oboe?" }
            ]
          }],
          "generationConfig": {
            "responseMimeType": "text/x.enum",
            "responseSchema": {
              "type": "STRING",
              "enum": ["Percussion", "String", "Woodwind", "Brass", "Keyboard"]
            }
          }
    }'

Die Python-Bibliothek übersetzt die Typdeklarationen für die API. Die API akzeptiert jedoch eine Teilmenge des OpenAPI 3.0-Schemas (Schema).

Es gibt zwei weitere Möglichkeiten, eine Aufzählung anzugeben. Sie können ein Literal verwenden: ```

Python

Literal["Percussion", "String", "Woodwind", "Brass", "Keyboard"]

Sie können das Schema auch als JSON übergeben:

Python

from google import genai

client = genai.Client()
response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents='What type of instrument is an oboe?',
    config={
        'response_mime_type': 'text/x.enum',
        'response_schema': {
            "type": "STRING",
            "enum": ["Percussion", "String", "Woodwind", "Brass", "Keyboard"],
        },
    },
)

print(response.text)
# Woodwind

Neben einfachen Multiple-Choice-Aufgaben können Sie ein Enum überall in einem JSON-Schema verwenden. Sie könnten das Modell beispielsweise nach einer Liste mit Rezepttiteln fragen und ein Grade-Enum verwenden, um jedem Titel einen Beliebtheitsgrad zuzuweisen:

Python

from google import genai

import enum
from pydantic import BaseModel

class Grade(enum.Enum):
    A_PLUS = "a+"
    A = "a"
    B = "b"
    C = "c"
    D = "d"
    F = "f"

class Recipe(BaseModel):
  recipe_name: str
  rating: Grade

client = genai.Client()
response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents='List 10 home-baked cookie recipes and give them grades based on tastiness.',
    config={
        'response_mime_type': 'application/json',
        'response_schema': list[Recipe],
    },
)

print(response.text)

Die Antwort könnte so aussehen:

[
  {
    "recipe_name": "Chocolate Chip Cookies",
    "rating": "a+"
  },
  {
    "recipe_name": "Peanut Butter Cookies",
    "rating": "a"
  },
  {
    "recipe_name": "Oatmeal Raisin Cookies",
    "rating": "b"
  },
  ...
]

JSON-Schemas

Wenn Sie das Modell für die JSON-Ausgabe mit dem Parameter responseSchema konfigurieren, wird die Struktur des Schema-Objekts verwendet. Dieses Objekt stellt eine ausgewählte Teilmenge des OpenAPI 3.0-Schemaobjekts dar und fügt außerdem ein propertyOrdering-Feld hinzu.

Hier ist eine Pseudo-JSON-Darstellung aller Schema-Felder:

{
  "type": enum (Type),
  "format": string,
  "description": string,
  "nullable": boolean,
  "enum": [
    string
  ],
  "maxItems": integer,
  "minItems": integer,
  "properties": {
    string: {
      object (Schema)
    },
    ...
  },
  "required": [
    string
  ],
  "propertyOrdering": [
    string
  ],
  "items": {
    object (Schema)
  }
}

Der Type des Schemas muss einer der OpenAPI-Datentypen oder eine Kombination dieser Typen (mit anyOf) sein. Für jeden Type ist nur eine Teilmenge von Feldern gültig. In der folgenden Liste wird jedes Type einer Teilmenge der Felder zugeordnet, die für diesen Typ gültig sind:

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

Hier sind einige Beispielschemata mit gültigen Kombinationen aus Typ und Feld:

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

Eine vollständige Dokumentation der Schemafelder, wie sie in der Gemini API verwendet werden, finden Sie in der Schemareferenz.

Reihenfolge von Properties

Wenn Sie mit JSON-Schemas in der Gemini API arbeiten, ist die Reihenfolge der Eigenschaften wichtig. Standardmäßig werden die Attribute in der API alphabetisch sortiert und die Reihenfolge, in der sie definiert sind, wird nicht beibehalten. Die Google Gen AI SDKs können diese Reihenfolge jedoch beibehalten. Wenn Sie dem Modell Beispiele mit einem konfigurierten Schema zur Verfügung stellen und die Reihenfolge der Attribute der Beispiele nicht mit der Reihenfolge der Attribute des Schemas übereinstimmt, kann die Ausgabe unzusammenhängend oder unerwartet sein.

Wenn Sie eine konsistente, vorhersehbare Reihenfolge von Attributen erzwingen möchten, können Sie das optionale Feld propertyOrdering[] verwenden.

"propertyOrdering": ["recipeName", "ingredients"]

propertyOrdering[] ist kein Standardfeld in der OpenAPI-Spezifikation, sondern ein Array von Strings, mit dem die Reihenfolge der Attribute in der Antwort festgelegt wird. Wenn Sie die Reihenfolge der Attribute angeben und dann Beispiele mit Attributen in derselben Reihenfolge bereitstellen, können Sie die Qualität der Ergebnisse möglicherweise verbessern. propertyOrdering wird nur unterstützt, wenn Sie types.Schema manuell erstellen.

Schemas in Python

Wenn Sie die Python-Bibliothek verwenden, muss der Wert von response_schema einer der folgenden sein:

  • Ein Typ, wie er in einer Typanmerkung verwendet wird (siehe das Python-Modul typing)
  • Eine Instanz von genai.types.Schema
  • Die dict-Entsprechung von genai.types.Schema

Am einfachsten lässt sich ein Schema mit einem Pydantic-Typ definieren (wie im vorherigen Beispiel gezeigt):

Python

config={'response_mime_type': 'application/json',
        'response_schema': list[Recipe]}

Wenn Sie einen Pydantic-Typ verwenden, erstellt die Python-Bibliothek ein JSON-Schema für Sie und sendet es an die API. Weitere Beispiele finden Sie in der Dokumentation zur Python-Bibliothek.

Die Python-Bibliothek unterstützt Schemas, die mit den folgenden Typen definiert sind (wobei AllowedType ein beliebiger zulässiger Typ ist):

  • int
  • float
  • bool
  • str
  • list[AllowedType]
  • AllowedType|AllowedType|...
  • Für strukturierte Typen:
    • dict[str, AllowedType]: Mit dieser Anmerkung werden alle Dict-Werte als vom selben Typ deklariert, es wird jedoch nicht angegeben, welche Schlüssel enthalten sein sollen.
    • Benutzerdefinierte Pydantic-Modelle. So können Sie die Schlüsselnamen angeben und verschiedene Typen für die Werte definieren, die den einzelnen Schlüsseln zugeordnet sind, einschließlich verschachtelter Strukturen.

Unterstützung von JSON-Schemas

JSON Schema ist eine neuere Spezifikation als OpenAPI 3.0, auf der das Schema-Objekt basiert. Die Unterstützung für JSON-Schema ist als Vorschau über das Feld responseJsonSchema verfügbar. Es akzeptiert jedes JSON-Schema mit den folgenden Einschränkungen:

  • Es funktioniert nur mit Gemini 2.5.
  • Es können zwar alle JSON-Schema-Attribute übergeben werden, aber nicht alle werden unterstützt. Weitere Informationen finden Sie in der Dokumentation zum Feld.
  • Rekursive Verweise können nur als Wert einer nicht erforderlichen Objekteigenschaft verwendet werden.
  • Rekursive Verweise werden in einem endlichen Grad entrollt, basierend auf der Größe des Schemas.
  • Schemas, die $ref enthalten, dürfen keine anderen Attribute als solche enthalten, die mit $ beginnen.

Hier ist ein Beispiel für das Generieren eines JSON-Schemas mit Pydantic und das Übermitteln an das Modell:

curl "https://generativelanguage.googleapis.com/v1alpha/models/\
gemini-2.5-flash:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY"\
    -H 'Content-Type: application/json' \
    -d @- <<EOF
{
  "contents": [{
    "parts":[{
      "text": "Please give a random example following this schema"
    }]
  }],
  "generationConfig": {
    "response_mime_type": "application/json",
    "response_json_schema": $(python3 - << PYEOF
    from enum import Enum
    from typing import List, Optional, Union, Set
    from pydantic import BaseModel, Field, ConfigDict
    import json

    class UserRole(str, Enum):
        ADMIN = "admin"
        VIEWER = "viewer"

    class Address(BaseModel):
        street: str
        city: str

    class UserProfile(BaseModel):
        username: str = Field(description="User's unique name")
        age: Optional[int] = Field(ge=0, le=120)
        roles: Set[UserRole] = Field(min_items=1)
        contact: Union[Address, str]
        model_config = ConfigDict(title="User Schema")

    # Generate and print the JSON Schema
    print(json.dumps(UserProfile.model_json_schema(), indent=2))
    PYEOF
    )
  }
}
EOF

Die direkte Übergabe von JSON-Schema wird bei Verwendung des SDK noch nicht unterstützt.

Best Practices

Beachten Sie die folgenden Überlegungen und Best Practices, wenn Sie ein Antwortschema verwenden:

  • Die Größe Ihres Antwortschemas wird auf das Eingabetokenlimit angerechnet.
  • Felder sind standardmäßig optional. Das bedeutet, dass das Modell die Felder ausfüllen oder überspringen kann. Sie können Felder als Pflichtfelder festlegen, um das Modell zu zwingen, einen Wert anzugeben. Wenn der zugehörige Eingabe-Prompt nicht genügend Kontext enthält, generiert das Modell Antworten, die hauptsächlich auf den Daten basieren, mit denen es trainiert wurde.

  • Ein komplexes Schema kann zu einem InvalidArgument: 400-Fehler führen. Komplexität kann durch lange Attributnamen, lange Arraylängenbegrenzungen, Enums mit vielen Werten, Objekte mit vielen optionalen Attributen oder eine Kombination dieser Faktoren entstehen.

    Wenn dieser Fehler bei einem gültigen Schema auftritt, nehmen Sie eine oder mehrere der folgenden Änderungen vor, um ihn zu beheben:

    • Kürzen Sie Property- oder Enum-Namen.
    • Verschachtelte Arrays vereinfachen.
    • Reduzieren Sie die Anzahl der Eigenschaften mit Einschränkungen, z. B. Zahlen mit Mindest- und Höchstgrenzen.
    • Reduzieren Sie die Anzahl der Properties mit komplexen Einschränkungen, z. B. Properties mit komplexen Formaten wie date-time.
    • Reduzieren Sie die Anzahl der optionalen Eigenschaften.
    • Reduzieren Sie die Anzahl der gültigen Werte für Enums.

  • Wenn Sie nicht die erwarteten Ergebnisse sehen, fügen Sie Ihren Eingabeaufforderungen mehr Kontext hinzu oder überarbeiten Sie Ihr Antwortschema. Sehen Sie sich beispielsweise die Antwort des Modells ohne strukturierte Ausgabe an, um zu sehen, wie das Modell reagiert. Anschließend können Sie das Antwortschema so aktualisieren, dass es besser zur Ausgabe des Modells passt. Weitere Tipps zur Fehlerbehebung bei strukturierter Ausgabe finden Sie im Leitfaden zur Fehlerbehebung.

Nächste Schritte

Nachdem Sie nun gelernt haben, wie Sie strukturierte Ausgaben generieren, können Sie die Gemini API-Tools ausprobieren: