Generowanie uporządkowanych danych wyjściowych za pomocą interfejsu Gemini API

Python Node.js Go Dart (Flutter) Android Swift Web REST

Gemini domyślnie generuje tekst nieustrukturyzowany, ale niektóre aplikacje wymagają tekstu ustrukturyzowanego. W takich przypadkach możesz ograniczyć Gemini do odpowiadania za pomocą danych w formacie JSON, który jest formatem uporządkowanych danych odpowiednim do przetwarzania automatycznego. Możesz też ograniczyć model do odpowiadania jedną z opcji określonych w typie zbiorczym.

Oto kilka przypadków użycia, które mogą wymagać uporządkowanych danych wyjściowych z modelu:

• Utwórz bazę danych firm, pobierając informacje o nich z artykułów prasowych.
• wyodrębniać ze standardowych życiorysów informacje,
• Wyodrębnianie składników z przepisów i wyświetlanie linku do strony internetowej sklepu spożywczego dla każdego składnika.

W promptzie możesz poprosić Gemini o wygenerowanie danych wyjściowych w formacie JSON, ale pamiętaj, że nie ma gwarancji, że model wygeneruje dane w tym formacie. Aby uzyskać bardziej deterministyczną odpowiedź, możesz przekazać konkretny schemat JSON w polu responseSchema, aby Gemini zawsze odpowiadał z oczekiwaną strukturą. Więcej informacji o pracy ze schematami znajdziesz w artykule Więcej informacji o schematach JSON.

Z tego przewodnika dowiesz się, jak wygenerować plik JSON za pomocą metody generateContent w wybranym pakiecie SDK lub bezpośrednio za pomocą interfejsu API REST. Przykłady pokazują dane wejściowe w postaci samego tekstu, ale Gemini może też generować odpowiedzi w formacie JSON na potrzeby żądań multimodalnych, które obejmują obrazy, filmy i dźwięk.

Zanim zaczniesz: skonfiguruj projekt i klucz interfejsu API

Zanim wywołasz interfejs Gemini API, musisz skonfigurować projekt i klucz interfejsu API.

Wygeneruj kod JSON

Gdy model jest skonfigurowany tak, aby zwracać dane w formacie JSON, odpowiada na każdy prompt z danymi w tym formacie.

Możesz kontrolować strukturę odpowiedzi JSON, podając schemat. Schemat można podać modelowi na 2 sposoby:

• Jako tekst w promptach
• Jako uporządkowany schemat dostarczony w ramach konfiguracji modelu

Podanie schematu jako tekstu w promptach

W tym przykładzie model zwraca przepisy na ciasteczka w określonym formacie JSON.

Ponieważ model otrzymuje specyfikację formatu z tekstu w promptzie, możesz mieć pewną swobodę w sposobie jej przedstawienia. Możesz użyć dowolnego formatu, który umożliwia wyświetlanie schematu JSON.

from google import genai

prompt = """List a few popular cookie recipes in JSON format.

Use this JSON schema:

Recipe = {'recipe_name': str, 'ingredients': list[str]}
Return: list[Recipe]"""

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model='gemini-2.0-flash',
    contents=prompt,
)

# Use the response as a JSON string.
print(response.text)

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

[
  {
    "recipe_name": "Chocolate Chip Cookies",
    "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"
    ]
  },
  ...
]

Przekazywanie schematu w ramach konfiguracji modelu

Ten przykład wykonuje następujące czynności:

1. Tworzy instancję modelu skonfigurowanego za pomocą schematu, aby zwracać odpowiedzi w formacie JSON.
2. Prosimy o zwrócenie przepisów na ciasteczka.

Ta bardziej formalna metoda deklarowania schematu JSON zapewnia większą kontrolę niż poleganie tylko na tekście w promptach.

from google import genai
from pydantic import BaseModel


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


client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model='gemini-2.0-flash',
    contents='List a few popular cookie recipes. Be sure to 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

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

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

Składnia definicji schematu

W przypadku odpowiedzi JSON określ schemat w przypadku właściwości response_schema w konfiguracji modelu. Wartość response_schema musi być równa:

• Typ, który jest używany w adnotacji typu. Zapoznaj się z modułem Pythona typing.
• Wystąpienie genai.types.Schema.
• Odpowiednik dict: genai.types.Schema.

Definiowanie schematu za pomocą typu

Najłatwiej zdefiniować schemat za pomocą typu bezpośredniego. W poprzednim przykładzie zastosowaliśmy takie podejście:

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

Biblioteka klienta interfejsu Gemini API w języku Python obsługuje schematy zdefiniowane za pomocą tych typów: (gdzie AllowedType to dowolny dozwolony typ):

• int
• float
• bool
• str
• list[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.
  • Modele Pydantic zdefiniowane przez użytkownika. 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.

Używanie typu zbiorczego do ograniczania danych wyjściowych

W niektórych przypadkach możesz chcieć, aby model wybrał jedną opcję z listy opcji. Aby zaimplementować to zachowanie, możesz przekazać w schemacie typ enum. Opcji enum możesz używać wszędzie tam, gdzie można użyć wartości str w elementach response_schema, ponieważ enum to lista ciągów znaków. Podobnie jak schemat JSON, typ enumeracji umożliwia ograniczenie danych wyjściowych modelu, aby spełniały wymagania 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ć sobie to zadanie, możesz utworzyć typ wyliczeniowy.

W tym przykładzie przekazujesz klasę enum Instrument jako response_schema, a model powinien wybrać najbardziej odpowiednią opcję enum.

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

Pakiet Python SDK przetłumaczy deklaracje typów dla interfejsu API. Interfejs API obsługuje jednak podzbiór schematu OpenAPI 3.0 (Schemat). 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 zadań wielokrotnego wyboru możesz używać enum w dowolnym miejscu w schemacie do wywoływania funkcji lub JSON. Możesz na przykład poprosić model o listę tytułów przepisów i użyć enumeracji Grade, aby przypisać każdemu tytułowi stopień 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 cookies and give them grades based on tastiness.',
    config={
        'response_mime_type': 'application/json',
        'response_schema': list[Recipe],
    },
)

print(response.text)
# [{"rating": "a+", "recipe_name": "Classic Chocolate Chip Cookies"}, ...]

Więcej informacji o schematach JSON

Gdy skonfigurujesz model tak, aby zwracał odpowiedź w formacie JSON, możesz użyć obiektu Schema do zdefiniowania kształtu danych JSON. Obiekt Schema reprezentuje wybrany podzbiór obiektów schematu OpenAPI 3.0.

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

{
  "type": enum (Type),
  "format": string,
  "description": string,
  "nullable": boolean,
  "enum": [
    string
  ],
  "maxItems": string,
  "minItems": string,
  "properties": {
    string: {
      object (Schema)
    },
    ...
  },
  "required": [
    string
  ],
  "propertyOrdering": [
    string
  ],
  "items": {
    object (Schema)
  }
}

Type schematu musi być jednym z typów danych OpenAPI. W przypadku każdego elementu Type ważny jest tylko podzbiór pól. Na liście poniżej każdy typ Type jest powiązany z odpowiednimi polami:

• string -> enum, format
• integer -> format
• number -> format
• bool
• array -> minItems, maxItems, items
• object -> właściwości, wymagane, propertyOrdering, nullable

Oto kilka przykładowych schematów pokazujących prawidłowe kombinacje typu i pola:

{ "type": "string", "enum": ["a", "b", "c"] }

{ "type": "string", "format": "date-time" }

{ "type": "integer", "format": "int64" }

{ "type": "number", "format": "double" }

{ "type": "bool" }

{ "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 są one 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": ["recipe_name", "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 właściwościami w tej samej kolejności, możesz potencjalnie poprawić jakość wyników.