Izvades strukturēšana: garantēts JSON
Šajā lapā
Izvades strukturēšana: garantēts JSON
Izvades strukturēšana (Structured Output) ir viena no Responses API spēcīgākajām funkcijām. Tā vietā, lai cerētu, ka modelis atgriezīs derīgu JSON, tu to garantē, norādot shēmu. Tad modelis tiek strukturāli ierobežots, lai tai sekotu. Tas pārvērš valodas modeli no radoša teksta ģeneratora par uzticamu automatizētas apstrādes cauruļvada komponenti.
Problēma, ko tas atrisina
JSON pieprasīšana uzvednē (prompt) vairumā gadījumu strādā, kas tieši padara šo pieeju bīstamu. Reizi simtos reižu modelis savu atbildi sāk ar ievadteikumu, ietver visu Markdown koda blokā vai pārdēvē kādu lauku — un tavs json.loads() ražošanas vidē izmet izņēmumu pie pieprasījuma, kuru nevari reproducēt.
from openai import OpenAI
client = OpenAI()
# Bez struktūras — modelis var atgriezt jebkuru formātu
response = client.responses.create(
model="gpt-5.6-terra",
input="Give me info about Paris in JSON."
)
print(response.output_text)
# Neparedzams rezultāts:
# Dažreiz derīgs JSON, dažreiz teksts, kas satur JSON,
# dažkārt negaidīts formāts...
Parametrs text maina garantijas dabu. Tu deklarē formātu json_schema kopā ar paredzēto shēmu, un izvade tai atbilst: deserializācija kļūst par drošu operāciju.
response = client.responses.create(
model="gpt-5.6-terra",
input="Give me information about Paris.",
text={
"format": {
"type": "json_schema",
"name": "city_info",
"strict": True,
"schema": {
"type": "object",
"properties": {
"name": {"type": "string"},
"country": {"type": "string"},
"population": {"type": "integer"},
"official_language": {"type": "string"},
"landmarks": {
"type": "array",
"items": {"type": "string"}
}
},
"required": ["name", "country", "population", "official_language", "landmarks"],
"additionalProperties": False
}
}
}
)
import json
data = json.loads(response.output_text)
print(f"City: {data['name']}")
print(f"Population: {data['population']:,}")
print(f"Landmarks: {', '.join(data['landmarks'])}")
# Rezultāts GARANTĒTI ir derīgs JSON:
# City: Paris
# Population: 2,161,000
# Landmarks: Eiffel Tower, Louvre, Notre-Dame, Arc de Triomphe, Sacré-Cœur
Pydantic manuāli rakstītas JSON shēmas vietā
Shēmu rakstīšana ar roku ātri kļūst apnicīga un pakļauta kļūdām. Pydantic ļauj tās aprakstīt kā Python klases, ģenerēt JSON shēmu ar model_json_schema() un pēc tam validēt un tipizēt atbildi ar `model_validate_json() Ķēdes galā tu iegūsti pilnvērtīgu Python objektu ar redaktora automātisko pabeigšanu, nevis anonīmu vārdnīcu.
from pydantic import BaseModel
from typing import Optional
import json
class Product(BaseModel):
name: str
price: float
category: str
in_stock: bool
description: Optional[str] = None
response = client.responses.create(
model="gpt-5.6-terra",
input="Describe a high-end gaming laptop.",
text={
"format": {
"type": "json_schema",
"name": "product",
"strict": True,
"schema": Product.model_json_schema()
}
}
)
# Parsē un validē ar Pydantic
product = Product.model_validate_json(response.output_text)
print(f"Product: {product.name}")
print(f"Price: {product.price} EUR")
print(f"In stock: {'Yes' if product.in_stock else 'No'}")
# Rezultāts:
# Product: ASUS ROG Strix G18
# Price: 2499.99 EUR
# In stock: Yes
Nekas neierobežo tevi ar plakanām struktūrām. Komponējot klases, tu apraksti ligzdotus objektus un objektu sarakstus, kas tev būs nepieciešami, tiklīdz izveidosi reālistisku klienta profilu: uzņēmums satur kontaktus, un katram kontaktam ir adrese.
from pydantic import BaseModel
class Address(BaseModel):
street: str
city: str
postal_code: str
country: str
class Contact(BaseModel):
last_name: str
first_name: str
email: str
phone: str
address: Address
class Company(BaseModel):
name: str
sector: str
employees: int
contacts: list[Contact]
response = client.responses.create(
model="gpt-5.6-terra",
input="Generate a fictional company profile in the tech sector "
"with 2 contacts.",
text={
"format": {
"type": "json_schema",
"name": "company",
"strict": True,
"schema": Company.model_json_schema()
}
}
)
company = Company.model_validate_json(response.output_text)
print(f"Company: {company.name} ({company.sector})")
for c in company.contacts:
print(f" - {c.first_name} {c.last_name}: {c.email}")
Divi bieži sastopami lietojumi
Pirmais ir ekstrakcija: rakstīta teksta pārvēršana izmantojamā ierakstā. Dabiskā valodā rakstīts konferences paziņojums kļūst par datubāzes rindu ar nosaukumu, datumu, atrašanās vietu un dalībnieku skaitu — bez regulārām izteiksmēm un bez bojāšanās, mainoties formulējumam.
class Event(BaseModel):
title: str
date: str
location: str
attendees: int
text = """
The PyCon France 2026 conference will be held on November 15 and 16
at the Palais des Congrès in Lyon. More than 800 Python developers
are expected for this edition.
"""
response = client.responses.create(
model="gpt-5.6-terra",
input=f"Extract the information from this event:\n{text}",
text={
"format": {
"type": "json_schema",
"name": "event",
"strict": True,
"schema": Event.model_json_schema()
}
}
)
evt = Event.model_validate_json(response.output_text)
print(f"{evt.title} - {evt.date} at {evt.location} ({evt.attendees} attendees)")
# Rezultāts: PyCon France 2026 - November 15-16, 2026 at Lyon (800 attendees)
Otrais ir klasifikācija. Deklarējot enumerāciju, tu ierobežo modeli ar slēgtu vārdu krājumu: tas nevar atbildēt „drīzāk pozitīvi” vai „pozitīvs”, ja tavs kods sagaida positive. Šī ir atšķirība starp vērtību, ko vari izmantot tieši, un vērtību, kas pēc tam ir jānormalizē.
from enum import Enum
class Sentiment(str, Enum):
positive = "positive"
negative = "negative"
neutral = "neutral"
class Analysis(BaseModel):
sentiment: Sentiment
confidence: float
keywords: list[str]
response = client.responses.create(
model="gpt-5.6-terra",
input="Analyze this comment: 'Great service, fast delivery!'",
text={
"format": {
"type": "json_schema",
"name": "sentiment_analysis",
"strict": True,
"schema": Analysis.model_json_schema()
}
}
)
analysis = Analysis.model_validate_json(response.output_text)
print(f"Sentiment: {analysis.sentiment.value} ({analysis.confidence:.0%})")
# Rezultāts: Sentiment: positive (95%)
Ko prasa stingrais režīms
Garantijai ir sava cena: ja strict: True, shēmai ir jāatbilst specifiskai JSON shēmas apakškopai. Šie ierobežojumi ir galvenais 400 kļūdu cēlonis iesācējiem, tāpēc vislabāk tos zināt jau iepriekš:
- Visiem īpašībām (properties) ir jābūt uzskaitītām
required additionalPropertiesir jābūtFalse- Atbalstītie tipi:
string,number,integer,boolean,array,object,null - Nav atļauts
oneOfvaianyOfar jauktiem tipiem - Izmanto
Optional[str], kas tiek tulkots kā{"anyOf": [{"type": "string"}, {"type": "null"}]}
Noteikums par required bieži pārsteidz: opcionāls lauks netiek izteikts, to izņemot no saraksta, bet gan atļaujot vērtību null, tieši to, ko Pydantic pusē rada Optional[str].
Galvenās atziņas
- Strukturētā izvade garantē, ka atbilde atbilst tavai JSON shēmai
- Responses API izmanto
text={"format": {"type": "json_schema", ...}} - Pydantic ir ideāls rīks shēmu definēšanai un validēšanai
- Aktivizē
strict: True, lai garantētu shēmas atbilstību - Ideāli piemērots datu ekstrakcijai, klasifikācijai un strukturētai ģenerēšanai