Väljund struktureerituna: garanteeritud JSON
Sellel lehel
Väljund struktureerituna: garanteeritud JSON
Väljund struktureerituna on Responses API üks võimsamaid funktsioone. Selle asemel, et loota mudeli poolt kehtiva JSON-i tagastamisele, garanteerid selle, esitades skeemi. Mudel on seejärel struktuurselt sunnitud seda järgima. See muudab keelemudeli loomingulisest tekstigeneraatorist usaldusväärseks komponendiks automatiseeritud töötlemise ahelas.
Probleem, mida see lahendab
JSON-i küsimine vihjes toimib enamasti, mis teebki selle lähenemise ohtlikuks. Ühel juhul sajast lisab mudel vastuse ette sissejuhatava lause, pakib kõik Markdowni koodiplokki või nimetab välja ümber – ja sinu json.loads() viskab tootmises erandi päringule, mida sa ei suuda reprodutseerida.
from openai import OpenAI
client = OpenAI()
# Ilma struktuurita — mudel võib tagastada ükskõik millises formaadis
response = client.responses.create(
model="gpt-5.6-terra",
input="Give me info about Paris in JSON."
)
print(response.output_text)
# Ettearvamatu tulemus:
# Vahel kehtiv JSON, vahel tekst, mis sisaldab JSON-i,
# vahel ootamatu formaat...
Parameeter text muudab garantii olemust. Sa deklareerid formaadi json_schema koos oodatava skeemiga ja väljund vastab sellele: deserialiseerimine muutub ohutuks operatsiooniks.
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'])}")
# Tulemus on GARANTEERITULT kehtiv JSON:
# City: Paris
# Population: 2,161,000
# Landmarks: Eiffel Tower, Louvre, Notre-Dame, Arc de Triomphe, Sacré-Cœur
Pydantic käsitsi kirjutatud JSON Schema asemel
Skeemide käsitsi kirjutamine muutub kiiresti tüütuks ja vigadele altiks. Pydantic võimaldab neid kirjeldada Pythoni klassidena, genereerida JSON Schema funktsiooniga model_json_schema() ning seejärel valideerida ja tüübistada vastus funktsiooniga model_validate_json(). Ahela lõpus saad täisväärtusliku Pythoni objekti koos redaktori automaatse täiendamisega, mitte anonüümse sõnastiku.
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()
}
}
)
# Parsi ja valideeri Pydanticuga
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'}")
# Tulemus:
# Product: ASUS ROG Strix G18
# Price: 2499.99 EUR
# In stock: Yes
Midagi ei piira sind lamedate struktuuridega. Klasse komponeerides kirjeldad pesastatud objekte ja objektide loendeid, mida vajad niipea, kui lood realistlikku kliendiprofiili: ettevõte sisaldab kontakte ja igal kontaktil on aadress.
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}")
Kaks levinud kasutusjuhtu
Esimene on ekstraheerimine: kirjaliku teksti muutmine kasutatavaks kirjeiks. Loomulikus keeles kirjutatud konverentsiteade muutub andmebaasi reaks, mis sisaldab pealkirja, kuupäeva, asukohta ja osalejate arvu – ilma regulaaravaldisteta ja katkemata iga kord, kui sõnastus muutub.
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)")
# Tulemus: PyCon France 2026 - November 15-16, 2026 at Lyon (800 attendees)
Teine on klassifitseerimine. Loetelu deklareerides piirad mudeli suletud sõnavaraga: ta ei saa vastata „pigem positiivne“ või „positiivne“, kui sinu kood ootab väärtust positive. See on erinevus väärtuse vahel, mida saad otse kasutada, ja väärtuse vahel, mida pead hiljem normaliseerima.
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%})")
# Tulemus: Sentiment: positive (95%)
Mida range režiim nõuab
Garantiiga kaasneb kompromiss: kui strict: True, peab skeem järgima JSON Schema spetsiifilist alamhulka. Need piirangud on algajate jaoks 400 vigade peamine põhjus, seega on kõige parem nendega enne kokkupuutumist tutvuda:
- Kõik omadused peavad olema loetletud võtmes
required additionalPropertiespeab olemaFalse- Toetatud tüübid:
string,number,integer,boolean,array,object,null - Puuduvad
oneOfvõianyOfsegatüüpidega - Kasuta
Optional[str], mis tõlgitakse kujule{"anyOf": [{"type": "string"}, {"type": "null"}]}
Reegel required kohta üllatab sageli: valikulist välja ei väljendata selle loendist eemaldamisega, vaid lubades väärtust null, täpselt nii, nagu Optional[str] Pydanticu poolel teeb.
Peamised punktid
- Struktureeritud väljund garanteerib, et vastus järgib sinu JSON skeemi
- Kasuta Responses API-s
text={"format": {"type": "json_schema", ...}} - Pydantic on ideaalne tööriist skeemide defineerimiseks ja valideerimiseks
- Luba
strict: True, et garanteerida skeemile vastavust - Ideaalne andmete ekstraheerimiseks, klassifitseerimiseks ja struktureeritud genereerimiseks