Način JSON i provođenje sheme
Na ovoj stranici
Lekcija ažurirana 3. studenog 2026. na temelju OpenAI dokumentacije:
temperatureitop_pprihvaćeni su samo uz napor razmišljanja (reasoning effort) odnone, dok modeli GPT-5.6 prema zadanim postavkama razmišljaju (medium). Pozivi koji postavljaju ove parametre stoga moraju specificiratireasoning={"effort": "none"}(Responses API) ilireasoning_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: trueza maksimalnu usklađenost - Sva polja moraju biti
requiredsadditionalProperties: false - Idealno za ekstrakciju podataka, klasifikaciju i procesne cjevovode
- Detaljna validacija (duljina, uzorak) događa se na strani klijenta nakon primitka