Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Strukturált kimenet: Garantált JSON

9. lecke 22 közül Frissítve 2026. július 29. Fejlesztő
Ezen az oldalon
  1. Strukturált kimenet: Garantált JSON
  2. A megoldandó probléma
  3. Pydantic a kézzel írt JSON Séma helyett
  4. Két gyakori használati eset
  5. Amit a szigorú mód megkövetel
  6. Főbb megállapítások

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 required listában
  • Az additionalProperties értékének False-nak kell lennie
  • Támogatott típusok: string, number, integer, boolean, array, object, null
  • Nincs oneOf vagy anyOf vegyes 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