Išvesties struktūravimas: garantuotas JSON
Šiame puslapyje
Išvesties struktūravimas: garantuotas JSON
Išvesties struktūravimas yra viena galingiausių „Responses API“ funkcijų. Užuot tikėjęsis, kad modelis grąžins tinkamą JSON, tu jį garantuoji pateikdamas schemą. Tuomet modelis yra struktūriškai priverstas jos laikytis. Tai paverčia kalbos modelį iš kūrybinio teksto generatoriaus į patikimą automatizuoto duomenų apdorojimo grandinės komponentą.
Kokią problemą tai sprendžia
JSON prašymas užklausoje dažniausiai veikia, tačiau būtent todėl šis metodas yra pavojingas. Vieną kartą iš šimto modelis savo atsakymą pradeda įžanginiu sakiniu, viską įvilkina į „Markdown“ kodo bloką arba pervadina laukelį – ir tavo json.loads() gamybinėje aplinkoje išmeta išimtį dėl užklausos, kurios negali atkurti.
from openai import OpenAI
client = OpenAI()
# Be struktūros – modelis gali grąžinti bet kokį formatą
response = client.responses.create(
model="gpt-5.6-terra",
input="Give me info about Paris in JSON."
)
print(response.output_text)
# Nenuspėjamas rezultatas:
# Kartais tinkamas JSON, kartais tekstas su JSON viduje,
# kartais netikėtas formatas...
Parametras text pakeičia garantijos pobūdį. Tu nurodai formato tipą json_schema kartu su laukiama schema, ir išvestis jai paklūsta: deserializavimas tampa saugia operacija.
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'])}")
# Rezultatas GARANTUOTAI yra tinkamas JSON:
# City: Paris
# Population: 2,161,000
# Landmarks: Eiffel Tower, Louvre, Notre-Dame, Arc de Triomphe, Sacré-Cœur
„Pydantic“ vietoj ranka rašytos JSON schemos
Schemų rašymas ranka greitai tampa varginantis ir linkęs į klaidas. „Pydantic“ leidžia jas aprašyti kaip „Python“ klases, sugeneruoti JSON schemą naudojant model_json_schema(), o tada patikrinti ir tipizuoti atsakymą su `model_validate_json()”. Grandinės pabaigoje gauni pilnavertį „Python“ objektą su redaktoriaus automatinio užbaigimo funkcija, o ne bevardį žodyną.
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()
}
}
)
# Analizuojama ir tikrinama naudojant 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'}")
# Rezultatas:
# Product: ASUS ROG Strix G18
# Price: 2499.99 EUR
# In stock: Yes
Niekas neapsiriboja plokščiomis struktūromis. Komponuodamas klases, gali aprašyti įdėtus objektus ir objektų sąrašus, ko prireiks kuriant realistišką kliento profilį: įmonėje yra kontaktiniai asmenys, o kiekvienas jų turi adresą.
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}")
Du dažni naudojimo atvejai
Pirmasis – duomenų išgavimas: rašytinio teksto pavertimas naudingu įrašu. Konferencijos anonansas, parašytas natūralia kalba, tampa duomenų bazės eilute su pavadinimu, data, vieta ir dalyvių skaičiumi – be reguliariųjų išraiškų ir be sutrikimų, kai pasikeičia formuluotė.
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)")
# Rezultatas: PyCon France 2026 - November 15-16, 2026 at Lyon (800 attendees)
Antrasis – klasifikavimas. Apibrėžęs enumeraciją, apriboji modelį uždaru žodynu: jis negali atsakyti „greičiau teigiamas“ arba „teigiamas“, kai tavo kodas tikisi positive. Tai skirtumas tarp vertės, kurią gali naudoti tiesiogiai, ir vertės, kurią vėliau reikia normalizuoti.
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%})")
# Rezultatas: Sentiment: positive (95%)
Ko reikalauja griežtas režimas (strict mode)
Garantija turi savo kainą: kai strict: True, schema turi atitikti specifinį JSON schemos poaibį. Šie apribojimai yra pagrindinė 400 klaidų priežastis pradedantiesiems, todėl geriausia juos žinoti iš anksto:
- Visi laukeliai turi būti išvardyti skiltyje
required additionalPropertiesturi būtiFalse- Palaikomi tipai:
string,number,integer,boolean,array,object,null - Negalima naudoti
oneOfarbaanyOfsu mišriais tipais - Naudok
Optional[str], kuris išverčiamas į{"anyOf": [{"type": "string"}, {"type": "null"}]}
Taisyklė dėl required dažnai nustebina: neprivalomas laukelis išreiškiamas ne pašalinant jį iš sąrašo, o leidžiant reikšmę null, būtent tai ir sukuria Optional[str] „Pydantic“ pusėje.
Svarbiausi punktai
- Išvesties struktūravimas garantuoja, kad atsakymas atitiks tavo JSON schemą
- „Responses API“ naudok
text={"format": {"type": "json_schema", ...}} - „Pydantic“ yra idealus įrankis schemoms apibrėžti ir tikrinti
- Įjunk
strict: True, kad garantuotum schemos laikymąsi - Idealu duomenų išgavimui, klasifikavimui ir struktūruotam generavimui