Strukturierte Ausgaben
Sie können Gemini-Modelle so konfigurieren, dass sie Antworten generieren, die einem bereitgestellten JSON-Schema entsprechen. So werden vorhersagbare, typsichere Ergebnisse erzielt und das Extrahieren strukturierter Daten aus unstrukturiertem Text wird vereinfacht.
Strukturierte Ausgaben eignen sich ideal für:
- Datenextraktion:Bestimmte Informationen wie Namen und Datumsangaben aus Text extrahieren.
- Strukturierte Klassifizierung:Text in vordefinierte Kategorien klassifizieren.
- Agentische Workflows:Strukturierte Eingaben für Tools oder APIs generieren.
Neben der Unterstützung von JSON-Schema in der REST API ermöglichen die Google GenAI SDKs die Definition von Schemas mit Pydantic (Python) und Zod (JavaScript).
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
# This will only work for SDK newer than 2.0.0
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.
"""
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input=prompt,
response_format={
"type": "text",
"mime_type": "application/json",
"schema": Recipe.model_json_schema()
},
)
recipe = Recipe.model_validate_json(interaction.steps[-1].content[0].text)
print(recipe)
JavaScript
// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";
import * as z from "zod";
const recipeJsonSchema = {
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"]
};
const recipeSchema = z.fromJSONSchema(recipeJsonSchema);
const client = 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 interaction = await client.interactions.create({
model: "gemini-3-flash-preview",
input: prompt,
response_format: {
type: 'text',
mime_type: 'application/json',
schema: recipeJsonSchema
},
});
const recipe = recipeSchema.parse(JSON.parse(interaction.steps.at(-1).content[0].text));
console.log(recipe);
REST
# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-H "Api-Revision: 2026-05-20" \
-d '{
"model": "gemini-3-flash-preview",
"input": "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.",
"response_format": {
"type": "text",
"mime_type": "application/json",
"schema": {
"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."
]
}
Ergebnisse streamen
Sie können strukturierte Ausgaben streamen und so mit der Verarbeitung der Antwort beginnen, während sie generiert wird. Die gestreamten Chunks sind gültige partielle JSON-Strings, die verkettet werden können, um das endgültige JSON-Objekt zu bilden.
Python
# This will only work for SDK newer than 2.0.0
from google import genai
from pydantic import BaseModel
from typing import Literal
class Feedback(BaseModel):
sentiment: Literal["positive", "neutral", "negative"]
summary: str
client = genai.Client()
prompt = "The new UI is incredibly intuitive. Add a very long summary to test streaming!"
stream = client.interactions.create(
model="gemini-3-flash-preview",
input=prompt,
response_format={
"type": "text",
"mime_type": "application/json",
"schema": Feedback.model_json_schema()
},
stream=True
)
for event in stream:
if event.event_type == "step.delta" and event.delta.text:
print(event.delta.text, end="")
JavaScript
// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";
import * as z from "zod";
const feedbackJsonSchema = {
type: "object",
properties: {
sentiment: { type: "string", enum: ["positive", "neutral", "negative"] },
summary: { type: "string" }
},
required: ["sentiment", "summary"]
};
const feedbackSchema = z.fromJSONSchema(feedbackJsonSchema);
const client = new GoogleGenAI({});
const stream = await client.interactions.create({
model: "gemini-3-flash-preview",
input: "The new UI is incredibly intuitive. Add a very long summary!",
response_format: {
type: 'text',
mime_type: 'application/json',
schema: feedbackJsonSchema
},
stream: true,
});
for await (const event of stream) {
if (event.type === "step.delta" && event.delta?.text) {
process.stdout.write(event.delta.text);
}
}
Strukturierte Ausgaben mit Tools
Mit Gemini 3 können Sie strukturierte Ausgaben mit integrierten Tools kombinieren, darunter Fundierung mit der Google Suche, URL-Kontext, Codeausführung, Dateisuche und Funktionsaufruf.
Python
# This will only work for SDK newer than 2.0.0
from google import genai
from pydantic import BaseModel, Field
from typing import List
class MatchResult(BaseModel):
winner: str = Field(description="The name of the winner.")
final_match_score: str = Field(description="The final match score.")
scorers: List[str] = Field(description="The name of the scorer.")
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3.1-pro-preview",
input="Search for all details for the latest Euro.",
tools=[{"type": "google_search"}, {"type": "url_context"}],
response_format={
"type": "text",
"mime_type": "application/json",
"schema": MatchResult.model_json_schema()
},
)
result = MatchResult.model_validate_json(interaction.steps[-1].content[0].text)
print(result)
JavaScript
// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";
import * as z from "zod";
const matchJsonSchema = {
type: "object",
properties: {
winner: { type: "string" },
final_match_score: { type: "string" },
scorers: { type: "array", items: { type: "string" } }
},
required: ["winner", "final_match_score", "scorers"]
};
const matchSchema = z.fromJSONSchema(matchJsonSchema);
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
model: "gemini-3.1-pro-preview",
input: "Search for all details for the latest Euro.",
tools: [{type: "google_search"}, {type: "url_context"}],
response_format: {
type: 'text',
mime_type: 'application/json',
schema: matchJsonSchema
},
});
const match = matchSchema.parse(JSON.parse(interaction.steps.at(-1).content[0].text));
console.log(match);
REST
# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-H "Api-Revision: 2026-05-20" \
-d '{
"model": "gemini-3.1-pro-preview",
"input": "Search for all details for the latest Euro.",
"tools": [{"type": "google_search"}, {"type": "url_context"}],
"response_format": {
"type": "text",
"mime_type": "application/json",
"schema": {
"type": "object",
"properties": {
"winner": {"type": "string"},
"final_match_score": {"type": "string"},
"scorers": {"type": "array", "items": {"type": "string"}}
},
"required": ["winner", "final_match_score", "scorers"]
}
}
}'
Unterstützung von JSON-Schemas
Wenn Sie ein JSON-Objekt generieren möchten, konfigurieren Sie response_format mit einem Objekt (oder einem Array, das ein Objekt enthält) vom Typ text und legen Sie mime_type auf application/json fest. Das Schema sollte im Feld schema angegeben werden.
Der Modus für strukturierte Ausgaben 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 „true“- oder „false“-Werte.object: Für strukturierte Daten mit Schlüssel/Wert-Paaren.array: Für Listen von Elementen.null: Wenn ein Attribut 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 inpropertiesaufgefü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.
Strukturierte Ausgaben im Vergleich zu Funktionsaufrufen
| Funktion | Primärer Anwendungsfall |
|---|---|
| Strukturierte Ausgaben | Endgültige Antwort formatieren: Verwenden Sie diese Option, wenn die Antwort des Modells in einem bestimmten Format erfolgen soll. |
| Funktionsaufrufe | Aktionen während der Unterhaltung ausführen: Wird verwendet, wenn das Modell Sie bitten muss, eine Aufgabe auszuführen, bevor es eine endgültige Antwort geben kann. |
Best Practices
- Klare Beschreibungen:Verwenden Sie das Feld
description, um das Modell zu unterstützen. - Starke Typisierung:Verwenden Sie spezifische Typen (
integer,string,enum). - Prompt Engineering:Machen Sie dem Modell deutlich, was es tun soll.
- Validierung:Die Ausgabe ist zwar syntaktisch korrektes JSON, aber Sie sollten die Werte immer in Ihrer Anwendung validieren.
- Fehlerbehandlung:Implementieren Sie eine robuste Fehlerbehandlung für schemakonforme, aber semantisch falsche Ausgaben.
Beschränkungen
- Schema-Teilmengen:Nicht alle JSON-Schemafunktionen werden unterstützt.
- Schema-Komplexität:Sehr große oder tief verschachtelte Schemas werden möglicherweise abgelehnt.