JSON-tila ja skeeman valvonta
Tällä sivulla
Oppitunti päivitetty 3. marraskuuta 2026 OpenAI:n dokumentaation perusteella:
temperaturejatop_phyväksytään vain, kun päättelypyrkimys onnone, 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) taireasoning_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: truemaksimaalista yhteensopivuutta varten - Kaikkien kenttien on oltava
requiredjaadditionalProperties: false - Ihanteellinen tiedonpoimintaan, luokitteluun ja käsittelyputkiin
- Tarkka validointi (pituus, kuvio) tapahtuu asiakaspuolella vastaanoton jälkeen