Il-Modalità JSON u l-Infurzar tal-Iskema
F'din il-paġna
Lezzjoni aġġornata fit-3 ta’ Novembru, 2026 ibbażata fuq id-dokumentazzjoni ta’ OpenAI:
temperatureutop_phuma aċċettati biss b’sforz ta’ raġunar ta’none, filwaqt li l-mudelli GPT-5.6 jirraġunaw b’mod default (medium). Għalhekk, is-sejħiet li jistabbilixxu dawn il-parametri jridu jispeċifikawreasoning={"effort": "none"}(API tar-Risposti) jewreasoning_effort="none"(Tlestijiet taċ-Chat). Sorsi: L-użu ta’ GPT-6 · GPT-5.6 Terra.
Il-Modalità JSON u l-Infurzar tal-Iskema
L-Output I strutturati ta’ OpenAI jiggarantixxi li r-risposta tal-mudell tkun JSON validu li jikkonforma ma’ skema li tiddefinixxi int. Ebda parsing fraġli b’regex jew żbalji fil-format aktar—il-vincolu jiġi applikat fil-livell tal-ġenerazzjoni nnifsu.
Din in-nuansa hija kritika, u tbiddel kollox għal żviluppatur. Li titlob “wieġeb f’JSON” fil-prompt hija talba: il-mudell jobdi ħafna drabi, imma xi darba jippreċedi r-risposta tiegħu b‘“Hawn hu l-JSON mitlub:”, iżid backticks ta’ Markdown, jew jinsa comma, u l-json.loads tiegħek itefa’ eċċezzjoni fil-produzzjoni fit-3 ta’ filgħodu fuq l-akbar batch tal-ġimgħa. Bl-Output I strutturati, il-vincolu jiġi applikat waqt id-decoding: it-tokens li jipproduċu JSON invalidu jew li ma jikkonformax sempliċiment ma jistgħux jintgħażlu. Tieqaf titlob u tibda tinforza.
Il-Modalità JSON vs l-Output I strutturati
OpenAI toffri żewġ livelli ta’ vincolu, u d-distinzjoni tiddependi fuq kelma waħda. Il-Modalità JSON tiggarantixxi JSON validu mingħajr ebda vincoli strutturali; l-Output I strutturati jiggarantixxi JSON li jikkonforma ma’ JSON Schema li ktibt int.
Il-Modalità JSON issolvi nofs il-problema. Inti żgur li tista’ tipparseja r-risposta, iżda mhux żgur x’fiha: il-mudell jista’ jsejjaħ kamp annee fuq talba waħda u year fuq oħra, jew jgħaqqad il-lista tiegħu f’oġġett resultats li ma użax il-jum ta’ qabel. Għal prototip jew wiri mhux ipproċessat maħsub għal bniedem, dan biżżejjed; hekk kif l-output jingħata lil kodiċi li jaċċessa l-kampijiet bl-isem, għandek bżonn it-tieni livell.
from openai import OpenAI
client = OpenAI()
# Modalità JSON sempliċi (JSON validu, struttura ħielsa)
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)
Output I strutturati b’JSON Schema
Din hija l-aktar karatteristika qawwija. Inti tiddefinixxi skema JSON, u l-API tiggarantixxi li l-output jaderixxi magħha. L-eżempju hawn taħt janalizza s-sentiment ta’ reviżjoni ta’ klijent u juri tliet użi komplementari tal-iskema.
L-enum fuq sentiment jipprevjeni lill-mudell milli jinventa kategorija intermedjarja bħal “pjuttost pożittiv”: irid jagħżel bejn l-erba’ valuri pprovduti, u b’hekk jagħmel l-output direttament użabbli f’filtru jew dashboard. Id-description tal-kamp score taġixxi bħala mini-prompt lokali, li tindika l-iskala mistennija mingħajr ma teħtieġ li tispjegaha fl-istruzzjonijiet ġenerali, u tibqa’ marbuta mal-kamp anke jekk il-prompt jevolvi. Fl-aħħar nett, l-array aspects jippermettilek li tiddekomponi reviżjoni kontradittorja—hawnhekk, prodott li għoġob iżda l-konsenja falliet—minflok ma tgħaffeġ dik in-nuansa f’punteġġ wieħed li ma jgħin lil ħadd.
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)
# Iggarantit: result għandu eżattament il-kampijiet definiti
print(f"Sentiment: {result['sentiment']}")
print(f"Score: {result['score']}")
for aspect in result["aspects"]:
print(f" - {aspect['aspect']}: {aspect['sentiment']}")
Regoli għal Output I strutturati Stretti
Il-modalità strict: true timponi l-vincoli tagħha stess fuq l-iskema. Il-kampijiet kollha jridu jidhru f’required, u additionalProperties irid ikun false fuq kull oġġett. It-tipi permessi huma string, number, integer, boolean, array, object, u null, flimkien ma’ enum biex tillimita l-valuri. Madankollu, la pattern u lanqas minLength/maxLength huma aċċettati: il-validazzjoni fina sseħħ fuq in-naħa tal-klijent.
Dawn ir-regoli jistgħu jkunu sorprendenti fl-ewwel tentattiv għax jipprojbixxu l-kamp fakultattiv kif miktub normalment f’JSON Schema. Il-kompromess huwa komdu: il-kodiċi tiegħek qatt m’għandu bżonn jittestja jekk ċavetta teżistix; hija dejjem hemm. Għal kamp li leġittimament jista’ jkun vojt—numru tat-telefon nieqes minn dokument, data tat-tmiem għal kuntratt għaddej—it-tweġiba mhix li tneħħih minn required iżda li tippermettilu jkun null. Fir-rigward tan-nuqqas ta’ pattern u limiti ta’ tul, dan jissinjala l-lezzjoni li jmiss: l-iskema tiggarantixxi l-forma, iżda l-validazzjoni tan-negozju tibqa’ xogħlok darba li tirċievi r-risposta.
Għajnuna għall-Bini tal-Iskemi
Il-kitba manwali tal-blokk text.format għal kull sejħa malajr issir tedjanti u suxxettibbli għal żbalji tat-tipografija—ċavetta name nieqsa, strict f’post ħażin, u l-iżball jerġa’ jiġi mill-API mingħajr ma jindika fejn tfittex. Ftit linji ta’ kodiċi wrapper jiċċentralizzaw l-istruttura, japplikaw temperatura baxxa b’mod default (peress li l-varjabbiltà ma żżid xejn għall-estrazzjoni), u jagħmlu s-sit tas-sejħa leġibbli.
def structured_query(prompt: str, schema: dict,
schema_name: str = "response",
model: str = "gpt-5.6-terra",
system: str = "") -> dict:
"""Wrapper għal talbiet ta' Output I strutturati."""
response = client.responses.create(
model=model,
reasoning={"effort": "none"}, # it-temperature teħtieġ sforz 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)
Eżempju: Estrazzjoni ta’ Data I strutturata
Hawn hu l-każ ta’ użu li waħdu jiġġustifika t-tagħlim ta’ din it-teknika: it-trasformazzjoni ta’ fattura riċevuta bħala test sempliċi f’oġġett użabbli mis-sistema kontabilistika tiegħek. L-iskema tiddeskrivi tliet livelli—l-intestatura tal-fattura, oġġett imqiegħed ġewwa vendor, u array lines fejn kull element għandu l-istess forma. Il-mudell għandu għalhekk kemm jillokalizza informazzjoni mxerrda mad-dokument kif ukoll ipoġġiha fil-post it-tajjeb, inkluż għal linja espressa f’sigħat minflok unitajiet, fejn il-prezz unitarju jinftiehem bħala rata fis-siegħa.
Innota li t-totali jidhru fl-iskema bħala kampijiet li għandhom jiġu estratti, mhux biex jiġu kkalkolati mill-ġdid. Nitolbu lill-mudell jaqra; il-kontroll aritmetiku jseħħ wara fil-kodiċi tiegħek, fejn paragun sempliċi bejn is-somma tal-linji u l-total_ht estratt jiffaċilita d-dokumenti għal reviżjoni umana.
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."
)
Il-Kejl ta’ Dak li Ġġib il-Vincolu
Applika dan il-prinċipju għal dokument li taf sew: iddefinixxi skema JSON biex testraċi informazzjoni ewlenija minn curriculum vitae—isem, esperjenza, ħiliet, edukazzjoni—u ttestjah fuq tliet CVs ta’ test sempliċi magħżula deliberatament għal-layouts eteroġenji tagħhom. Iverifika li l-output jirrispetta l-iskema anke meta taqsima tkun nieqsa għalkollox.
Imbagħad erġa’ agħmel l-istess estrazzjoni mingħajr Output I strutturati, sempliċiment titlob JSON fil-prompt, u żomm is-sitt outputs ħdejn xulxin. Il-paragun bejn iż-żewġ serje juri x’ġieb il-vincolu: id-differenza rari tkun fil-kontenut estratt, kważi dejjem fl-istabbiltà tal-ismijiet tal-kampijiet u l-preżenza taċ-ċwievet mistennija.
Punti Ewlenin
- L-Output I strutturati jiggarantixxi JSON li jikkonforma mal-iskema fil-livell tal-ġenerazzjoni
- Uża
strict: truegħall-ogħla konformità - Il-kampijiet kollha jridu jkunu
requiredb’additionalProperties: false - Ideali għall-estrazzjoni tad-data, il-klassifikazzjoni, u l-pipelines tal-ipproċessar
- Il-validazzjoni fina (tul, mudell) iseħħ fuq in-naħa tal-klijent wara r-riċeviment