Način JSON in uveljavljanje sheme
Na tej strani
Lekcija posodobljena 3. novembra 2026 na podlagi dokumentacije OpenAI: parametra
temperatureintop_psta sprejeta le pri naporu razmišljanja (reasoning effort) vrednostinone, medtem ko modeli GPT-5.6 privzeto razmišljajo (medium). Klici, ki nastavljajo te parametre, morajo zato določitireasoning={"effort": "none"}(API za odzive) alireasoning_effort="none"(Chat Completions). Viri: Uporaba GPT-6 · GPT-5.6 Terra.
Način JSON in uveljavljanje sheme
Strukturirani izhod (Structured Output) podjetja OpenAI zagotavlja, da je odgovor modela veljaven JSON, ki sledi shemi, ki jo določiš ti. Ni več krhkega razčlenjevanja z regularnimi izrazi ali napak zaradi formatiranja – omejitev se uporabi že na ravni samega generiranja.
Ta odtenek je ključen in za razvijalca spremeni vse. Če v pozivu napišeš „odgovori v JSON-u”, je to prošnja: model večinoma uboga, a nekega dne bo odgovoru dodal predpono „Tukaj je zahtevani JSON:”, vključil povratne poševnice Markdown ali pozabil vejico, tvoj json.loads pa bo ob 3. zjutraj med največjo tedensko obdelavo serije vrgel izjemo. Pri strukturiranem izhodu se omejitev uporabi med dekodiranjem: žetoni, ki bi ustvarili neveljaven ali neustrezen JSON, preprosto ne morejo biti izbrani. Prenehaš prositi in začneš uveljavljati.
Način JSON proti strukturiranemu izhodu
OpenAI ponuja dve ravni omejitev, razlika pa visi na eni sami besedi. Način JSON zagotavlja veljaven JSON brez strukturnih omejitev; strukturirani izhod zagotavlja JSON, ki ustreza shemi JSON Schema, ki si jo napisal.
Način JSON reši polovico težave. Prepričan si, da lahko odgovor razčleniš, nisi pa prepričan, kaj vsebuje: model lahko v enem zahtevku poimenuje polje annee, v naslednjem pa year, ali pa svoj seznam ovije v objekt resultats, ki ga prejšnji dan ni uporabil. Za prototip ali surov prikaz, namenjen človeku, to zadostuje; takoj ko izhod napaja kodo, ki dostopa do polj po imenu, potrebuješ drugo raven.
from openai import OpenAI
client = OpenAI()
# Preprost način JSON (veljaven JSON, prosta 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 izhod s shemo JSON
To je najzmogljivejša funkcija. Določiš shemo JSON in API zagotavlja, da se izhod drži nje. Spodnji primer analizira sentiment mnenja stranke in ponazarja tri komplementarne uporabe sheme.
enum pri polju sentiment preprečuje, da bi model izumil vmesno kategorijo, kot je „precej pozitiven”: izbrati mora med štirimi podanimi vrednostmi, kar omogoča neposredno uporabo izhoda v filtru ali nadzorni plošči. description polja score deluje kot lokalni mini-poziv, ki označuje pričakovano lestvico, ne da bi jo moral razlagati v splošnih navodilih, in ostane pripeta polju, tudi če se poziv spremeni. Nazadnje, polje aspects kot niz omogoča razčlenitev protislovnega mnenja – tukaj izdelek všeč, dostava pa katastrofalna – namesto da bi to nianso zdrobili v eno samo oceno, ki nikomur ne koristi.
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)
# Zagotovljeno: result ima točno določena 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 izhod
Način strict: true nalaga lastne omejitve shemi. Vsa polja morajo biti navedena v required, additionalProperties pa mora biti false pri vsakem objektu. Dovoljeni tipi so string, number, integer, boolean, array, object in null, plus enum za omejitev vrednosti. Vendar niti pattern niti minLength/maxLength nista sprejeta: podrobno preverjanje veljavnosti poteka na strani odjemalca.
Ta pravila so ob prvem poskusu lahko presenetljiva, saj prepovedujejo izbirna polja, kot so običajno zapisana v shemi JSON Schema. Kompromis je udoben: tvoja koda nikoli ne mora preverjati, ali ključ obstaja; vedno je tam. Za polje, ki je lahko upravičeno prazno – na primer manjkajoča telefonska številka v dokumentu ali datum konca za tekočo pogodbo – odgovor ni odstranitev iz required, temveč dovoljenje, da ima vrednost null. Kar zadeva odsotnost pattern in omejitev dolžine, to signalizira naslednjo lekcijo: shema zagotavlja obliko, poslovno preverjanje veljavnosti pa ostane tvoje opravilo, ko prejmeš odgovor.
Pomočnik za gradnjo shem
Ročno pisanje bloka text.format za vsak klic hitro postane dolgočasno in dovzetno za tipkarske napake – manjkajoč ključ name, napačno postavljen strict in napaka se vrne od API-ja, ne da bi kazala, kam gledati. Nekaj vrstic ovijalne kode centralizira strukturo, privzeto uporabi nizko temperaturo (saj variabilnost pri ekstrakciji ničesar ne doda) in naredi mesto klica berljivo.
def structured_query(prompt: str, schema: dict,
schema_name: str = "response",
model: str = "gpt-5.6-terra",
system: str = "") -> dict:
"""Ovijalnik za zahteve strukturiranega izhoda."""
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)
Primer: Ekstrakcija strukturiranih podatkov
Tukaj je primer uporabe, ki sam po sebi upravičuje učenje te tehnike: pretvorba računa, prejetega kot golo besedilo, v objekt, uporaben za tvoj računovodski sistem. Shema opisuje tri ravni – glavo računa, gnezdeni objekt vendor in niz lines, kjer ima vsak element enako obliko. Model mora torej tako locirati informacije, razpršene po dokumentu, kot jih postaviti na pravo mesto, vključno za vrstico, izraženo v urah namesto v enotah, kjer se cena na enoto razume kot urna postavka.
Upoštevaj, da se vsote v shemi pojavljajo kot polja za ekstrakcijo, ne za ponovni izračun. Model prosimo, naj bere; aritmetični nadzor se zgodi kasneje v tvoji kodi, kjer bo preprosta primerjava med vsoto vrstic in izvlečenim total_ht označila dokumente za človeški 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."
)
Merjenje koristi omejitve
To načelo uporabi na dokumentu, ki ga dobro poznaš: določi shemo JSON za ekstrakcijo ključnih informacij iz življenjepisa – ime, izkušnje, veščine, izobrazba – in jo preizkusi na treh življenjepisih v golo besedilo, namerno izbranih zaradi njihovih heterogenih postavitev. Preveri, ali izhod spoštuje shemo, tudi ko kakšen razdelek popolnoma manjka.
Nato ponovi isto ekstrakcijo brez strukturiranega izhoda, tako da v pozivu preprosto zahtevaš JSON, in obdrži vseh šest izhodov drug ob drugem. Primerjava obeh serij pokaže, kaj prinaša omejitev: razlika redko leži v izvlečeni vsebini, skoraj vedno pa v stabilnosti imen polj in prisotnosti pričakovanih ključev.
Ključne ugotovitve
- Strukturirani izhod zagotavlja JSON, ki ustreza shemi, na ravni generiranja
- Uporabi
strict: trueza največjo skladnost - Vsa polja morajo biti
requiredzadditionalProperties: false - Idealno za ekstrakcijo podatkov, klasifikacijo in obdelovalne cevovode
- Podrobno preverjanje veljavnosti (dolžina, vzorec) poteka na strani odjemalca po prejemu