Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Izhod v strukturirani obliki: zajamčen JSON

Lekcija 9 od 22 Posodobljeno 29. julij 2026 Razvijalec
Na tej strani
  1. Izhod v strukturirani obliki: zajamčen JSON
  2. Težava, ki jo to rešuje
  3. Pydantic namesto ročno napisane JSON sheme
  4. Dva pogosta primera uporabe
  5. Kaj zahteva strogi način
  6. Ključne ugotovitve

Izhod v strukturirani obliki: zajamčen JSON

Izhod v strukturirani obliki (Structured Output) je ena najzmogljivejših funkcij API-ja Responses. Namesto da upaš, da bo model vrnil veljaven JSON, to zajamčiš z zagotovitvijo sheme. Model je nato strukturno omejen, da ji sledi. To jezikovni model spremeni iz ustvarjalnega generatorja besedila v zanesljivo komponento avtomatiziranega obdelovalnega procesa.

Težava, ki jo to rešuje

Zahteva po JSON-u v pozivu deluje večino časa, kar je prav tisto, zaradi česar je ta pristop nevaren. Enkrat na sto poskusov model svojemu odgovoru doda uvodni stavek, vse ovije v blok kode Markdown ali preimenuje polje – in tvoj json.loads() v proizvodnem okolju vrže izjemo pri zahtevi, ki je ne moreš reproducirati.

from openai import OpenAI
client = OpenAI()

# Brez strukture — model lahko vrne katero koli obliko
response = client.responses.create(
    model="gpt-5.6-terra",
    input="Give me info about Paris in JSON."
)
print(response.output_text)
# Nepredvidljiv rezultat:
# Včasih veljaven JSON, včasih besedilo, ki vsebuje JSON,
# včasih nepričakovana oblika...

Parameter text spremeni naravo zajamčenosti. Deklariraš format json_schema skupaj s pričakovano shemo in izhod se ji prilagodi: deserializacija postane varna 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'])}")

# Rezultat je ZAJAMČENO veljaven JSON:
# City: Paris
# Population: 2,161,000
# Landmarks: Eiffel Tower, Louvre, Notre-Dame, Arc de Triomphe, Sacré-Cœur

Pydantic namesto ročno napisane JSON sheme

Ročno pisanje shem hitro postane dolgočasno in nagnjeno k tipkarskim napakam. Pydantic ti omogoča, da jih opišeš kot razrede Python, generiraš JSON shemo z model_json_schema() in nato odgovor validiraš ter tipiziraš z model_validate_json(). Na koncu verige dobiš popoln objekt Python z samodejnim dopolnjevanjem v urejevalniku, namesto anonimnega slovarja.

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()
        }
    }
)

# Razčleni in validiraj s 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'}")

# Rezultat:
# Product: ASUS ROG Strix G18
# Price: 2499.99 EUR
# In stock: Yes

Nič te ne omejuje na ravne strukture. S komponiranjem razredov opišeš gnezdena objekta in sezname objektov, kar boš potreboval takoj, ko ustvariš realističen profil stranke: podjetje vsebuje kontakte, vsak kontakt pa ima naslov.

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}")

Dva pogosta primera uporabe

Prvi je ekstrakcija: pretvorba zapisanega besedila v uporaben zapis. Napoved konference, napisana v naravnem jeziku, postane vrstica v zbirki podatkov z naslovom, datumom, lokacijo in številom udeležencev – brez regularnih izrazov in brez napak, kadar se spremeni besedilo.

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)")
# Rezultat: PyCon France 2026 - November 15-16, 2026 at Lyon (800 attendees)

Drugi primer je klasifikacija. Z deklaracijo enumeracije omejiš model na zaprt besednjak: ne more odgovoriti „precej pozitiven” ali „pozitiven”, ko tvoja koda pričakuje positive. To je razlika med vrednostjo, ki jo lahko uporabiš neposredno, in vrednostjo, ki jo moraš nato normalizirati.

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%})")
# Rezultat: Sentiment: positive (95%)

Kaj zahteva strogi način

Zajamčenost ima svojo ceno: ko je strict: True, se mora shema držati določenega podnabora JSON Schema. Te omejitve so glavni vzrok za napake 400 pri začetnikih, zato jih je najbolje poznati, preden nanje naletiš:

  • Vsa polja morajo biti navedena v required
  • additionalProperties mora biti False
  • Podprti tipi: string, number, integer, boolean, array, object, null
  • Brez oneOf ali anyOf z mešanimi tipi
  • Uporabi Optional[str], kar se prevede v {"anyOf": [{"type": "string"}, {"type": "null"}]}

Pravilo o required pogosto preseneti ljudi: izbirnega polja ne izraziš z njegovo odstranitvijo s seznama, temveč z dovoljenjem vrednosti null, kar točno počne Optional[str] na strani Pydantic.

Ključne ugotovitve

  • Strukturirani izhod zajamči, da se odgovor drži tvoje JSON sheme
  • V API-ju Responses uporabi text={"format": {"type": "json_schema", ...}}
  • Pydantic je idealno orodje za definiranje in validacijo shem
  • Omogoči strict: True za zajamčeno skladnost s shemo
  • Idealno za ekstrakcijo podatkov, klasifikacijo in strukturirano generiranje