Lähe põhisisu juurde
Eesti— Vali keel
Menüü

JSON-režiim ja skeemi jõustamine

Õppetund 10 / 16 Värskendatud 3. november 2026 Arendajatele
Sellel lehel
  1. JSON-režiim ja skeemi jõustamine
  2. JSON-režiim vs struktureeritud väljund
  3. Struktureeritud väljund JSON-skeemiga
  4. Range struktureeritud väljundi reeglid
  5. Abivahend skeemide loomiseks
  6. Näide: struktureeritud andmete ekstraheerimine
  7. Piirangu väärtuse mõõtmine
  8. Peamised punktid

Tund uuendatud 3. novembril 2026 OpenAI dokumentatsiooni põhjal: parameetreid temperature ja top_p aktsepteeritakse ainult siis, kui arutluse pingutus on none, samas kui GPT-5.6 mudelid kasutavad vaikimisi arutlust (medium). Seetõttu peavad need parameetrid määravad päringud sisaldama reasoning={"effort": "none"} (Responses API) või reasoning_effort="none" (Chat Completions). Allikad: GPT-6 kasutamine · GPT-5.6 Terra.

JSON-režiim ja skeemi jõustamine

OpenAI struktureeritud väljund garanteerib, et mudeli vastus on kehtiv JSON, mis järgib sinu defineeritud skeemi. Regexiga habras parsimine või vorminguvead on minevik – piirangut rakendatakse juba genereerimise tasandil.

See nüanss on kriitiline ja muudab arendaja jaoks kõike. Kui palud vihjes „vasta JSON-is“, on see pigem anumine: mudel kuuletub enamasti, kuid ühel päeval lisab ta vastuse ette „Siin on soovitud JSON:“, paneb Markdowni tagasideed või unustab komaga, ja sinu json.loads viskab tootmises erandi kell 3 öösel nädala suurima partii töötlemisel. Struktureeritud väljundi korral rakendub piirang dekodeerimise ajal: tokeneid, mis tekitaksid kehtetu või mittevastava JSON-i, lihtsalt ei valita. Lõpeta anumine ja hakka jõustama.

JSON-režiim vs struktureeritud väljund

OpenAI pakub kahte piirangu taset ja erinevus seisneb ühes sõnas. JSON-režiim garanteerib kehtiva JSON-i ilma struktuuriliste piiranguteta; struktureeritud väljund garanteerib JSON-i, mis järgib sinu kirjutatud JSON-skeemi.

JSON-režiim lahendab pool probleemi. Oled kindel, et saad vastuse parsida, kuid ei tea, mida see sisaldab: mudel võib ühel päringul nimetada välja annee ja järgmisel year või pakendada oma loendi objekti resultats, mida ta eile ei kasutanud. Prototüübi või inimesele mõeldud toore kuva jaoks see piisab; niipea kui väljund toidab koodi, mis pääseb väljadele juurde nime järgi, vajad teist taset.

from openai import OpenAI

client = OpenAI()

# Lihtne JSON-režiim (kehtiv JSON, vaba struktuur)
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)

Struktureeritud väljund JSON-skeemiga

See on võimsaim funktsioon. Defineerid JSON-skeemi ja API garanteerib, et väljund sellele vastab. Allpool olev näide analüüsib kliendi arvustuse sentimenti ja illustreerib skeemi kolme täiendavat kasutusviisi.

enum väljal sentiment takistab mudelil leiutamast vahepealset kategooriat nagu „pigem positiivne“: ta peab valima nelja pakutud väärtuse vahel, muutes väljundi otse kasutatavaks filtris või armatuurlaual. Välja score kirjeldus (description) toimib kohaliku minivihjena, näidates oodatavat skaalat ilma, et peaksid seda üldistes juhistes selgitama, ja see jääb väljaga seotuks isegi siis, kui vihje muutub. Lõpuks võimaldab massiiv aspects lahata vastuolulist arvustust – siin meeldib toode, kuid tarne ebaõnnestus – selle asemel, et see nüanss purustada üheks skooriks, millest pole kellelegi kasu.

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)
# Garanteeritud: result sisaldab täpselt defineeritud välju
print(f"Sentiment: {result['sentiment']}")
print(f"Score: {result['score']}")
for aspect in result["aspects"]:
    print(f"  - {aspect['aspect']}: {aspect['sentiment']}")

Range struktureeritud väljundi reeglid

Režiim strict: true seab skeemile oma piirangud. Kõik väljad peavad ilmuma võtmes required ja additionalProperties peab olema false igal objektil. Lubatud tüübid on string, number, integer, boolean, array, object ja null, lisaks enum väärtuste piiramiseks. Siiski ei aktsepteerita ei pattern ega minLength/maxLength: peeneteraline valideerimine toimub kliendi poolel.

Need reeglid võivad esimesel korral üllatada, kuna need keelavad vabatahtliku välja nii, nagu see JSON-skeemis tavaliselt kirjutatakse. Kompromiss on mugav: sinu kood ei pea kunagi testima, kas võti on olemas; see on alati kohal. Välja jaoks, mis võib õigustatult olla tühi – näiteks dokumendist puuduv telefoninumber või käimasoleva lepingu lõppkuupäev – ei ole lahenduseks selle eemaldamine required loendist, vaid lubamine olla null. Mis puutub pattern ja pikkuse piirangute puudumisse, siis see viitab järgmisele tunnile: skeem garanteerib vormi, kuid ärireeglite valideerimine jääb sinu ülesandeks pärast vastuse saamist.

Abivahend skeemide loomiseks

Ploki text.format käsitsi kirjutamine iga päringu jaoks muutub kiiresti tüütuks ja vigade altiks – puuduv võti name, valesti paigutatud strict ja API tagastab vea, näitamata, kust otsida. Mõned read abikoodi tsentraliseerivad struktuuri, rakendavad vaikimisi madalat temperatuuri (kuna varieeruvus ei lisa ekstraheerimisele midagi) ja muudavad päringukoha loetavaks.

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)

Näide: struktureeritud andmete ekstraheerimine

Siin on kasutusjuhtum, mis üksi õigustab selle tehnika õppimist: lihttekstina saabunud arve teisendamine objektiks, mida sinu raamatupidamissüsteem kasutada saab. Skeem kirjeldab kolme taset – arve päis, pesastatud objekt vendor ja massiiv lines, kus igal elemendil on sama kuju. Mudel peab seega nii leidma dokumendis laiali oleva info kui ka paigutama selle õigesse kohta, sealhulgas tunnipõhise rea puhul, kus ühikhinda mõistetakse tunnihinnana.

Pane tähele, et summad ilmuvad skeemi väljadena, mida tuleb ekstraheerida, mitte ümber arvutada. Palume mudelil lugeda; aritmeetika kontroll toimub hiljem sinu koodis, kus lihtne võrdlus ridade summa ja ekstraheeritud total_ht vahel märgistab dokumendid inimülevaatuseks.

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."
)

Piirangu väärtuse mõõtmine

Rakenda seda põhimõtet dokumendile, mida hästi tunned: defineeri JSON-skeem CV-st põhiteabe (nimi, kogemus, oskused, haridus) ekstraheerimiseks ja testi seda kolmel lihttekstis CV-l, mis on tahtlikult valitud oma heterogeense paigutuse tõttu. Veendu, et väljund järgib skeemi isegi siis, kui mõni sektsioon on täiesti puudu.

Seejärel korda sama ekstraheerimist ilma struktureeritud väljundita, paludes vihjes lihtsalt JSON-i, ja hoia kuus väljundit kõrvuti. Kahe seeria võrdlemine näitab, mida piirang annab: erinevus seisneb harva ekstraheeritud sisus, peaaegu alati väljanimede stabiilsuses ja oodatud võtmete olemasolus.

Peamised punktid

  • Struktureeritud väljund garanteerib genereerimise tasandil skeemile vastava JSON-i
  • Kasuta maksimaalse vastavuse saavutamiseks strict: true
  • Kõik väljad peavad olema required koos additionalProperties: false
  • Ideaalne andmete ekstraheerimiseks, klassifitseerimiseks ja töötlemise torustike jaoks
  • Peeneteraline valideerimine (pikkus, muster) toimub kliendi poolel pärast vastuvõtmist