Uporządkowane dane wyjściowe

Możesz skonfigurować Gemini tak, aby zamiast nieuporządkowanego tekstu generował on uporządkowany tekst wyjściowy, co umożliwia dokładne wyodrębnianie i standardyzowanie informacji na potrzeby dalszego przetwarzania. Możesz na przykład użyć uporządkowanego wyjścia, aby wyodrębnić informacje z CV i ujednolicić je w celu utworzenia uporządkowanej bazy danych.

Gemini może generować dane wyjściowe w postaci JSON lub wartości typu wyliczeniowego.

Generowanie pliku JSON

Istnieją 2 sposoby generowania pliku JSON za pomocą interfejsu Gemini API:

• Konfigurowanie schematu w modelu
• Podanie schematu w promptach tekstowych

Konfigurowanie schematu w modelu to zalecany sposób generowania danych w formacie JSON, ponieważ ogranicza model do generowania danych w tym formacie.

Konfigurowanie schematu (zalecane)

Aby ograniczyć model do generowania danych w formacie JSON, skonfiguruj responseSchema. Model będzie wtedy odpowiadać na dowolny prompt, zwracając dane wyjściowe w formacie JSON.

from google import genai
from pydantic import BaseModel

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

client = genai.Client(api_key="GOOGLE_API_KEY")
response = client.models.generate_content(
    model="gemini-2.0-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

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

const ai = new GoogleGenAI({ "GOOGLE_API_KEY" });

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-2.0-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();

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, &genai.ClientConfig{
        APIKey:  "GOOGLE_API_KEY",
        Backend: genai.BackendGeminiAPI,
    })
    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.0-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())
}

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GOOGLE_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

Dane wyjściowe mogą wyglądać tak:

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

Podanie schematu w promptach tekstowych

Zamiast konfigurować schemat, możesz podać go w naturalnym języku lub w pseudokodzie w prośbie tekstowej. Nie zalecamy tej metody, ponieważ może ona generować dane wyjściowe o gorszej jakości, a model nie jest ograniczony do przestrzegania schematu.

Oto ogólny przykład schematu podanego w promptach tekstowych:

List a few popular cookie recipes, and include the amounts of ingredients.

Produce JSON matching this specification:

Recipe = { "recipeName": string, "ingredients": array<string> }
Return: array<Recipe>

Ponieważ model otrzymuje schemat z tekstu w promptach, możesz mieć pewną elastyczność w sposobie jego reprezentowania. Gdy jednak podasz schemat w postaci inline, jak w tym przykładzie, model nie będzie musiał zwracać danych w formacie JSON. Aby uzyskać bardziej deterministyczne odpowiedzi o wyższej jakości, skonfiguruj schemat na modelu i nie powielaj go w promptach tekstowych.

Generowanie wartości typu wyliczeniowego

W niektórych przypadkach możesz chcieć, aby model wybrał jedną opcję z listy opcji. Aby wdrożyć to zachowanie, możesz przekazać w schemacie typ enum. Opcji wyliczeniowej możesz używać wszędzie tam, gdzie w elementach string możesz użyć wartości string, ponieważ wyliczenie to tablica ciągów znaków.responseSchema Podobnie jak schemat JSON, enumeracja umożliwia ograniczenie danych wyjściowych modelu do wymagań aplikacji.

Załóżmy na przykład, że tworzysz aplikację do klasyfikowania instrumentów muzycznych do jednej z 5 kategorii: "Percussion", "String", "Woodwind", "Brass" lub „"Keyboard"”. Aby ułatwić to zadanie, możesz utworzyć typ wyliczeniowy.

W tym przykładzie jako parametr responseSchema przekazujesz typ enumeracji, co ogranicza model do wyboru najbardziej odpowiedniej opcji.

from google import genai
import enum

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

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

print(response.text)
# Woodwind

Biblioteka Pythona przetłumaczy deklaracje typów interfejsu API. Interfejs API akceptuje jednak podzbiór schematu OpenAPI 3.0 (Schemat).

Wyliczenie można określić na 2 inne sposoby. Możesz użyć Literal:

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

Możesz też przekazać schemat w formacie JSON:

from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model='gemini-2.0-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

Oprócz podstawowych problemów z wieloma odpowiedziami możesz używać enumeracji w dowolnym miejscu w schemacie JSON. Możesz na przykład poprosić model o listę tytułów przepisów i użyć enumeracji Grade, aby nadać każdemu tytułowi ocenę popularności:

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(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model='gemini-2.0-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)

Odpowiedź może wyglądać tak:

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

Informacje o schematach JSON

Konfigurowanie modelu na potrzeby generowania danych wyjściowych w formacie JSON za pomocą parametru responseSchema polega na definiowaniu jego struktury za pomocą obiektu Schema. Ten obiekt reprezentuje wybrany podzbiór obiektu Schema OpenAPI 3.0, a także dodaje pole propertyOrdering.

Oto reprezentacja w pseudo-formacie JSON wszystkich pól Schema:

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

Type schematu musi być jednym z typów danych OpenAPI lub ich unionem (za pomocą anyOf). W przypadku każdego Type prawidłowy jest tylko podzbiór pól. Poniższa lista mapuje każdy typ Type na podzbiór pól, które są prawidłowe w przypadku tego typu:

• 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

Oto kilka przykładowych schematów z prawidłowymi kombinacjami typu i pola:

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

Pełną dokumentację pól schematu, które są używane w Gemini API, znajdziesz w dokumentacji schematu.

Sortowanie obiektów

Gdy pracujesz z schematami JSON w interfejsie Gemini API, ważna jest kolejność właściwości. Domyślnie interfejs API sortuje właściwości alfabetycznie i nie zachowuje kolejności, w jakiej zostały zdefiniowane (chociaż pakiety SDK Google Gen AI mogą zachować tę kolejność). Jeśli przekazujesz modelowi przykłady z skonfigurowanym schematem, a kolejność właściwości przykładów nie jest zgodna z kolejnością właściwości schematu, wynik może być niejasny lub nieoczekiwany.

Aby zapewnić spójne i przewidywalne sortowanie właściwości, możesz użyć opcjonalnego pola propertyOrdering[].

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

propertyOrdering[] – nie jest to standardowe pole w specyfikacji OpenAPI – to tablica ciągów znaków służąca do określania kolejności właściwości w odpowiedzi. Określając kolejność właściwości, a następnie podając przykłady z tymi samymi właściwościami, możesz potencjalnie poprawić jakość wyników. propertyOrdering jest obsługiwana tylko wtedy, gdy types.Schema jest tworzona ręcznie.

Schematy w Pythonie

Jeśli używasz biblioteki Python, wartość response_schema musi być jedną z tych:

• typ, który używasz w adnotacji typu (patrz modułtyping w Pythonie);
• Przykład: genai.types.Schema
• dict równowartość genai.types.Schema

Najprostszym sposobem zdefiniowania schematu jest użycie typu Pydantic (jak w poprzednim przykładzie):

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

Gdy używasz typu Pydantic, biblioteka Pythona tworzy dla Ciebie schemat JSON i wysyła go do interfejsu API. Dodatkowe przykłady znajdziesz w dokumentacji biblioteki Pythona.

Biblioteka Pythona obsługuje schematy zdefiniowane za pomocą tych typów (gdzie AllowedType to dowolny dozwolony typ):

• int
• float
• bool
• str
• list[AllowedType]
• AllowedType|AllowedType|...
• W przypadku typów uporządkowanych:
  • dict[str, AllowedType]. Ta adnotacja deklaruje, że wszystkie wartości w słowniku mają ten sam typ, ale nie określa, które klucze powinny być uwzględnione.
  • Zdefiniowane przez użytkownika modele analityczne. Dzięki temu możesz określić nazwy kluczy i zdefiniować różne typy wartości powiązanych z poszczególnymi kluczami, w tym struktury zagnieżdżone.

Obsługa schematu JSON

Schemat JSON to nowsza specyfikacja niż OpenAPI 3.0, na której opiera się obiekt Schema. Obsługa schematu JSON jest dostępna jako podgląd za pomocą pola responseJsonSchema, które akceptuje dowolny schemat JSON z tymi ograniczeniami:

• Działa tylko z Gemini 2.5.
• Wszystkie właściwości schematu JSON mogą być przekazywane, ale nie wszystkie są obsługiwane. Aby dowiedzieć się więcej, zapoznaj się z dokumentacją dotyczącą tego pola.
• Rekurencja może być używana tylko jako wartość niewymaganej właściwości obiektu.
• Odwołania rekurencyjne są rozwijane do określonego stopnia w zależności od rozmiaru schematu.
• Schematy zawierające $ref nie mogą zawierać żadnych właściwości innych niż te, które zaczynają się od $.

Oto przykład generowania schematu JSON za pomocą Pydantic i przesyłania go do modelu:

curl "https://generativelanguage.googleapis.com/v1alpha/models/\
gemini-2.5-flash-preview-05-20:generateContent?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

Przekazywanie schematu JSON bezpośrednio nie jest jeszcze obsługiwane w pakiecie SDK.

Sprawdzone metody

Podczas korzystania ze schematu odpowiedzi pamiętaj o tych kwestiach i zaleceniach:

• Rozmiar schematu odpowiedzi jest wliczany do limitu tokenów wejściowych.
• Domyślnie pola są opcjonalne, co oznacza, że model może je wypełnić lub pominąć. Możesz ustawić pola jako wymagane, aby wymusić podanie wartości przez model. Jeśli w powiązanym promptzie jest niewystarczający kontekst, model generuje odpowiedzi głównie na podstawie danych, na których był trenowany.

• Złożony schemat może spowodować błąd InvalidArgument: 400. Złożoność może wynikać z długich nazw właściwości, długich limitów długości tablic, typów enumeracji z wiele wartościami, obiektów z wiele opcjonalnych właściwości lub kombinacji tych czynników.

  Jeśli ten błąd wystąpi w przypadku prawidłowego schematu, wprowadź co najmniej jedną z tych zmian, aby go naprawić:

  • Skróć nazwy właściwości lub nazwy typów.
  • spłaszczyć zagnieżdżone tablice.
  • Zmniejsz liczbę właściwości z ograniczeniami, takimi jak liczby z minimalnymi i maksymalnymi limitami.
  • Zmniejsz liczbę właściwości z zaawansowanymi ograniczeniami, np. właściwości z zaawansowanymi formatami, takimi jak date-time.
  • Zmniejsz liczbę właściwości opcjonalnych.
  • Zmniejsz liczbę prawidłowych wartości w przypadku typów wyliczeniowych.

• Jeśli nie widzisz oczekiwanych wyników, dodaj więcej kontekstu do promptów dotyczących danych wejściowych lub zmodyfikuj schemat odpowiedzi. Możesz na przykład sprawdzić odpowiedź modelu bez danych wyjściowych w formacie ustrukturyzowanym, aby zobaczyć, jak model reaguje. Następnie możesz zaktualizować schemat odpowiedzi, aby lepiej pasował do danych wyjściowych modelu.

Co dalej?

Teraz, gdy już wiesz, jak generować uporządkowane dane wyjściowe, możesz spróbować użyć narzędzi interfejsu Gemini API:

• Wywoływanie funkcji
• Wykonanie kodu
• Grounding z użyciem wyszukiwarki Google