Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

JSON-tila ja skeeman valvonta

Oppitunti 10 / 16 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. JSON-tila ja skeeman valvonta
  2. JSON-tila vs. rakenteellinen tulostus
  3. Rakenteellinen tulostus JSON-skeemalla
  4. Säännöt tiukalle rakenteelliselle tulostukselle
  5. Apuri skeemojen rakentamiseen
  6. Esimerkki: Rakenteellinen tiedonpoiminta
  7. Rajoitteen tuoman hyödyn mittaaminen
  8. Keskeiset asiat

Oppitunti päivitetty 3. marraskuuta 2026 OpenAI:n dokumentaation perusteella: temperature ja top_p hyväksytään vain, kun päättelypyrkimys on none, kun taas GPT-5.6-mallit päättelevät oletusarvoisesti (medium). Näitä parametreja käyttävien kutsujen on siksi määritettävä reasoning={"effort": "none"} (Responses API) tai reasoning_effort="none" (Chat Completions). Lähteet: Using GPT-6 · GPT-5.6 Terra.

JSON-tila ja skeeman valvonta

OpenAI:n rakenteellinen tulostus (Structured Output) takaa, että mallin vastaus on kelvollista JSONia, joka noudattaa määrittelemääsi skeemaa. Ei enää hauraita regex-parsintoja tai muotovirheitä – rajoite sovelletaan itse generointivaiheessa.

Tämä vivahde on kriittinen, ja se muuttaa kaiken kehittäjän kannalta. Kehotteen pyytäminen “vastaa JSON-muodossa” on anelua: malli tottelee useimmiten, mutta eräänä päivänä se lisää vastauksen eteen lauseen “Tässä pyydetty JSON:”, käärii sisällön Markdown-koodilohkoon tai unohtaa pilkun, jolloin json.loads heittää poikkeuksen tuotannossa kello 3 yöllä viikon suurimman erän käsittelyn aikana. Rakenteellisessa tulostuksessa rajoite voimassa dekoodauksen aikana: tokeneita, jotka tuottaisivat virheellistä tai vaatimusten vastaista JSONia, ei yksinkertaisesti voi valita. Lopetat anelemisen ja siirryt valvomaan.

JSON-tila vs. rakenteellinen tulostus

OpenAI tarjoaa kaksi rajoitustasoa, ja ero riippuu yhdestä sanasta. JSON-tila takaa kelvollisen JSONin ilman rakenteellisia rajoitteita; rakenteellinen tulostus takaa JSONin, joka noudattaa kirjoittamaasi JSON-skeemaa.

JSON-tila ratkaisee puolet ongelmasta. Olet varma, että voit jäsentää vastauksen, mutta et tiedä, mitä se sisältää: malli saattaa nimetä kentän annee yhdessä pyynnössä ja year seuraavassa, tai kääriä listansa resultats-objektiin, jota se ei käyttänyt edellisenä päivänä. Prototyyppiä tai ihmiselle tarkoitettua raakatulostusta varten tämä riittää; heti kun syöte syöttää koodia, joka käyttää kenttiä nimen perusteella, tarvitset toisen tason.

from openai import OpenAI

client = OpenAI()

# Yksinkertainen JSON-tila (kelvollinen JSON, vapaa rakenne)
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)

Rakenteellinen tulostus JSON-skeemalla

Tämä on tehokkain ominaisuus. Määrittelet JSON-skeeman, ja API takaa tulosteen noudattavan sitä. Alla oleva esimerkki analysoi asiakasarvostelun tunnelman ja havainnollistaa skeeman kolmea täydentävää käyttötarkoitusta.

sentiment-kentän enum estää mallia keksimästä väliluokkia kuten “melko positiivinen”: sen on valittava annetuista neljästä arvosta, mikä tekee tuloksesta suoraan käytettävän suodattimessa tai kojelaudassa. score-kentän description toimii paikallisena minikehotteena, joka ilmoittaa odotetun asteikon ilman, että sinun tarvitsee selittää sitä yleisissä ohjeissa, ja se pysyy kiinni kentässä, vaikka kehote muuttuisi. Lopuksi aspects-taulukko mahdollistaa ristiriitaisen arvostelun purkamisen – tässä tapauksessa tuote miellytti, mutta toimitus epäonnistui – sen sijaan, että tämä vivahde litistettäisiin yhdeksi pisteeksi, josta ei ole kenellekään hyötyä.

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)
# Taattu: result sisältää täsmälleen määritellyt kentät
print(f"Sentiment: {result['sentiment']}")
print(f"Score: {result['score']}")
for aspect in result["aspects"]:
    print(f"  - {aspect['aspect']}: {aspect['sentiment']}")

Säännöt tiukalle rakenteelliselle tulostukselle

strict: true -tila asettaa omat rajoituksensa skeemalle. Kaikkien kenttien on esiinnyttävä kohdassa required, ja additionalProperties on oltava false jokaisessa objektissa. Sallitut tyypit ovat string, number, integer, boolean, array, object ja null, sekä enum arvojen rajoittamiseen. Sen sijaan pattern eikä minLength/maxLength ole hyväksyttyjä: tarkka validointi tapahtuu asiakaspuolella.

Nämä säännöt voivat yllättää ensimmäisellä kerralla, koska ne kieltävät valinnaiset kentät sellaisina kuin ne yleensä kirjoitetaan JSON-skeemassa. Kompromissi on kuitenkin mukava: koodisi ei koskaan joudu testaamaan, onko avain olemassa; se on aina paikallaan. Kentälle, joka voi laillisesti olla tyhjä – esimerkiksi puhelinnúmero, joka puuttuu asiakirjasta, tai päättymispäivä voimassa olevalle sopimukselle – ratkaisu ei ole poistaa sitä kohdasta required, vaan sallia sen olevan null. Mitä tulee patternin ja pituusrajoitusten puuttumiseen, se viittaa seuraavaan oppituntiin: skeema takaa muodon, mutta liiketoiminnan validointi jää sinun tehtäväksesi vastauksen vastaanottamisen jälkeen.

Apuri skeemojen rakentamiseen

text.format-lohkon manuaalinen kirjoittaminen jokaiseen kutsuun muuttuu nopeasti työlääksi ja alttiiksi kirjoitusvirheille – puuttuva name-avain, väärään paikkaan sijoitettu strict, ja virhe palaa API:lta ilmoittamatta, mistä etsiä. Muutama rivi käärijäkoodia keskittää rakenteen, soveltaa oletusarvoisesti matalaa lämpötilaa (koska vaihtelu ei lisää mitään tiedonpoimintaan) ja tekee kutsupaikasta luettavan.

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)

Esimerkki: Rakenteellinen tiedonpoiminta

Tässä on käyttötapa, joka yksinään oikeuttaa tekniikan opiskelun: pelkkänä tekstinä vastaanotetun laskun muuntaminen kirjanpitojärjestelmäsi käyttämäksi objektiksi. Skeema kuvaa kolmea tasoa – laskun otsikko, sisäkkäinen vendor-objekti ja lines-taulukko, jossa jokaisella alkiolla on sama muoto. Mallin on siis sekä löydettävä asiakirjan eri puolille hajautettua tietoa että sijoitettava se oikeaan paikkaan, myös riville, joka on ilmaistu tunteina yksiköiden sijaan, jolloin yksikköhinnan ymmärretään olevan tuntihinta.

Huomaa, että summat esiintyvät skeemassa kenttinä, jotka tulee poimia, ei laskea uudelleen. Pyydämme mallia lukemaan; aritmeettinen valvonta tapahtuu myöhemmin koodissasi, jossa yksinkertainen vertailu rivien summan ja poimitun total_ht:n välillä merkitsee asiakirjat ihmisen tarkistettavaksi.

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

Rajoitteen tuoman hyödyn mittaaminen

Sovella tätä periaatetta asiakirjaan, jonka tunnet hyvin: määrittele JSON-skeema avaintietojen poimimiseksi ansioluettelosta – nimi, kokemus, taidot, koulutus – ja testaa sitä kolmella pelkkänä tekstinä olevalla ansioluettelolla, jotka on valittu tarkoituksellisesti niiden heterogeenisten asettelujen perusteella. Varmista, että tuloste noudattaa skeemaa, vaikka osa-alue puuttuisi kokonaan.

Toista sitten sama poiminta ilman rakenteellista tulostusta pyytämällä kehotteessa yksinkertaisesti JSONia, ja pidä kaikki kuusi tulostetta vierekkäin. Kahden sarjan vertaaminen osoittaa, mitä rajoite tuo: ero ei harvoin ole poimitussa sisällössä, vaan lähes aina kenttien nimien vakaudessa ja odotettujen avainten olemassaolossa.

Keskeiset asiat

  • Rakenteellinen tulostus takaa skeeman mukaisen JSONin generointitasolla
  • Käytä strict: true maksimaalista yhteensopivuutta varten
  • Kaikkien kenttien on oltava required ja additionalProperties: false
  • Ihanteellinen tiedonpoimintaan, luokitteluun ja käsittelyputkiin
  • Tarkka validointi (pituus, kuvio) tapahtuu asiakaspuolella vastaanoton jälkeen