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

Način JSON i provođenje sheme

Lekcija 10 od 16 Ažurirano 3. studenoga 2026. Programer
Na ovoj stranici
  1. Način JSON i provođenje sheme
  2. Način JSON naspram strukturiranog izlaza
  3. Strukturirani izlaz s JSON shemom
  4. Pravila za strogi strukturirani izlaz
  5. Pomoćnik za izgradnju shema
  6. Primjer: Ekstrakcija strukturiranih podataka
  7. Mjerenje onoga što ograničenje donosi
  8. Ključne točke

Lekcija ažurirana 3. studenog 2026. na temelju OpenAI dokumentacije: temperature i top_p prihvaćeni su samo uz napor razmišljanja (reasoning effort) od none, dok modeli GPT-5.6 prema zadanim postavkama razmišljaju (medium). Pozivi koji postavljaju ove parametre stoga moraju specificirati reasoning={"effort": "none"} (Responses API) ili reasoning_effort="none" (Chat Completions). Izvori: Korištenje GPT-6 · GPT-5.6 Terra.

Način JSON i provođenje sheme

OpenAI-jev strukturirani izlaz (Structured Output) jamči da će odgovor modela biti valjani JSON koji odgovara shemi koju ti definiraš. Više nema krhkog parsiranja pomoću regularnih izraza ili grešaka u formatu – ograničenje se primjenjuje na samoj razini generiranja.

Ova je nijansa ključna i mijenja sve za developera. Tražiti u promptu „odgovori u JSON-u“ molba je: model će se većinom pokoriti, ali jednog će dana svom odgovoru dodati prefiks „Evo traženog JSON-a:“, umetnuti Markdown backtickove ili zaboraviti zarez, pa će tvoj json.loads baciti iznimku u produkciji u 3 ujutro tijekom najveće tjedne serije podataka. Uz strukturirani izlaz, ograničenje se primjenjuje tijekom dekodiranja: tokeni koji bi proizveli nevaljani ili neusklađeni JSON jednostavno se ne mogu odabrati. Prestaješ moljakati i počinješ provoditi pravila.

Način JSON naspram strukturiranog izlaza

OpenAI nudi dvije razine ograničenja, a razlika visi o jednoj jedinoj riječi. Način JSON jamči valjani JSON bez strukturnih ograničenja; strukturirani izlaz jamči JSON koji odgovara JSON shemi koju si napisao.

Način JSON rješava pola problema. Siguran si da možeš parsirati odgovor, ali nisi siguran što on sadrži: model može nazvati polje annee u jednom zahtjevu, a year u sljedećem, ili svoj popis umotati u objekt resultats kojeg jučer nije koristio. Za prototip ili sirovi prikaz namijenjen čovjeku to je dovoljno; čim izlaz napaja kod koji pristupa poljima po imenu, trebaš drugu razinu.

from openai import OpenAI

client = OpenAI()

# Jednostavni način JSON (valjani JSON, slobodna struktura)
response = client.responses.create(
    model="gpt-5.6-terra",
    instructions="Always respond in JSON.",
    input="List 3 programming languages with their year of creation.",
    text={"format": {"type": "json_object"}}
)

import json
data = json.loads(response.output_text)
print(data)

Strukturirani izlaz s JSON shemom

Ovo je najmoćnija značajka. Definiraš JSON shemu, a API jamči da će se izlaz pridržavati nje. Donji primjer analizira sentiment recenzije kupca i ilustrira tri komplementarne uporabe sheme.

enum na polju sentiment sprječava model da izmisli međukategoriju poput „prilično pozitivno“: mora birati između četiri ponuđene vrijednosti, čineći izlaz izravno upotrebljivim u filteru ili nadzornoj ploči. description polja score djeluje kao lokalni mini-prompt, ukazujući na očekivanu ljestvicu bez potrebe da to objašnjavaš u općim uputama, a ostaje vezano uz polje čak i ako se prompt evoluira. Konačno, niz aspects omogućuje ti raščlanjivanje kontradiktorne recenzije – ovdje proizvod koji se sviđa, ali dostava je propala – umjesto da tu nijansu zgnječiš u jedan rezultat koji nikome ne pomaže.

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Analyze the sentiment of: 'The product is excellent "
          "but the delivery was catastrophic.'",
    text={
        "format": {
            "type": "json_schema",
            "name": "sentiment_analysis",
            "schema": {
                "type": "object",
                "properties": {
                    "sentiment": {
                        "type": "string",
                        "enum": ["positive", "negative", "mixed", "neutral"]
                    },
                    "score": {
                        "type": "number",
                        "description": "Score from -1.0 (very negative) to 1.0 (very positive)"
                    },
                    "aspects": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "aspect": {"type": "string"},
                                "sentiment": {
                                    "type": "string",
                                    "enum": ["positive", "negative", "neutral"]
                                }
                            },
                            "required": ["aspect", "sentiment"],
                            "additionalProperties": False
                        }
                    },
                    "summary": {"type": "string"}
                },
                "required": ["sentiment", "score", "aspects", "summary"],
                "additionalProperties": False
            },
            "strict": True
        }
    }
)

result = json.loads(response.output_text)
# Zajamčeno: result ima točno definirana polja
print(f"Sentiment: {result['sentiment']}")
print(f"Score: {result['score']}")
for aspect in result["aspects"]:
    print(f"  - {aspect['aspect']}: {aspect['sentiment']}")

Pravila za strogi strukturirani izlaz

Način strict: true nameće vlastita ograničenja shemi. Sva polja moraju se pojaviti u required, a additionalProperties mora biti false na svakom objektu. Dopušteni tipovi su string, number, integer, boolean, array, object i null, plus enum za ograničavanje vrijednosti. Međutim, ni pattern ni minLength/maxLength nisu prihvaćeni: detaljna validacija događa se na strani klijenta.

Ova pravila mogu biti iznenađujuća pri prvom pokušaju jer zabranjuju opcionalna polja onako kako se obično pišu u JSON shemi. Kompromis je udoban: tvoj kod nikada ne mora testirati postoji li ključ; on je uvijek tu. Za polje koje legitimno može biti prazno – nedostajući broj telefona u dokumentu, datum završetka za tekući ugovor – odgovor nije ukloniti ga iz required, već dopustiti da bude null. Što se tiče izostanka pattern i granica duljine, to signalizira sljedeću lekciju: shema jamči oblik, ali poslovna validacija ostaje tvoj posao nakon što se odgovor primi.

Pomoćnik za izgradnju shema

Ručno pisanje bloka text.format za svaki poziv brzo postaje dosadno i podložno tipfelerima – nedostaje ključ name, strict je na pogrešnom mjestu i greška se vraća s API-ja bez naznake gdje gledati. Nekoliko redaka omotnog koda centralizira strukturu, prema zadanim postavkama primjenjuje nisku temperaturu (jer varijabilnost ne dodaje ništa ekstrakciji) i čini mjesto poziva čitljivim.

def structured_query(prompt: str, schema: dict,
                     schema_name: str = "response",
                     model: str = "gpt-5.6-terra",
                     system: str = "") -> dict:
    """Wrapper for Structured Output requests."""
    response = client.responses.create(
        model=model,
        reasoning={"effort": "none"},  # temperature requires effort none
        instructions=system or "Respond in JSON according to the provided schema.",
        input=prompt,
        text={
            "format": {
                "type": "json_schema",
                "name": schema_name,
                "schema": schema,
                "strict": True
            }
        },
        temperature=0.1
    )
    return json.loads(response.output_text)

Primjer: Ekstrakcija strukturiranih podataka

Evo slučaja uporabe koji sam po sebi opravdava učenje ove tehnike: pretvaranje računa primljenog kao običan tekst u objekt upotrebljiv za tvoj računovodstveni sustav. Shema opisuje tri razine – zaglavlje računa, ugniježđeni objekt vendor i niz lines gdje svaki element ima isti oblik. Model stoga mora i locirati informacije raspršene po dokumentu i postaviti ih na pravo mjesto, uključujući i za stavku izraženu u satima umjesto u jedinicama, gdje se jedinična cijena podrazumijeva kao satnica.

Imaj na umu da se ukupni iznosi u shemi pojavljuju kao polja za ekstrakciju, a ne za ponovni izračun. Od modela tražimo da čita; kontrola aritmetike događa se nakon toga u tvom kodu, gdje će jednostavna usporedba između zbroja stavki i ekstrahiranog total_ht označiti dokumente za ljudski pregled.

invoice_schema = {
    "type": "object",
    "properties": {
        "invoice_number": {"type": "string"},
        "date": {"type": "string"},
        "vendor": {
            "type": "object",
            "properties": {
                "name": {"type": "string"},
                "siret": {"type": "string"},
                "address": {"type": "string"}
            },
            "required": ["name", "siret", "address"],
            "additionalProperties": False
        },
        "lines": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "description": {"type": "string"},
                    "quantity": {"type": "integer"},
                    "unit_price_excl_tax": {"type": "number"},
                    "vat_percent": {"type": "number"}
                },
                "required": ["description", "quantity",
                             "unit_price_excl_tax", "vat_percent"],
                "additionalProperties": False
            }
        },
        "total_excl_tax": {"type": "number"},
        "total_incl_tax": {"type": "number"}
    },
    "required": ["invoice_number", "date", "vendor",
                  "lines", "total_excl_tax", "total_incl_tax"],
    "additionalProperties": False
}

invoice_text = """
Invoice No. 2026-0042
Date: 15/03/2026
Vendor: TechServ SARL, SIRET 123 456 789 00012
12 rue de la Paix, 75002 Paris

- REST API Development x1: 3500.00 EUR excl. tax (VAT 20%)
- Cloud hosting (3 months) x1: 450.00 EUR excl. tax (VAT 20%)
- Technical support x10h: 150.00 EUR excl. tax/h (VAT 20%)

Total excl. tax: 5450.00 EUR
Total incl. tax: 6540.00 EUR
"""

result = structured_query(
    invoice_text,
    invoice_schema,
    schema_name="invoice",
    system="Extract the data from this invoice."
)

Mjerenje onoga što ograničenje donosi

Primijeni ovo načelo na dokument koji dobro poznaješ: definiraj JSON shemu za ekstrakciju ključnih informacija iz životopisa – ime, iskustvo, vještine, obrazovanje – i testiraj je na tri životopisa u običnom tekstu namjerno odabrana zbog njihovih heterogenih rasporeda. Provjeri poštuje li izlaz shemu čak i kada cijeli odjeljak nedostaje.

Zatim ponovi istu ekstrakciju bez strukturiranog izlaza, jednostavno tražeći JSON u promptu, i drži svih šest izlaza jedan uz drugi. Usporedba dviju serija pokazuje što ograničenje donosi: razlika rijetko leži u ekstrahiranom sadržaju, gotovo uvijek u stabilnosti imena polja i prisutnosti očekivanih ključeva.

Ključne točke

  • Strukturirani izlaz jamči JSON koji odgovara shemi na razini generiranja
  • Koristi strict: true za maksimalnu usklađenost
  • Sva polja moraju biti required s additionalProperties: false
  • Idealno za ekstrakciju podataka, klasifikaciju i procesne cjevovode
  • Detaljna validacija (duljina, uzorak) događa se na strani klijenta nakon primitka