Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Il-Modalità JSON u l-Infurzar tal-Iskema

Lezzjoni 10 / 16 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Il-Modalità JSON u l-Infurzar tal-Iskema
  2. Il-Modalità JSON vs l-Output I strutturati
  3. Output I strutturati b’JSON Schema
  4. Regoli għal Output I strutturati Stretti
  5. Għajnuna għall-Bini tal-Iskemi
  6. Eżempju: Estrazzjoni ta’ Data I strutturata
  7. Il-Kejl ta’ Dak li Ġġib il-Vincolu
  8. Punti Ewlenin

Lezzjoni aġġornata fit-3 ta’ Novembru, 2026 ibbażata fuq id-dokumentazzjoni ta’ OpenAI: temperature u top_p huma 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ċifikaw reasoning={"effort": "none"} (API tar-Risposti) jew reasoning_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: true għall-ogħla konformità
  • Il-kampijiet kollha jridu jkunu required b’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