Dane wyjściowe uporządkowane

Modele Gemini możesz skonfigurować tak, aby generowały odpowiedzi zgodne z podanym schematem JSON. Zapewnia to przewidywalne i bezpieczne typowo wyniki oraz upraszcza wyodrębnianie uporządkowanych danych z nieustrukturyzowanego tekstu.

Używanie uporządkowanych danych wyjściowych jest idealne w tych przypadkach:

  • Wyodrębnianie danych: pobieranie z tekstu konkretnych informacji, takich jak imiona i nazwiska oraz daty.
  • Uporządkowana klasyfikacja: klasyfikowanie tekstu według wstępnie zdefiniowanych kategorii.
  • Przepływy pracy agenta: generowanie uporządkowanych danych wejściowych dla narzędzi lub interfejsów API.

Oprócz obsługi schematu JSON w interfejsie REST API, pakiety SDK Google GenAI ułatwiają definiowanie schematów za pomocą Pydantic (Python) i Zod (JavaScript).

Ten przykład pokazuje, jak wyodrębniać uporządkowane dane 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-3-flash-preview",
    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-3-flash-preview",
  contents: prompt,
  config: {
    responseMimeType: "application/json",
    responseJsonSchema: zodToJsonSchema(recipeSchema),
  },
});

const recipe = recipeSchema.parse(JSON.parse(response.text));
console.log(recipe);

Go

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-3-flash-preview",
        genai.Text(prompt),
        config,
    )
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(result.Text())
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview: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 uporządkowane dane wyjściowe, co pozwala na rozpoczęcie przetwarzania odpowiedzi w trakcie jej generowania, bez konieczności czekania na zakończenie całego procesu. Może to poprawić postrzeganą wydajność aplikacji.

Przesyłane 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-3-flash-preview",
    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-3-flash-preview",
  contents: prompt,
  config: {
    responseMimeType: "application/json",
    responseJsonSchema: zodToJsonSchema(feedbackSchema),
  },
});

for await (const chunk of stream) {
  console.log(chunk.candidates[0].content.parts[0].text)
}

Uporządkowane dane wyjściowe z narzędziami

Gemini 3 umożliwia łączenie uporządkowanych danych wyjściowych z wbudowanymi narzędziami, takimi jak powiązanie ze źródłem informacji przy użyciu wyszukiwarki Google, kontekst adresu URL, wykonywanie kodu, wyszukiwanie plików i wywoływanie funkcji.

Python

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

response = client.models.generate_content(
    model="gemini-3.1-pro-preview",
    contents="Search for all details for the latest Euro.",
    config={
        "tools": [
            {"google_search": {}},
            {"url_context": {}}
        ],
        "response_mime_type": "application/json",
        "response_json_schema": MatchResult.model_json_schema(),
    },  
)

result = MatchResult.model_validate_json(response.text)
print(result)

JavaScript

import { GoogleGenAI } from "@google/genai";
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";

const ai = new GoogleGenAI({});

const matchSchema = z.object({
  winner: z.string().describe("The name of the winner."),
  final_match_score: z.string().describe("The final score."),
  scorers: z.array(z.string()).describe("The name of the scorer.")
});

async function run() {
  const response = await ai.models.generateContent({
    model: "gemini-3.1-pro-preview",
    contents: "Search for all details for the latest Euro.",
    config: {
      tools: [
        { googleSearch: {} },
        { urlContext: {} }
      ],
      responseMimeType: "application/json",
      responseJsonSchema: zodToJsonSchema(matchSchema),
    },
  });

  const match = matchSchema.parse(JSON.parse(response.text));
  console.log(match);
}

run();

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [{"text": "Search for all details for the latest Euro."}]
    }],
    "tools": [
      {"googleSearch": {}},
      {"urlContext": {}}
    ],
    "generationConfig": {
        "responseMimeType": "application/json",
        "responseJsonSchema": {
            "type": "object",
            "properties": {
                "winner": {"type": "string", "description": "The name of the winner."},
                "final_match_score": {"type": "string", "description": "The final score."},
                "scorers": {
                    "type": "array",
                    "items": {"type": "string"},
                    "description": "The name of the scorer."
                }
            },
            "required": ["winner", "final_match_score", "scorers"]
        }
    }
  }'

Obsługa schematu JSON

Aby wygenerować obiekt JSON, ustaw response_mime_type w konfiguracji generowania na application/json i podaj response_json_schema. Schemat musi być prawidłowym schematem JSON, który opisuje żądany format danych wyjściowych.

Model wygeneruje wtedy odpowiedź, która jest syntaktycznie prawidłowym ciągiem JSON zgodnym z podanym schematem. W przypadku używania uporządkowanych danych wyjściowych model będzie generować dane wyjściowe w tej samej kolejności co klucze w schemacie.

Tryb uporządkowanych danych wyjściowych Gemini obsługuje podzbiór specyfikacji schematu JSON.

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 elementów.
  • null: aby zezwolić na wartość null właściwości, dodaj "null" do tablicy typów (np. {"type": ["string", "null"]}).

Te właściwości opisowe pomagają modelowi:

  • title: krótki opis właściwości.
  • description: dłuższy i bardziej szczegółowy opis właściwości.

Właściwości specyficzne dla typu

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, która zawiera listę właściwości obowiązkowych.
  • additionalProperties: określa, czy właściwości nieuwzględnione w properties są dozwolone. Może to być wartość logiczna lub schemat.

W przypadku wartości string:

  • enum: zawiera listę konkretnych 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ę konkretnych możliwych wartości liczbowych.
  • minimum: minimalna wartość włącznie.
  • maximum: maksymalna wartość włącznie.

W przypadku wartości array values:

  • items: określa schemat wszystkich elementów w tablicy.
  • prefixItems: określa 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 modelu

Uporządkowane dane wyjściowe są obsługiwane przez te modele:

Model Uporządkowane dane wyjściowe
Gemini 3.1 Pro (wersja testowa) ✔️
Gemini 3 Flash (wersja testowa) ✔️
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 w przypadku Gemini 2.0 wymagana jest wyraźna lista propertyOrdering w danych wejściowych JSON, aby zdefiniować preferowaną strukturę. Przykład znajdziesz w tym przewodniku.

Uporządkowane dane wyjściowe a wywoływanie funkcji

Zarówno uporządkowane dane wyjściowe, jak i wywoływanie funkcji używają schematów JSON, ale służą do różnych celów:

Funkcja Główny przypadek użycia
Uporządkowane dane wyjściowe Formatowanie ostatecznej odpowiedzi dla użytkownika. Używaj tej funkcji, 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żywaj tej funkcji, gdy model musi poprosić Cię o wykonanie zadania (np. „pobierz aktualną pogodę”), zanim będzie mógł udzielić ostatecznej odpowiedzi.

Sprawdzone metody

  • Jasne opisy: użyj pola description w schemacie, aby podać modelowi jasne instrukcje dotyczące tego, co reprezentuje każda właściwość. Jest to kluczowe w przypadku kierowania danymi wyjściowymi modelu.
  • Silne typowanie: jeśli to możliwe, używaj konkretnych typów (integer, string, enum). Jeśli parametr ma ograniczony zestaw prawidłowych wartości, użyj enum.
  • Inżynieria promptów: w prompcie jasno określ, co ma zrobić model. Na przykład „Wyodrębnij z tekstu te informacje…” lub „Sklasyfikuj tę opinię zgodnie z podanym schematem…”.
  • Weryfikacja: uporządkowane dane wyjściowe gwarantują syntaktycznie prawidłowy kod JSON, ale nie gwarantują, że wartości są semantycznie poprawne. Zawsze sprawdzaj ostateczne dane wyjściowe w kodzie aplikacji, zanim ich użyjesz.
  • Obsługa błędów: zaimplementuj w aplikacji niezawodną obsługę błędów, aby prawidłowo zarządzać przypadkami, w których dane wyjściowe modelu, choć 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 odrzucić bardzo duże lub głęboko zagnieżdżone schematy. Jeśli wystąpią błędy, spróbuj uprościć schemat, skracając nazwy właściwości, zmniejszając zagnieżdżenie lub ograniczając liczbę ograniczeń.