Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Izlaz u strukturiranom obliku: zajamčeni JSON

Lekcija 9 od 22 Ažurirano 29. srpnja 2026. Programer
Na ovoj stranici
  1. Izlaz u strukturiranom obliku: zajamčeni JSON
  2. Problem koji ovo rješava
  3. Pydantic umjesto ručno pisanog JSON Schema
  4. Dva česta slučaja upotrebe
  5. Što zahtijeva strogi način rada (strict mode)
  6. Ključne točke

Izlaz u strukturiranom obliku: zajamčeni JSON

Izlaz u strukturiranom obliku (Structured Output) jedna je od najmoćnijih značajki API-ja Responses. Umjesto da se nadaš kako će model vratiti ispravan JSON, to zajamčuješ davanjem sheme. Model je tada strukturno prisiljen slijediti je. Time jezični model pretvaraš iz kreativnog generatora teksta u pouzdanu komponentu automatiziranog procesnog lanca.

Problem koji ovo rješava

Traženje JSON-a u promptu većinom funkcionira, što je upravo ono što ovaj pristup čini opasnim. Jedan dan od stotinu model će odgovor započeti uvodnom rečenicom, sve zamotati u Markdown blok koda ili preimenovati polje – i tvoj json.loads() u produkciji baci iznimku na zahtjev koji ne možeš reproducirati.

from openai import OpenAI
client = OpenAI()

# Bez strukture — model može vratiti bilo koji format
response = client.responses.create(
    model="gpt-5.6-terra",
    input="Give me info about Paris in JSON."
)
print(response.output_text)
# Nepredvidiv rezultat:
# Ponekad ispravan JSON, ponekad tekst koji sadrži JSON,
# ponekad neočekivani format...

Parametar text mijenja prirodu jamstva. Deklariraš format json_schema zajedno s očekivanom shemom, a izlaz joj se prilagođava: deserializacija postaje sigurna 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 ispravan JSON:
# City: Paris
# Population: 2,161,000
# Landmarks: Eiffel Tower, Louvre, Notre-Dame, Arc de Triomphe, Sacré-Cœur

Pydantic umjesto ručno pisanog JSON Schema

Ručno pisanje shema brzo postaje zamorno i podložno tipfelerskim greškama. Pydantic ti omogućuje da ih opišeš kao Python klase, generiraš JSON Shemu s model_json_schema(), a zatim validiraš i tipiziraš odgovor s model_validate_json(). Na kraju lanca dobivaš puni Python objekt s automatskim dovršavanjem u uređivaču, umjesto anonimnog rječnika.

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

# Parsiranje i validacija s Pydanticom
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šta te ne ograničava na ravne strukture. Sastavljanjem klasa opisuješ ugniježđene objekte i liste objekata, što ćeš trebati čim kreiraš realističan profil kupca: tvrtka sadrži kontakte, a svaki kontakt ima adresu.

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 česta slučaja upotrebe

Prvi je ekstrakcija: pretvaranje pisanog teksta u upotrebljivi zapis. Najava konferencije napisana prirodnim jezikom postaje redak u bazi podataka s naslovom, datumom, lokacijom i brojem sudionika – bez regularnih izraza i bez kvarova kad god se promijeni formulacija.

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 je klasifikacija. Deklariranjem enumeracije ograničavaš model na zatvoreni rječnik: ne može odgovoriti „prilično pozitivno“ ili „pozitivno“ kada tvoj kod očekuje positive. To je razlika između vrijednosti koju možeš izravno upotrijebiti i one koju moraš naknadno 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%)

Što zahtijeva strogi način rada (strict mode)

Jamstvo nosi kompromis: kada je strict: True, shema se mora pridržavati određenog podskupa JSON Sheme. Ta su ograničenja vodeći uzrok grešaka 400 za početnike, pa ih je najbolje upoznati prije nego što na njih naiđeš:

  • Sva svojstva moraju biti navedena u required
  • additionalProperties mora biti False
  • Podržani tipovi: string, number, integer, boolean, array, object, null
  • Bez oneOf ili anyOf s mješovitim tipovima
  • Koristi Optional[str], što se prevodi u {"anyOf": [{"type": "string"}, {"type": "null"}]}

Pravilo o required često iznenadi ljude: opcionalno polje ne izražavaš njegovim uklanjanjem s popisa, već dopuštanjem vrijednosti null, točno onako kako Optional[str] proizvodi na strani Pydantica.

Ključne točke

  • Strukturirani izlaz jamči da odgovor poštuje tvoju JSON shemu
  • U API-ju Responses koristi text={"format": {"type": "json_schema", ...}}
  • Pydantic je idealan alat za definiranje i validaciju shema
  • Omogući strict: True za zajamčenu usklađenost sa shemom
  • Idealno za ekstrakciju podataka, klasifikaciju i strukturirano generiranje