JSON režimas ir schemos vykdymas
Šiame puslapyje
Pamoka atnaujinta 2026 m. lapkričio 3 d. pagal „OpenAI“ dokumentaciją: parametrai
temperatureirtop_ppriimami tik esantnonelygio samprotavimui, tuo tarpu GPT-5.6 modeliai pagal nutylėjimą samprotauja (medium). Todėl kvietimuose, kuriuose nustatomi šie parametrai, būtina nurodytireasoning={"effort": "none"}(Responses API) arbareasoning_effort="none"(Chat Completions). Šaltiniai: Using GPT-6 · GPT-5.6 Terra.
JSON režimas ir schemos vykdymas
„OpenAI“ struktūrizuota išvestis garantuoja, kad modelio atsakymas bus tinkamas JSON, atitinkantis jūsų apibrėžtą schemą. Jokių daugiau trapių reguliariųjų išraiškų (regex) ar formato klaidų – apribojimas taikomas pačiame generavimo lygmenyje.
Ši subtilybė yra kritinė ir keičia viską kūrėjui. Prašymas „atsakyti JSON formatu“ užuominoje yra tik prašymas: modelis dažniausiai paklūsta, bet vieną dieną jis gali pradėti atsakymą fraze „Štai prašytas JSON:“, pridėti „Markdown“ kodų blokelius arba pamiršti kablelį, ir jūsų json.loads išmes išimtį gamybinėje aplinkoje 3 val. ryto didžiausios savaitės apkrovos metu. Naudojant struktūrizuotą išvestį, apribojimas taikomas dekoduavimo metu: žetonai, kurie sukurtų netinkamą arba reikalavimų neatitinkantį JSON, tiesiog negali būti pasirinkti. Nustojate maldauti ir pradedate reikalauti.
JSON režimas prieš struktūrizuotą išvestį
„OpenAI“ siūlo du apribojimo lygius, o skirtumas slypi viename žodyje. JSON režimas garantuoja tinkamą JSON be struktūrinių apribojimų; struktūrizuota išvestis garantuoja JSON, atitinkantį jūsų parašytą JSON schemą.
JSON režimas išsprendžia tik pusę problemos. Esate tikri, kad galėsite išanalizuoti atsakymą, bet nesate tikri, ką jis turės: modelis viename užklausime gali pavadinti lauką annee, o kitame – year, arba įvilkti sąrašą į resultats objektą, kurio prieš dieną nenaudojo. Prototipui arba žmogui skirtam neapdorotam rodymui to pakanka; tačiau kai tik išvestis maitina kodą, kuris pasiekia laukus pagal pavadinimą, jums reikia antrojo lygio.
from openai import OpenAI
client = OpenAI()
# Paprastas JSON režimas (tinkamas JSON, laisva struktūra)
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)
Struktūrizuota išvestis naudojant JSON schemą
Tai galingiausia funkcija. Jūs apibrėžiate JSON schemą, o API garantuoja, kad išvestis jai paklus. Toliau pateiktame pavyzdyje analizuojamas kliento atsiliepimo sentimentas ir iliustruojami trys papildomi schemos naudojimo būdai.
enum lauke sentiment neleidžia modeliui išgalvoti tarpinės kategorijos, pavyzdžiui, „greičiau teigiamas“: jis turi rinktis iš keturių pateiktų reikšmių, todėl išvestį galima tiesiogiai naudoti filtre arba skydelyje. Lauko score aprašymas (description) veikia kaip vietinė mini-užuomina, nurodanti tikėtiną skalę, nereikalaujant to aiškinti bendrose instrukcijose, ir jis lieka susietas su lauku net evoliucionuojant užuominai. Galiausiai masyvas aspects leidžia išskaidyti prieštaringą atsiliepimą – čia produktas patiko, bet pristatymas žlugo – užuot suspaudus šią niuansą į vieną balą, kuris niekam nepadeda.
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)
# Garantuoja: result turi tiksliai apibrėžtus laukus
print(f"Sentiment: {result['sentiment']}")
print(f"Score: {result['score']}")
for aspect in result["aspects"]:
print(f" - {aspect['aspect']}: {aspect['sentiment']}")
Griežtos struktūrizuotos išvesties taisyklės
Režimas strict: true schemai taiko savo apribojimus. Visi laukai privalo būti nurodyti required, o additionalProperties turi būti false kiekviename objekte. Leidžiami tipai yra string, number, integer, boolean, array, object ir null, plius enum reikšmėms apriboti. Tačiau nei pattern, nei minLength/maxLength nėra priimami: detalus validavimas atliekamas kliento pusėje.
Šios taisyklės pirmą kartą gali nustebinti, nes jos draudia nebūtinus laukus taip, kaip jie paprastai rašomi JSON schemoje. Kompromisas yra patogus: jūsų kodui niekada nereikia tikrinti, ar raktas egzistuoja; jis visada yra ten. Laukui, kuris teisėtai gali būti tuščias – pavyzdžiui, telefono numerio trūkumas dokumente arba sutarties pabaigos data vykstančiai sutarčiai – sprendimas yra ne pašalinti jį iš required, o leisti jam būti null. O pattern ir ilgio ribų nebuvimas signalizuoja kitą pamoką: schema garantuoja formą, tačiau verslo validavimas lieka jūsų darbu, kai atsakymas jau gautas.
Pagalbinė funkcija schemoms kurti
Rankinis text.format bloko rašymas kiekvienam kvietimui greitai tampa varginantis ir linkęs į klaidas – trūksta rakto name, neteisingai pastatytas strict, ir API grąžina klaidą nenurodydama, kur ieškoti. Keletas eilučių apvyniojimo kodo centralizuoja struktūrą, pagal nutylėjimą taiko žemą temperatūrą (kadangi kintamumas ekstrakcijai nieko neduoda) ir daro kvietimo vietą skaitomą.
def structured_query(prompt: str, schema: dict,
schema_name: str = "response",
model: str = "gpt-5.6-terra",
system: str = "") -> dict:
"""Apvyniojimas struktūrizuotos išvesties užklausoms."""
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)
Pavyzdys: struktūrizuotų duomenų ekstrakcija
Štai naudojimo atvejis, kuris vienas pateisina šios technikos mokymąsi: sąskaitos faktūros, gautos kaip paprastas tekstas, pavertimas objektu, tinkamu jūsų apskaitos sistemai. Schema aprašo tris lygius – sąskaitos antraštę, įdėtą vendor objektą ir masyvą lines, kurio kiekvienas elementas turi tą pačią formą. Modelis todėl turi tiek surasti informaciją, išbarstytą visame dokumente, tiek patalpinti ją į tinkamą vietą, įskaitant atvejį, kai eilutė išreikšta valandomis, o ne vienetais, kur vieneto kaina suprantama kaip valandinis įkainis.
Atkreipkite dėmesį, kad schemoje sumos atsiranda kaip laukai ekstrahavimui, o ne perskaičiavimui. Mes prašome modelio skaityti; aritmetinė kontrolė vykdoma vėliau jūsų kode, kur paprastas eilučių sumos palyginimas su ekstrahuota total_ht pažymės dokumentus, kuriuos turi peržiūrėti žmogus.
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."
)
Apribojimo teikiamos naudos matavimas
Pritaikykite šį principą jums gerai žinomam dokumentui: apibrėžkite JSON schemą pagrindinei informacijai iš gyvenimo aprašymo ekstrahuoti – vardas, patirtis, įgūdžiai, išsilavinimas – ir išbandykite ją su trimis paprasto teksto gyvenimo aprašymais, tyčia parinktais dėl jų nevienalyčių išdėstymų. Patikrinkite, ar išvestis laikosi schemos net tada, kai kuri nors skiltis visiškai trūksta.
Tada pakartokite tą pačią ekstrakciją be struktūrizuotos išvesties, tiesiog prašydami JSON užuominoje, ir gretai palikite šešis rezultatus. Palyginus dvi serijas matyti, ką duoda apribojimas: skirtumas retai slypi ekstrahuotame turinyje, beveik visada – laukų pavadinimų stabilume ir tikėtinų raktų buvime.
Svarbiausi punktai
- Struktūrizuota išvestis generavimo lygmenyje garantuoja schemą atitinkantį JSON
- Naudokite
strict: truemaksimaliam atitikimui - Visi laukai privalo būti
required, oadditionalPropertiesturi būtifalse - Idealu duomenų ekstrakcijai, klasifikacijai ir apdorojimo grandinėms
- Detalūs validavimai (ilgis, šablonas) atliekami kliento pusėje po gavimo