Możesz skonfigurować Gemini tak, aby generował dane strukturalne zamiast tekstu bez struktury. Umożliwi to precyzyjne wyodrębnianie i standaryzowanie informacji do dalszego przetwarzania. Możesz na przykład użyć danych wyjściowych w formacie strukturalnym, aby wyodrębnić informacje z CV i ujednolicić je w celu utworzenia strukturalnej bazy danych.
Gemini może generować dane wyjściowe w formacie JSON lub wartości wyliczeniowe.
Generowanie kodu JSON
Aby ograniczyć model do generowania JSON, skonfiguruj responseSchema. Model będzie wtedy odpowiadać na wszystkie prompty danymi wyjściowymi w formacie JSON.
Python
from google import genai from pydantic import BaseModel class Recipe(BaseModel): recipe_name: str ingredients: list[str] client = genai.Client() response = client.models.generate_content( model="gemini-2.5-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 JavaScript
import { GoogleGenAI, Type } from "@google/genai"; const ai = new GoogleGenAI({}); async function main() { const response = await ai.models.generateContent({ model: "gemini-2.5-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(); 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) } 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.5-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()) } 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' \ -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" ] }, ... ] Generowanie wartości typu wyliczeniowego
W niektórych przypadkach możesz chcieć, aby model wybrał jedną opcję z listy. Aby zaimplementować to działanie, możesz przekazać w schemacie wyliczenie. Opcji typu wyliczeniowego możesz używać wszędzie tam, gdzie w responseSchema można użyć string, ponieważ typ wyliczeniowy to tablica ciągów znaków. Podobnie jak schemat JSON, wyliczenie umożliwia ograniczenie danych wyjściowych modelu w celu spełnienia wymagań aplikacji.
Załóżmy na przykład, że tworzysz aplikację do klasyfikowania instrumentów muzycznych w jednej z 5 kategorii: "Percussion", "String", "Woodwind", "Brass" lub „"Keyboard"”. Możesz utworzyć wyliczenie, które ułatwi Ci to zadanie.
W poniższym przykładzie przekazujesz wyliczenie jako responseSchema, ograniczając model do wyboru najbardziej odpowiedniej opcji.
Python
from google import genai import enum class Instrument(enum.Enum): PERCUSSION = "Percussion" STRING = "String" WOODWIND = "Woodwind" BRASS = "Brass" KEYBOARD = "Keyboard" client = genai.Client() response = client.models.generate_content( model='gemini-2.5-flash', contents='What type of instrument is an oboe?', config={ 'response_mime_type': 'text/x.enum', 'response_schema': Instrument, }, ) print(response.text) # Woodwind JavaScript
import { GoogleGenAI, Type } from "@google/genai"; const ai = new GoogleGenAI({}); const response = await ai.models.generateContent({ model: "gemini-2.5-flash", contents: "What type of instrument is an oboe?", config: { responseMimeType: "text/x.enum", responseSchema: { type: Type.STRING, enum: ["Percussion", "String", "Woodwind", "Brass", "Keyboard"], }, }, }); console.log(response.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' \ -d '{ "contents": [{ "parts":[ { "text": "What type of instrument is an oboe?" } ] }], "generationConfig": { "responseMimeType": "text/x.enum", "responseSchema": { "type": "STRING", "enum": ["Percussion", "String", "Woodwind", "Brass", "Keyboard"] } } }' Biblioteka Pythona przetłumaczy deklaracje typów dla interfejsu API. Interfejs API akceptuje jednak podzbiór schematu OpenAPI 3.0 (Schema).
Wyliczenie można określić na 2 inne sposoby. Możesz użyć tego symbolu:Literal:```
Python
Literal["Percussion", "String", "Woodwind", "Brass", "Keyboard"] Możesz też przekazać schemat jako JSON:
Python
from google import genai client = genai.Client() response = client.models.generate_content( model='gemini-2.5-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ć wyliczenia w dowolnym miejscu schematu JSON. Możesz na przykład poprosić model o listę tytułów przepisów i użyć wyliczenia Grade, aby przypisać każdemu tytułowi ocenę popularności:
Python
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() response = client.models.generate_content( model='gemini-2.5-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 pod kątem danych wyjściowych w formacie JSON za pomocą parametru responseSchema opiera się na obiekcie Schema, który definiuje jego strukturę. Ten obiekt reprezentuje wybrany podzbiór obiektu schematu OpenAPI 3.0 i dodaje pole propertyOrdering.
Oto pseudoreprezentacja 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) } } Pole Type schematu musi być jednym z typów danych OpenAPI lub sumą tych typów (przy użyciu anyOf). W przypadku każdego pola Type prawidłowy jest tylko podzbiór pól. Na poniższej liście znajdziesz przyporządkowanie każdego Type do podzbioru pól, które są prawidłowe w przypadku tego typu:
string->enum,format,nullableinteger->format,minimum,maximum,enum,nullablenumber->format,minimum,maximum,enum,nullableboolean->nullablearray->minItems,maxItems,items,nullableobject->properties,required,propertyOrdering,nullable
Oto przykładowe schematy pokazujące prawidłowe kombinacje typów i pól:
{ "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 używanych w interfejsie Gemini API znajdziesz w dokumentacji schematu.
Zamawianie nieruchomości
Podczas pracy ze schematami JSON w interfejsie Gemini API kolejność właściwości ma znaczenie. Domyślnie interfejs API porządkuje właściwości alfabetycznie i nie zachowuje kolejności, w jakiej zostały zdefiniowane (chociaż pakiety SDK Google Gen AI mogą zachowywać tę kolejność). Jeśli podajesz przykłady do modelu ze skonfigurowanym schematem, a kolejność właściwości w przykładach nie jest zgodna z kolejnością właściwości w schemacie, dane wyjściowe mogą być niespójne lub nieoczekiwane.
Aby zapewnić spójne i przewidywalne sortowanie właściwości, możesz użyć opcjonalnego pola propertyOrdering[].
"propertyOrdering": ["recipeName", "ingredients"] propertyOrdering[] – nie jest standardowym polem w specyfikacji OpenAPI; jest to tablica ciągów znaków używana 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 właściwościami w tej samej kolejności, możesz potencjalnie poprawić jakość wyników. propertyOrdering jest obsługiwane tylko wtedy, gdy ręcznie tworzysz types.Schema.
Schematy w Pythonie
Jeśli używasz biblioteki Python, wartość response_schema musi być jedną z tych wartości:
- Typ, którego używasz w adnotacji typu (patrz moduł Python
typing). - Instancja
genai.types.Schema - Równowartość
genai.types.Schemawdict
Najprostszym sposobem na zdefiniowanie schematu jest użycie typu Pydantic (jak w poprzednim przykładzie):
Python
config={'response_mime_type': 'application/json', 'response_schema': list[Recipe]} Gdy używasz typu Pydantic, biblioteka Pythona tworzy schemat JSON i wysyła go do interfejsu API. Więcej przykładów znajdziesz w dokumentacji biblioteki Python.
Biblioteka Pythona obsługuje schematy zdefiniowane za pomocą tych typów (gdzieAllowedType to dowolny dozwolony typ):
intfloatboolstrlist[AllowedType]AllowedType|AllowedType|...- W przypadku typów strukturalnych:
dict[str, AllowedType]. Ta adnotacja deklaruje, że wszystkie wartości słownika są tego samego typu, ale nie określa, jakie klucze powinny być uwzględnione.- zdefiniowanych przez użytkownika modeli Pydantic. Takie podejście umożliwia określanie nazw kluczy i definiowanie różnych typów wartości powiązanych z poszczególnymi kluczami, w tym struktur zagnieżdżonych.
Obsługa schematu JSON
JSON Schema to nowsza specyfikacja niż OpenAPI 3.0, na której opiera się obiekt Schema. Obsługa schematu JSON jest dostępna w wersji podglądowej w polu responseJsonSchema, które akceptuje dowolny schemat JSON z tymi ograniczeniami:
- Działa tylko z Gemini 2.5.
- Można przekazywać wszystkie właściwości schematu JSON, ale nie wszystkie są obsługiwane. Więcej informacji o tym polu znajdziesz w dokumentacji.
- Odwołania rekurencyjne mogą być używane tylko jako wartość właściwości obiektu, która nie jest wymagana.
- Odniesienia rekurencyjne są rozwijane do skończonego stopnia na podstawie rozmiaru schematu.
- Schematy zawierające
$refnie 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:generateContent" \ -H "x-goog-api-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 przypadku korzystania z pakietu SDK.
Sprawdzone metody
Podczas korzystania ze schematu odpowiedzi pamiętaj o tych kwestiach i sprawdzonych metodach:
- Rozmiar schematu odpowiedzi wlicza się do limitu tokenów wejściowych.
- Domyślnie pola są opcjonalne, co oznacza, że model może je wypełnić lub pominąć. Możesz oznaczyć pola jako wymagane, aby wymusić podanie wartości przez model. Jeśli w powiązanym prompcie wejściowym jest niewystarczający kontekst, model generuje odpowiedzi głównie na podstawie danych, na których został wytrenowany.
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, wyliczeń z wieloma wartościami, obiektów z wieloma opcjonalnymi właściwościami lub kombinacji tych czynników.Jeśli ten błąd pojawi się w przypadku prawidłowego schematu, wprowadź co najmniej jedną z tych zmian, aby go rozwiązać:
- skróć nazwy właściwości lub nazwy wyliczeń,
- Spłaszcz zagnieżdżone tablice.
- Zmniejsz liczbę właściwości z ograniczeniami, np. liczb z minimalnymi i maksymalnymi limitami.
- Zmniejsz liczbę usług z złożonymi ograniczeniami, np. usług o złożonych formatach, takich jak
date-time. - Zmniejsz liczbę właściwości opcjonalnych.
- Zmniejsz liczbę prawidłowych wartości wyliczeń.
Jeśli nie widzisz oczekiwanych wyników, dodaj więcej kontekstu do promptów lub zmień schemat odpowiedzi. Na przykład sprawdź odpowiedź modelu bez danych strukturalnych, aby zobaczyć, jak model reaguje. Następnie możesz zaktualizować schemat odpowiedzi, aby lepiej pasował do danych wyjściowych modelu. Dodatkowe wskazówki dotyczące rozwiązywania problemów z danymi strukturalnymi znajdziesz w przewodniku rozwiązywania problemów.
Co dalej?
Teraz gdy już wiesz, jak generować dane wyjściowe w formacie strukturalnym, możesz wypróbować narzędzia interfejsu Gemini API: