Strukturierte Ausgabe

Sie können dafür sorgen, dass die vom Modell generierte Ausgabe immer einem bestimmten Schema entspricht, damit Sie einheitlich formatierte Antworten erhalten. Möglicherweise haben Sie beispielsweise ein etabliertes Datenschema, das Sie für andere Aufgaben verwenden. Wenn Sie das Modell dem gleichen Schema folgen lassen, können Sie Daten direkt aus der Ausgabe des Modells extrahieren, ohne dass eine Nachbearbeitung erforderlich ist.

Wenn Sie die Struktur der Ausgabe eines Modells festlegen möchten, definieren Sie ein Antwortschema, das als Vorlage für Modellantworten dient. Wenn Sie einen Prompt mit dem Antwortschema senden, entspricht die Antwort des Modells immer dem von Ihnen definierten Schema.

Sie können die generierte Ausgabe bei Verwendung der folgenden Modelle steuern:

Nutzerhandbuch für Open Models

Beispielanwendungsfälle

Ein Anwendungsfall für die Anwendung eines Antwortschemas besteht darin, sicherzustellen, dass die Antwort eines Modells gültiges JSON erzeugt und Ihrem Schema entspricht. Die Ausgaben generativer Modelle können eine gewisse Variabilität aufweisen. Wenn Sie ein Antwortschema einfügen, erhalten Sie immer gültiges JSON. Daher können Ihre nachgelagerten Aufgaben zuverlässig gültige JSON-Eingaben aus generierten Antworten erwarten.

Ein weiteres Beispiel ist, die Art der Antwort eines Modells einzuschränken. Sie können beispielsweise ein Modell verwenden, um Text mit benutzerdefinierten Labels zu annotieren, nicht mit Labels, die vom Modell generiert werden. Diese Einschränkung ist nützlich, wenn Sie eine bestimmte Gruppe von Labels wie positive oder negative erwarten und keine Mischung aus anderen Labels erhalten möchten, die das Modell möglicherweise generiert, z. B. good, positive, negative oder bad.

Hinweise

Im Folgenden werden potenzielle Einschränkungen bei der Verwendung eines Antwortschemas beschrieben:

  • Sie müssen die API verwenden, um ein Antwortschema zu definieren und zu verwenden. Es gibt keine Konsolenunterstützung.
  • Die Größe Ihres Antwortschemas wird auf das Tokenlimit für die Eingabe angerechnet.
  • Es werden nur bestimmte Ausgabeformate unterstützt, z. B. application/json oder text/x.enum. Weitere Informationen finden Sie in der Gemini API-Referenz unter dem Parameter responseMimeType.
  • Die strukturierte Ausgabe unterstützt eine Teilmenge der Vertex AI-Schemareferenz. Weitere Informationen finden Sie unter Unterstützte Schemafelder.

  • 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 Attributnamen 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 Enumerationen.

Unterstützte Schemafelder

Die strukturierte Ausgabe unterstützt die folgenden Felder aus dem Vertex AI-Schema. Wenn Sie ein nicht unterstütztes Feld verwenden, kann Vertex AI Ihre Anfrage trotzdem bearbeiten, ignoriert das Feld jedoch.

  • anyOf
  • enum: Es werden nur string-Enums unterstützt.
  • format
  • items
  • maximum
  • maxItems
  • minimum
  • minItems
  • nullable
  • properties
  • propertyOrdering*
  • required

* propertyOrdering ist speziell für strukturierte Ausgaben vorgesehen und nicht Teil des Vertex AI-Schemas. In diesem Feld wird die Reihenfolge festgelegt, in der Eigenschaften generiert werden. Die aufgeführten Properties müssen eindeutig sein und gültige Schlüssel im properties-Dictionary sein.

Wenn Sie ein Schema definieren, hält sich das Modell nicht strikt an die Reihenfolge der Attribute, die Sie im Feld properties definieren. Wenn Sie eine bestimmte Reihenfolge für die Generierung von Attributen erzwingen möchten, verwenden Sie das Feld propertyOrdering. Properties, die in propertyOrdering aufgeführt sind, werden zuerst in der angegebenen Reihenfolge generiert, gefolgt von allen anderen Properties.

Wenn Sie das Python SDK verwenden, entspricht die standardmäßige Reihenfolge der Attribute der Reihenfolge, die in Ihrem Schema definiert ist. In allen anderen Fällen werden Properties alphabetisch generiert. Die erforderlichen Properties werden zuerst gruppiert, gefolgt von optionalen Properties.

Für das Feld format unterstützt Vertex AI die folgenden Werte: date, date-time, duration und time. Die Beschreibung und das Format der einzelnen Werte sind in der OpenAPI Initiative Registry beschrieben.

Hinweise

Definieren Sie ein Antwortschema, um die Struktur der Modellausgabe, die Feldnamen und den erwarteten Datentyp für jedes Feld festzulegen. Verwenden Sie nur die unterstützten Felder, die im Abschnitt Wichtige Hinweise aufgeführt sind. Alle anderen Felder werden ignoriert.

Fügen Sie Ihr Antwortschema nur als Teil des Felds responseSchema ein. Wiederholen Sie das Schema nicht in Ihrem Eingabe-Prompt. In diesem Fall ist die Qualität der generierten Ausgabe möglicherweise geringer.

Beispielschemata finden Sie im Abschnitt Beispielschemata und Modellantworten.

Modellverhalten und Antwortschema

Wenn ein Modell eine Antwort generiert, verwendet es den Feldnamen und den Kontext aus Ihrem Prompt. Wir empfehlen daher, eine klare Struktur und eindeutige Feldnamen zu verwenden, damit Ihre Absicht klar ist.

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.

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 Ihr Antwortschema aktualisieren, damit es besser zur Ausgabe des Modells passt.

Prompt mit Antwortschema senden

Standardmäßig sind alle Felder optional. Das bedeutet, dass ein Modell möglicherweise eine Antwort auf ein Feld generiert. Wenn Sie erzwingen möchten, dass das Modell immer eine Antwort für ein Feld generiert, legen Sie das Feld entsprechend fest.

Python

Installieren

pip install --upgrade google-genai

Weitere Informationen finden Sie in der SDK-Referenzdokumentation.

Umgebungsvariablen für die Verwendung des Gen AI SDK mit Vertex AI festlegen: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True
 

from google import genai
from google.genai.types import HttpOptions

response_schema = {
    "type": "ARRAY",
    "items": {
        "type": "OBJECT",
        "properties": {
            "recipe_name": {"type": "STRING"},
            "ingredients": {"type": "ARRAY", "items": {"type": "STRING"}},
        },
        "required": ["recipe_name", "ingredients"],
    },
}

prompt = """
    List a few popular cookie recipes.
"""

client = genai.Client(http_options=HttpOptions(api_version="v1"))
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents=prompt,
    config={
        "response_mime_type": "application/json",
        "response_schema": response_schema,
    },
)

print(response.text)
# Example output:
# [
#     {
#         "ingredients": [
#             "2 1/4 cups all-purpose flour",
#             "1 teaspoon baking soda",
#             "1 teaspoon salt",
#             "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 cups chocolate chips",
#         ],
#         "recipe_name": "Chocolate Chip Cookies",
#     }
# ]

Go

Informationen zum Installieren oder Aktualisieren von Go

Weitere Informationen finden Sie in der SDK-Referenzdokumentation.

Umgebungsvariablen für die Verwendung des Gen AI SDK mit Vertex AI festlegen: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True
 

import (
	"context"
	"fmt"
	"io"

	genai "google.golang.org/genai"
)

// generateWithRespSchema shows how to use a response schema to generate output in a specific format.
func generateWithRespSchema(w io.Writer) error {
	ctx := context.Background()

	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"},
	})
	if err != nil {
		return fmt.Errorf("failed to create genai client: %w", err)
	}

	config := &genai.GenerateContentConfig{
		ResponseMIMEType: "application/json",
		// See the OpenAPI specification for more details and examples:
		//   https://spec.openapis.org/oas/v3.0.3.html#schema-object
		ResponseSchema: &genai.Schema{
			Type: "array",
			Items: &genai.Schema{
				Type: "object",
				Properties: map[string]*genai.Schema{
					"recipe_name": {Type: "string"},
					"ingredients": {
						Type:  "array",
						Items: &genai.Schema{Type: "string"},
					},
				},
				Required: []string{"recipe_name", "ingredients"},
			},
		},
	}
	contents := []*genai.Content{
		{Parts: []*genai.Part{
			{Text: "List a few popular cookie recipes."},
		},
			Role: "user"},
	}
	modelName := "gemini-2.5-flash"

	resp, err := client.Models.GenerateContent(ctx, modelName, contents, config)
	if err != nil {
		return fmt.Errorf("failed to generate content: %w", err)
	}

	respText := resp.Text()

	fmt.Fprintln(w, respText)

	// Example response:
	// [
	//   {
	//     "ingredients": [
	//       "2 1/4 cups all-purpose flour",
	//       "1 teaspoon baking soda",
	//       ...
	//     ],
	//     "recipe_name": "Chocolate Chip Cookies"
	//   },
	//   {
	//     ...
	//   },
	//   ...
	// ]

	return nil
}

Node.js

Installieren

npm install @google/genai

Weitere Informationen finden Sie in der SDK-Referenzdokumentation.

Umgebungsvariablen für die Verwendung des Gen AI SDK mit Vertex AI festlegen: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True
 

const {GoogleGenAI} = require('@google/genai');

const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;
const GOOGLE_CLOUD_LOCATION = process.env.GOOGLE_CLOUD_LOCATION || 'global';

async function generateResponseSchema(
  projectId = GOOGLE_CLOUD_PROJECT,
  location = GOOGLE_CLOUD_LOCATION
) {
  const client = new GoogleGenAI({
    vertexai: true,
    project: projectId,
    location: location,
  });

  const prompt = 'List a few popular cookie recipes.';

  const responseSchema = {
    type: 'ARRAY',
    items: {
      type: 'OBJECT',
      properties: {
        recipeName: {type: 'STRING'},
        ingredients: {
          type: 'ARRAY',
          items: {type: 'STRING'},
        },
      },
      required: ['recipeName', 'ingredients'],
    },
  };

  const response = await client.models.generateContent({
    model: 'gemini-2.5-flash',
    contents: prompt,
    config: {
      responseMimeType: 'application/json',
      responseSchema: responseSchema,
    },
  });

  console.log(response.text);

  // Example output:
  // [
  //     {
  //         "ingredients": [
  //             "2 1/4 cups all-purpose flour",
  //             "1 teaspoon baking soda",
  //             "1 teaspoon salt",
  //             "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 cups chocolate chips",
  //         ],
  //         "recipe_name": "Chocolate Chip Cookies",
  //     }
  // ]

  return response.text;
}

REST

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • GENERATE_RESPONSE_METHOD: Der Typ der Antwort, die das Modell generieren soll. Wählen Sie eine Methode aus, mit der generiert wird, wie die Antwort des Modells zurückgegeben werden soll:
    • streamGenerateContent: Die Antwort wird während der Generierung gestreamt, um die Wahrnehmung der Latenz für menschliche Zielgruppen zu reduzieren.
    • generateContent: Die Antwort wird zurückgegeben, nachdem sie vollständig generiert wurde.
  • LOCATION: Die Region, in der die Anfrage verarbeitet werden soll.
  • PROJECT_ID: Ihre Projekt-ID.
  • MODEL_ID: Die Modell-ID des multimodalen Modells, das Sie verwenden möchten.
  • ROLE: Die Rolle in einer Unterhaltung, die mit dem Inhalt verknüpft ist. Die Angabe einer Rolle ist auch bei Anwendungsfällen mit nur einem Schritt erforderlich. Unter anderem sind folgende Werte zulässig:
    • USER: Gibt Inhalte an, die von Ihnen gesendet werden
  • TEXT: Die Textanleitung, die in den Prompt eingefügt werden soll.
  • RESPONSE_MIME_TYPE: Der Formattyp des generierten Kandidatentexts. Eine Liste der unterstützten Werte finden Sie im Parameter responseMimeType in der Gemini API.
  • RESPONSE_SCHEMA: Schema, dem das Modell beim Generieren von Antworten folgen soll. Weitere Informationen finden Sie in der Schema-Referenz.

HTTP-Methode und URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD

JSON-Text der Anfrage:

{
  "contents": {
    "role": "ROLE",
    "parts": {
      "text": "TEXT"
    }
  },
  "generation_config": {
    "responseMimeType": "RESPONSE_MIME_TYPE",
    "responseSchema": RESPONSE_SCHEMA,
  }
}

Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

curl

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD"

PowerShell

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD" | Select-Object -Expand Content

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

Beispiel: cURL-Befehls

LOCATION="us-central1"
MODEL_ID="gemini-2.5-flash"
PROJECT_ID="test-project"
GENERATE_RESPONSE_METHOD="generateContent"

cat << EOF > request.json
{
  "contents": {
    "role": "user",
    "parts": {
      "text": "List a few popular cookie recipes."
    }
  },
  "generation_config": {
    "maxOutputTokens": 2048,
    "responseMimeType": "application/json",
    "responseSchema": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "recipe_name": {
            "type": "string",
          },
        },
        "required": ["recipe_name"],
      },
    }
  }
}
EOF

curl \
-X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}:${GENERATE_RESPONSE_METHOD} \
-d '@request.json'

Beispielschemas für die JSON-Ausgabe

In den folgenden Abschnitten finden Sie verschiedene Beispiel-Prompts und Antwortschemata. Nach jedem Codebeispiel finden Sie auch eine Beispielantwort des Modells.

Wetter für jeden Tag der Woche vorhersagen

Im folgenden Beispiel wird für jeden Tag der Woche ein forecast-Objekt ausgegeben, das eine Reihe von Attributen wie die erwartete Temperatur und Luftfeuchtigkeit für den Tag enthält. Einige Attribute sind auf „nullable“ gesetzt, damit das Modell einen Nullwert zurückgeben kann, wenn nicht genügend Kontext vorhanden ist, um eine sinnvolle Antwort zu generieren. Diese Strategie trägt dazu bei, Halluzinationen zu verringern.

Python

Installieren

pip install --upgrade google-genai

Weitere Informationen finden Sie in der SDK-Referenzdokumentation.

Umgebungsvariablen für die Verwendung des Gen AI SDK mit Vertex AI festlegen: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True
 

from google import genai
from google.genai.types import GenerateContentConfig, HttpOptions

response_schema = {
    "type": "OBJECT",
    "properties": {
        "forecast": {
            "type": "ARRAY",
            "items": {
                "type": "OBJECT",
                "properties": {
                    "Day": {"type": "STRING", "nullable": True},
                    "Forecast": {"type": "STRING", "nullable": True},
                    "Temperature": {"type": "INTEGER", "nullable": True},
                    "Humidity": {"type": "STRING", "nullable": True},
                    "Wind Speed": {"type": "INTEGER", "nullable": True},
                },
                "required": ["Day", "Temperature", "Forecast", "Wind Speed"],
            },
        }
    },
}

prompt = """
    The week ahead brings a mix of weather conditions.
    Sunday is expected to be sunny with a temperature of 77°F and a humidity level of 50%. Winds will be light at around 10 km/h.
    Monday will see partly cloudy skies with a slightly cooler temperature of 72°F and the winds will pick up slightly to around 15 km/h.
    Tuesday brings rain showers, with temperatures dropping to 64°F and humidity rising to 70%.
    Wednesday may see thunderstorms, with a temperature of 68°F.
    Thursday will be cloudy with a temperature of 66°F and moderate humidity at 60%.
    Friday returns to partly cloudy conditions, with a temperature of 73°F and the Winds will be light at 12 km/h.
    Finally, Saturday rounds off the week with sunny skies, a temperature of 80°F, and a humidity level of 40%. Winds will be gentle at 8 km/h.
"""

client = genai.Client(http_options=HttpOptions(api_version="v1"))
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents=prompt,
    config=GenerateContentConfig(
        response_mime_type="application/json",
        response_schema=response_schema,
    ),
)

print(response.text)
# Example output:
# {"forecast": [{"Day": "Sunday", "Forecast": "sunny", "Temperature": 77, "Wind Speed": 10, "Humidity": "50%"},
#   {"Day": "Monday", "Forecast": "partly cloudy", "Temperature": 72, "Wind Speed": 15},
#   {"Day": "Tuesday", "Forecast": "rain showers", "Temperature": 64, "Wind Speed": null, "Humidity": "70%"},
#   {"Day": "Wednesday", "Forecast": "thunderstorms", "Temperature": 68, "Wind Speed": null},
#   {"Day": "Thursday", "Forecast": "cloudy", "Temperature": 66, "Wind Speed": null, "Humidity": "60%"},
#   {"Day": "Friday", "Forecast": "partly cloudy", "Temperature": 73, "Wind Speed": 12},
#   {"Day": "Saturday", "Forecast": "sunny", "Temperature": 80, "Wind Speed": 8, "Humidity": "40%"}]}

Go

Informationen zum Installieren oder Aktualisieren von Go

Weitere Informationen finden Sie in der SDK-Referenzdokumentation.

Umgebungsvariablen für die Verwendung des Gen AI SDK mit Vertex AI festlegen: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True
 

import (
	"context"
	"fmt"
	"io"

	genai "google.golang.org/genai"
)

// generateWithNullables shows how to use the response schema with nullable values.
func generateWithNullables(w io.Writer) error {
	ctx := context.Background()

	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"},
	})
	if err != nil {
		return fmt.Errorf("failed to create genai client: %w", err)
	}

	modelName := "gemini-2.5-flash"
	prompt := `
The week ahead brings a mix of weather conditions.
Sunday is expected to be sunny with a temperature of 77°F and a humidity level of 50%. Winds will be light at around 10 km/h.
Monday will see partly cloudy skies with a slightly cooler temperature of 72°F and the winds will pick up slightly to around 15 km/h.
Tuesday brings rain showers, with temperatures dropping to 64°F and humidity rising to 70%.
Wednesday may see thunderstorms, with a temperature of 68°F.
Thursday will be cloudy with a temperature of 66°F and moderate humidity at 60%.
Friday returns to partly cloudy conditions, with a temperature of 73°F and the Winds will be light at 12 km/h.
Finally, Saturday rounds off the week with sunny skies, a temperature of 80°F, and a humidity level of 40%. Winds will be gentle at 8 km/h.
`
	contents := []*genai.Content{
		{Parts: []*genai.Part{
			{Text: prompt},
		},
			Role: "user"},
	}
	config := &genai.GenerateContentConfig{
		ResponseMIMEType: "application/json",
		// See the OpenAPI specification for more details and examples:
		//   https://spec.openapis.org/oas/v3.0.3.html#schema-object
		ResponseSchema: &genai.Schema{
			Type: "object",
			Properties: map[string]*genai.Schema{
				"forecast": {
					Type: "array",
					Items: &genai.Schema{
						Type: "object",
						Properties: map[string]*genai.Schema{
							"Day":         {Type: "string", Nullable: genai.Ptr(true)},
							"Forecast":    {Type: "string", Nullable: genai.Ptr(true)},
							"Temperature": {Type: "integer", Nullable: genai.Ptr(true)},
							"Humidity":    {Type: "string", Nullable: genai.Ptr(true)},
							"Wind Speed":  {Type: "integer", Nullable: genai.Ptr(true)},
						},
						Required: []string{"Day", "Temperature", "Forecast", "Wind Speed"},
					},
				},
			},
		},
	}

	resp, err := client.Models.GenerateContent(ctx, modelName, contents, config)
	if err != nil {
		return fmt.Errorf("failed to generate content: %w", err)
	}

	respText := resp.Text()

	fmt.Fprintln(w, respText)

	// Example response:
	// {
	// 	"forecast": [
	// 		{"Day": "Sunday", "Forecast": "Sunny", "Temperature": 77, "Wind Speed": 10, "Humidity": "50%"},
	// 		{"Day": "Monday", "Forecast": "Partly Cloudy", "Temperature": 72, "Wind Speed": 15},
	// 		{"Day": "Tuesday", "Forecast": "Rain Showers", "Temperature": 64, "Wind Speed": null, "Humidity": "70%"},
	// 		{"Day": "Wednesday", "Forecast": "Thunderstorms", "Temperature": 68, "Wind Speed": null},
	// 		{"Day": "Thursday", "Forecast": "Cloudy", "Temperature": 66, "Wind Speed": null, "Humidity": "60%"},
	// 		{"Day": "Friday", "Forecast": "Partly Cloudy", "Temperature": 73, "Wind Speed": 12},
	// 		{"Day": "Saturday", "Forecast": "Sunny", "Temperature": 80, "Wind Speed": 8, "Humidity": "40%"}
	// 	]
	// }

	return nil
}

Node.js

Installieren

npm install @google/genai

Weitere Informationen finden Sie in der SDK-Referenzdokumentation.

Umgebungsvariablen für die Verwendung des Gen AI SDK mit Vertex AI festlegen: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True
 

const {GoogleGenAI} = require('@google/genai');

const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;
const GOOGLE_CLOUD_LOCATION = process.env.GOOGLE_CLOUD_LOCATION || 'global';

async function generateNullableSchema(
  projectId = GOOGLE_CLOUD_PROJECT,
  location = GOOGLE_CLOUD_LOCATION
) {
  const client = new GoogleGenAI({
    vertexai: true,
    project: projectId,
    location: location,
  });

  const prompt = `
  The week ahead brings a mix of weather conditions.
  Sunday is expected to be sunny with a temperature of 77°F and a humidity level of 50%. Winds will be light at around 10 km/h.
  Monday will see partly cloudy skies with a slightly cooler temperature of 72°F and the winds will pick up slightly to around 15 km/h.
  Tuesday brings rain showers, with temperatures dropping to 64°F and humidity rising to 70%.
  Wednesday may see thunderstorms, with a temperature of 68°F.
  Thursday will be cloudy with a temperature of 66°F and moderate humidity at 60%.
  Friday returns to partly cloudy conditions, with a temperature of 73°F and the Winds will be light at 12 km/h.
  Finally, Saturday rounds off the week with sunny skies, a temperature of 80°F, and a humidity level of 40%. Winds will be gentle at 8 km/h.
`;

  const responseSchema = {
    type: 'object',
    properties: {
      forecast: {
        type: 'array',
        items: {
          type: 'object',
          properties: {
            Day: {type: 'string', nullable: true},
            Forecast: {type: 'string', nullable: true},
            Temperature: {type: 'integer', nullable: true},
            Humidity: {type: 'string', nullable: true},
            WindSpeed: {type: 'integer', nullable: true},
          },
          required: ['Day', 'Temperature', 'Forecast', 'WindSpeed'],
        },
      },
    },
  };

  const response = await client.models.generateContent({
    model: 'gemini-2.5-flash',
    contents: prompt,
    config: {
      responseMimeType: 'application/json',
      responseSchema: responseSchema,
    },
  });
  console.log(response.text);

  // Example output:
  //  {"forecast": [{"Day": "Sunday", "Forecast": "sunny", "Temperature": 77, "Wind Speed": 10, "Humidity": "50%"},
  //   {"Day": "Monday", "Forecast": "partly cloudy", "Temperature": 72, "Wind Speed": 15},
  //   {"Day": "Tuesday", "Forecast": "rain showers", "Temperature": 64, "Wind Speed": null, "Humidity": "70%"},
  //   {"Day": "Wednesday", "Forecast": "thunderstorms", "Temperature": 68, "Wind Speed": null},
  //   {"Day": "Thursday", "Forecast": "cloudy", "Temperature": 66, "Wind Speed": null, "Humidity": "60%"},
  //   {"Day": "Friday", "Forecast": "partly cloudy", "Temperature": 73, "Wind Speed": 12},
  //   {"Day": "Saturday", "Forecast": "sunny", "Temperature": 80, "Wind Speed": 8, "Humidity": "40%"}]}

  return response.text;
}

Produkt klassifizieren

Das folgende Beispiel enthält Enums, in denen das Modell den Typ und den Zustand eines Objekts anhand einer Liste von angegebenen Werten klassifizieren muss.

Python

Installieren

pip install --upgrade google-genai

Weitere Informationen finden Sie in der SDK-Referenzdokumentation.

Umgebungsvariablen für die Verwendung des Gen AI SDK mit Vertex AI festlegen: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True
 

from google import genai
from google.genai.types import GenerateContentConfig, HttpOptions

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

print(response.text)
# Example output:
# Woodwind

Go

Informationen zum Installieren oder Aktualisieren von Go

Weitere Informationen finden Sie in der SDK-Referenzdokumentation.

Umgebungsvariablen für die Verwendung des Gen AI SDK mit Vertex AI festlegen: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True
 

import (
	"context"
	"fmt"
	"io"

	genai "google.golang.org/genai"
)

// generateWithEnumSchema shows how to use enum schema to generate output.
func generateWithEnumSchema(w io.Writer) error {
	ctx := context.Background()

	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"},
	})
	if err != nil {
		return fmt.Errorf("failed to create genai client: %w", err)
	}

	modelName := "gemini-2.5-flash"
	contents := []*genai.Content{
		{Parts: []*genai.Part{
			{Text: "What type of instrument is an oboe?"},
		}, Role: "user"},
	}
	config := &genai.GenerateContentConfig{
		ResponseMIMEType: "text/x.enum",
		ResponseSchema: &genai.Schema{
			Type: "STRING",
			Enum: []string{"Percussion", "String", "Woodwind", "Brass", "Keyboard"},
		},
	}

	resp, err := client.Models.GenerateContent(ctx, modelName, contents, config)
	if err != nil {
		return fmt.Errorf("failed to generate content: %w", err)
	}

	respText := resp.Text()

	fmt.Fprintln(w, respText)

	// Example response:
	// Woodwind

	return nil
}

Node.js

Installieren

npm install @google/genai

Weitere Informationen finden Sie in der SDK-Referenzdokumentation.

Umgebungsvariablen für die Verwendung des Gen AI SDK mit Vertex AI festlegen: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True
 

const {GoogleGenAI, Type} = require('@google/genai');

const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;
const GOOGLE_CLOUD_LOCATION = process.env.GOOGLE_CLOUD_LOCATION || 'global';

async function generateContent(
  projectId = GOOGLE_CLOUD_PROJECT,
  location = GOOGLE_CLOUD_LOCATION
) {
  const client = new GoogleGenAI({
    vertexai: true,
    project: projectId,
    location: location,
  });

  const responseSchema = {
    type: Type.STRING,
    enum: ['Percussion', 'String', 'Woodwind', 'Brass', 'Keyboard'],
  };

  const response = await client.models.generateContent({
    model: 'gemini-2.5-flash',
    contents: 'What type of instrument is an oboe?',
    config: {
      responseMimeType: 'text/x.enum',
      responseSchema: responseSchema,
    },
  });

  console.log(response.text);
  // Example output:
  //  Woodwind
  return response.text;
}

Java

Informationen zum Installieren oder Aktualisieren von Java

Weitere Informationen finden Sie in der SDK-Referenzdokumentation.

Umgebungsvariablen für die Verwendung des Gen AI SDK mit Vertex AI festlegen: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True
 


import com.google.genai.Client;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.HttpOptions;
import com.google.genai.types.Schema;
import com.google.genai.types.Type;
import java.util.List;

public class ControlledGenerationWithEnumSchema {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String contents = "What type of instrument is an oboe?";
    String modelId = "gemini-2.5-flash";
    generateContent(modelId, contents);
  }

  // Generates content with an enum response schema
  public static String generateContent(String modelId, String contents) {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (Client client =
        Client.builder()
            .location("global")
            .vertexAI(true)
            .httpOptions(HttpOptions.builder().apiVersion("v1").build())
            .build()) {

      // Define the response schema with an enum.
      Schema responseSchema =
          Schema.builder()
              .type(Type.Known.STRING)
              .enum_(List.of("Percussion", "String", "Woodwind", "Brass", "Keyboard"))
              .build();

      GenerateContentConfig config =
          GenerateContentConfig.builder()
              .responseMimeType("text/x.enum")
              .responseSchema(responseSchema)
              .build();

      GenerateContentResponse response = client.models.generateContent(modelId, contents, config);

      System.out.print(response.text());
      // Example response:
      // Woodwind
      return response.text();
    }
  }
}