Strukturált kimenet: Garantált JSON
Ezen az oldalon
Strukturált kimenet: Garantált JSON
A Strukturált kimenet (Structured Output) a Responses API egyik leghatékonyabb funkciója. Ahelyett, hogy abban bíznál, hogy a modell érvényes JSON-t ad vissza, ezt egy séma megadásával garantálod. A modell ezután szerkezetileg kénytelen ezt követni. Ez a nyelvi modellt egy kreatív szöveggenerátorból egy automatizált feldolgozási lánc megbízható elemévé alakítja.
A megoldandó probléma
Ha JSON-t kérsz a promptban, az az esetek többségében működik, és pontosan ez teszi veszélyessé a módszert. Száz esetből egyszer a modell bevezető mondattal kezdi a választ, Markdown kódblokkba csomagolja az egészet, vagy átnevez egy mezőt – és a termelésben a json.loads() kivételt dob egy olyan kérésnél, amelyet nem tudsz reprodukálni.
from openai import OpenAI
client = OpenAI()
# Struktúra nélkül – a modell bármilyen formátumot visszaadhat
response = client.responses.create(
model="gpt-5.6-terra",
input="Give me info about Paris in JSON."
)
print(response.output_text)
# Kiszámíthatatlan eredmény:
# Néha érvényes JSON, néha JSON-t tartalmazó szöveg,
# néha váratlan formátum...
A text paraméter megváltoztatja a garancia jellegét. Deklarálsz egy json_schema formátumot a várt sémával együtt, és a kimenet ehhez igazodik: a deszerializálás biztonságos műveletté válik.
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'])}")
# Az eredmény GARANTÁLTAN érvényes JSON:
# City: Paris
# Population: 2,161,000
# Landmarks: Eiffel Tower, Louvre, Notre-Dame, Arc de Triomphe, Sacré-Cœur
Pydantic a kézzel írt JSON Séma helyett
A sémák kézi írása gyorsan unalmassá válik, és tele lesz elírásokkal. A Pydantic lehetővé teszi, hogy Python osztályokként írd le őket, generáld a JSON Sémát a model_json_schema() segítségével, majd a model_validate_json()-nel validáld és típusosítsd a választ. A lánc végén egy teljes Python objektumot kapsz szerkesztői automatikus kiegészítéssel, nem pedig egy névtelen szótárat.
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()
}
}
)
# Elemzés és validálás Pydanticcel
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'}")
# Eredmény:
# Product: ASUS ROG Strix G18
# Price: 2499.99 EUR
# In stock: Yes
Semmi sem korlátoz lapos struktúrákra. Osztályok összetételével leírhatsz beágyazott objektumokat és objektumlistákat is, amelyekre akkor lesz szükséged, amikor egy valós ügyfélprofilt hozol létre: egy cég tartalmaz kapcsolatokat, és minden kapcsolatnak van címe.
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}")
Két gyakori használati eset
Az első a kinyerés (extraction): írott szöveg használható rekordszá alakítása. Egy természetes nyelven írt konferenciabejelentés adatbázis-sorrá válik címmel, dátummal, helyszínnel és résztvevői létszámmal – reguláris kifejezések nélkül, és anélkül, hogy összeomlana, valahányszor a megfogalmazás megváltozik.
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)")
# Eredmény: PyCon France 2026 - November 15-16, 2026 at Lyon (800 attendees)
A második a kategorizálás (classification). Egy felsorolás (enumeration) deklarálásával zárt szókészletre korlátozod a modellt: nem válaszolhat azt, hogy „inkább pozitív“ vagy „pozitív“, ha a kódod a positive értéket várja. Ez a különbség egy közvetlenül használható érték és egy utólag normalizálandó érték között.
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%})")
# Eredmény: Sentiment: positive (95%)
Amit a szigorú mód megkövetel
A garancia kompromisszummal jár: ha strict: True, a sémának a JSON Schema egy specifikus részhalmazához kell igazodnia. Ezek a korlátozások okozzák a legtöbb 400-as hibát a kezdőknél, ezért érdemes előre ismerni őket:
- Minden tulajdonságot fel kell sorolni a
requiredlistában - Az
additionalPropertiesértékénekFalse-nak kell lennie - Támogatott típusok:
string,number,integer,boolean,array,object,null - Nincs
oneOfvagyanyOfvegyes típusokkal - Használj
Optional[str]-t, ami a{"anyOf": [{"type": "string"}, {"type": "null"}]}kifejezésre fordul
A required-ra vonatkozó szabály gyakran lep meg embereket: egy opcionális mezőt nem úgy fejezel ki, hogy kiveszed a listából, hanem úgy, hogy engedélyezed a null értéket – pontosan ezt csinálja az Optional[str] a Pydantic oldalán.
Főbb megállapítások
- A Strukturált kimenet garantálja, hogy a válasz megfelel a JSON sémádnak
- Használd a
text={"format": {"type": "json_schema", ...}}paramétert a Responses API-ban - A Pydantic az ideális eszköz sémák definiálására és validálására
- Engedélyezd a
strict: Trueértéket a garantált séma-megfeleléshez - Ideális adatok kinyerésére, kategorizálására és strukturált generálására