Możesz skonfigurować modele Gemini tak, aby generowały odpowiedzi zgodne z podanym schematem JSON. Ta funkcja gwarantuje przewidywalne i łatwe do przeanalizowania wyniki, zapewnia bezpieczeństwo formatu i typu, umożliwia programowe wykrywanie odmów i upraszcza tworzenie promptów.
Korzystanie z danych strukturalnych jest idealne w przypadku wielu zastosowań:
- Wyodrębnianie danych: pobieranie konkretnych informacji z nieustrukturyzowanego tekstu, np. wyodrębnianie nazwisk, dat i kwot z faktury.
- Klasyfikacja strukturalna: klasyfikowanie tekstu według wstępnie zdefiniowanych kategorii i przypisywanie etykiet strukturalnych, np. kategoryzowanie opinii klientów według nastawienia i tematu.
- Przepływy pracy oparte na agentach: generowanie uporządkowanych danych, które można wykorzystać do wywoływania innych narzędzi lub interfejsów API, np. do tworzenia karty postaci w grze lub wypełniania formularza.
Oprócz obsługi schematu JSON w interfejsie REST API pakiety Google GenAI SDK dla Pythona i JavaScriptu ułatwiają też definiowanie schematów obiektów odpowiednio za pomocą bibliotek Pydantic i Zod. Poniższy przykład pokazuje, jak wyodrębnić informacje z nieustrukturyzowanego tekstu zgodnego ze schematem zdefiniowanym w kodzie.
Ten przykład pokazuje, jak wyodrębniać dane strukturalne z tekstu za pomocą podstawowych typów schematu JSON, takich jak object, array, string i 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);
Przeczytaj
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"]
}
}
}'
Przykładowa odpowiedź:
{
"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
Możesz przesyłać strumieniowo dane wyjściowe w formacie strukturalnym, co pozwala rozpocząć przetwarzanie odpowiedzi w trakcie jej generowania bez konieczności czekania na zakończenie całego procesu. Może to poprawić postrzeganą wydajność aplikacji.
Przesyłane strumieniowo fragmenty będą prawidłowymi częściowymi ciągami JSON, które można połączyć, aby utworzyć ostateczny, kompletny obiekt JSON.
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)
}
Obsługa schematu JSON
Aby wygenerować obiekt JSON, ustaw w konfiguracji generowania wartość response_mime_type na application/json i podaj response_json_schema. Schemat musi być prawidłowym schematem JSON, który opisuje żądany format wyjściowy.
Model wygeneruje odpowiedź, która jest poprawnym składniowo ciągiem JSON zgodnym z podanym schematem. W przypadku danych wyjściowych w formacie strukturalnym model generuje dane wyjściowe w tej samej kolejności co klucze w schemacie.
Tryb danych wyjściowych w formacie strukturalnym Gemini obsługuje podzbiór specyfikacji JSON Schema.
Obsługiwane są te wartości type:
string: w przypadku tekstu.number: w przypadku liczb zmiennoprzecinkowych.integer: w przypadku liczb całkowitych.boolean: w przypadku wartości prawda/fałsz.object: w przypadku uporządkowanych danych z parami klucz–wartość.array: w przypadku list produktów.null: aby zezwolić na wartość null w usłudze, w tablicy typów umieść"null"(np.{"type": ["string", "null"]}).
Te właściwości opisowe pomagają w trenowaniu modelu:
title: krótki opis właściwości.description: dłuższy i bardziej szczegółowy opis nieruchomości.
Właściwości związane z typem
W przypadku wartości object:
properties: obiekt, w którym każdy klucz jest nazwą właściwości, a każda wartość jest schematem tej właściwości.required: tablica ciągów znaków zawierająca listę właściwości, które są obowiązkowe.additionalProperties: określa, czy dozwolone są właściwości, których nie ma na liścieproperties. Może to być wartość logiczna lub schemat.
W przypadku wartości string:
enum: zawiera konkretny zestaw możliwych ciągów znaków w przypadku zadań klasyfikacji.format: określa składnię ciągu znaków, np.date-time,date,time.
W przypadku wartości number i integer:
enum: zawiera listę określonego zbioru możliwych wartości liczbowych.minimum: minimalna wartość włącznie.maximum: maksymalna wartość włącznie.
W przypadku wartości array:
items: określa schemat wszystkich elementów w tablicy.prefixItems: definiuje listę schematów dla pierwszych N elementów, co umożliwia tworzenie struktur podobnych do krotek.minItems: minimalna liczba elementów w tablicy.maxItems: maksymalna liczba elementów w tablicy.
Obsługa modeli
Dane wyjściowe w formacie strukturalnym są obsługiwane przez te modele:
| Model | Uporządkowane dane wyjściowe |
|---|---|
| Gemini 2.5 Pro | ✔️ |
| Gemini 2.5 Flash | ✔️ |
| Gemini 2.5 Flash-Lite | ✔️ |
| Gemini 2.0 Flash | ✔️* |
| Gemini 2.0 Flash-Lite | ✔️* |
* Pamiętaj, że Gemini 2.0 wymaga w danych wejściowych JSON jawnej listy propertyOrdering, która określa preferowaną strukturę. Przykład znajdziesz w tym przepisie.
Uporządkowane dane wyjściowe a wywoływanie funkcji
Zarówno dane wyjściowe w formacie strukturalnym, jak i wywoływanie funkcji korzystają ze schematów JSON, ale służą różnym celom:
| Funkcja | Główny przypadek użycia |
|---|---|
| Ustrukturyzowane dane wyjściowe | Formatowanie ostatecznej odpowiedzi dla użytkownika. Używaj tego parametru, gdy chcesz, aby odpowiedź modelu była w określonym formacie (np. wyodrębnianie danych z dokumentu w celu zapisania ich w bazie danych). |
| Wywoływanie funkcji | Podejmowanie działań podczas rozmowy. Użyj tego ustawienia, gdy model ma poprosić Cię o wykonanie zadania (np. „get current weather” (pobierz aktualną pogodę), zanim będzie mogła podać ostateczną odpowiedź. |
Sprawdzone metody
- Jasne opisy: użyj pola
descriptionw schemacie, aby podać modelowi jasne instrukcje dotyczące tego, co reprezentuje każda właściwość. Ma to kluczowe znaczenie dla wyników modelu. - Silne typowanie: w miarę możliwości używaj konkretnych typów (
integer,string,enum). Jeśli parametr ma ograniczony zbiór prawidłowych wartości, użyjenum. - Inżynieria promptów: w prompcie jasno określ, co ma zrobić model. Na przykład „Wyodrębnij z tekstu te informacje…” lub „Skategoryzuj tę opinię zgodnie z podanym schematem…”.
- Weryfikacja: chociaż dane wyjściowe w formacie strukturalnym gwarantują poprawność składniową JSON, nie gwarantują poprawności semantycznej wartości. Zanim użyjesz ostatecznego wyniku, zawsze sprawdź go w kodzie aplikacji.
- Obsługa błędów: wdróż w aplikacji solidną obsługę błędów, aby sprawnie zarządzać przypadkami, w których dane wyjściowe modelu, mimo że są zgodne ze schematem, mogą nie spełniać wymagań logiki biznesowej.
Ograniczenia
- Podzbiór schematu: nie wszystkie funkcje specyfikacji schematu JSON są obsługiwane. Model ignoruje nieobsługiwane właściwości.
- Złożoność schematu: interfejs API może odrzucać bardzo duże lub głęboko zagnieżdżone schematy. Jeśli napotkasz błędy, spróbuj uprościć schemat, skracając nazwy właściwości, zmniejszając zagnieżdżenie lub ograniczając liczbę ograniczeń.