Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

Išvesties struktūravimas: garantuotas JSON

Paskaita 9 iš 22 Atnaujinta 2026 m. liepos 29 d. Kūrėjas
Šiame puslapyje
  1. Išvesties struktūravimas: garantuotas JSON
  2. Kokią problemą tai sprendžia
  3. „Pydantic“ vietoj ranka rašytos JSON schemos
  4. Du dažni naudojimo atvejai
  5. Ko reikalauja griežtas režimas (strict mode)
  6. Svarbiausi punktai

Išvesties struktūravimas: garantuotas JSON

Išvesties struktūravimas yra viena galingiausių „Responses API“ funkcijų. Užuot tikėjęsis, kad modelis grąžins tinkamą JSON, tu jį garantuoji pateikdamas schemą. Tuomet modelis yra struktūriškai priverstas jos laikytis. Tai paverčia kalbos modelį iš kūrybinio teksto generatoriaus į patikimą automatizuoto duomenų apdorojimo grandinės komponentą.

Kokią problemą tai sprendžia

JSON prašymas užklausoje dažniausiai veikia, tačiau būtent todėl šis metodas yra pavojingas. Vieną kartą iš šimto modelis savo atsakymą pradeda įžanginiu sakiniu, viską įvilkina į „Markdown“ kodo bloką arba pervadina laukelį – ir tavo json.loads() gamybinėje aplinkoje išmeta išimtį dėl užklausos, kurios negali atkurti.

from openai import OpenAI
client = OpenAI()

# Be struktūros – modelis gali grąžinti bet kokį formatą
response = client.responses.create(
    model="gpt-5.6-terra",
    input="Give me info about Paris in JSON."
)
print(response.output_text)
# Nenuspėjamas rezultatas:
# Kartais tinkamas JSON, kartais tekstas su JSON viduje,
# kartais netikėtas formatas...

Parametras text pakeičia garantijos pobūdį. Tu nurodai formato tipą json_schema kartu su laukiama schema, ir išvestis jai paklūsta: deserializavimas tampa saugia operacija.

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Give me information about Paris.",
    text={
        "format": {
            "type": "json_schema",
            "name": "city_info",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "country": {"type": "string"},
                    "population": {"type": "integer"},
                    "official_language": {"type": "string"},
                    "landmarks": {
                        "type": "array",
                        "items": {"type": "string"}
                    }
                },
                "required": ["name", "country", "population", "official_language", "landmarks"],
                "additionalProperties": False
            }
        }
    }
)

import json
data = json.loads(response.output_text)
print(f"City: {data['name']}")
print(f"Population: {data['population']:,}")
print(f"Landmarks: {', '.join(data['landmarks'])}")

# Rezultatas GARANTUOTAI yra tinkamas JSON:
# City: Paris
# Population: 2,161,000
# Landmarks: Eiffel Tower, Louvre, Notre-Dame, Arc de Triomphe, Sacré-Cœur

„Pydantic“ vietoj ranka rašytos JSON schemos

Schemų rašymas ranka greitai tampa varginantis ir linkęs į klaidas. „Pydantic“ leidžia jas aprašyti kaip „Python“ klases, sugeneruoti JSON schemą naudojant model_json_schema(), o tada patikrinti ir tipizuoti atsakymą su `model_validate_json()”. Grandinės pabaigoje gauni pilnavertį „Python“ objektą su redaktoriaus automatinio užbaigimo funkcija, o ne bevardį žodyną.

from pydantic import BaseModel
from typing import Optional
import json

class Product(BaseModel):
    name: str
    price: float
    category: str
    in_stock: bool
    description: Optional[str] = None

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Describe a high-end gaming laptop.",
    text={
        "format": {
            "type": "json_schema",
            "name": "product",
            "strict": True,
            "schema": Product.model_json_schema()
        }
    }
)

# Analizuojama ir tikrinama naudojant Pydantic
product = Product.model_validate_json(response.output_text)
print(f"Product: {product.name}")
print(f"Price: {product.price} EUR")
print(f"In stock: {'Yes' if product.in_stock else 'No'}")

# Rezultatas:
# Product: ASUS ROG Strix G18
# Price: 2499.99 EUR
# In stock: Yes

Niekas neapsiriboja plokščiomis struktūromis. Komponuodamas klases, gali aprašyti įdėtus objektus ir objektų sąrašus, ko prireiks kuriant realistišką kliento profilį: įmonėje yra kontaktiniai asmenys, o kiekvienas jų turi adresą.

from pydantic import BaseModel

class Address(BaseModel):
    street: str
    city: str
    postal_code: str
    country: str

class Contact(BaseModel):
    last_name: str
    first_name: str
    email: str
    phone: str
    address: Address

class Company(BaseModel):
    name: str
    sector: str
    employees: int
    contacts: list[Contact]

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Generate a fictional company profile in the tech sector "
          "with 2 contacts.",
    text={
        "format": {
            "type": "json_schema",
            "name": "company",
            "strict": True,
            "schema": Company.model_json_schema()
        }
    }
)

company = Company.model_validate_json(response.output_text)
print(f"Company: {company.name} ({company.sector})")
for c in company.contacts:
    print(f"  - {c.first_name} {c.last_name}: {c.email}")

Du dažni naudojimo atvejai

Pirmasis – duomenų išgavimas: rašytinio teksto pavertimas naudingu įrašu. Konferencijos anonansas, parašytas natūralia kalba, tampa duomenų bazės eilute su pavadinimu, data, vieta ir dalyvių skaičiumi – be reguliariųjų išraiškų ir be sutrikimų, kai pasikeičia formuluotė.

class Event(BaseModel):
    title: str
    date: str
    location: str
    attendees: int

text = """
The PyCon France 2026 conference will be held on November 15 and 16
at the Palais des Congrès in Lyon. More than 800 Python developers
are expected for this edition.
"""

response = client.responses.create(
    model="gpt-5.6-terra",
    input=f"Extract the information from this event:\n{text}",
    text={
        "format": {
            "type": "json_schema",
            "name": "event",
            "strict": True,
            "schema": Event.model_json_schema()
        }
    }
)

evt = Event.model_validate_json(response.output_text)
print(f"{evt.title} - {evt.date} at {evt.location} ({evt.attendees} attendees)")
# Rezultatas: PyCon France 2026 - November 15-16, 2026 at Lyon (800 attendees)

Antrasis – klasifikavimas. Apibrėžęs enumeraciją, apriboji modelį uždaru žodynu: jis negali atsakyti „greičiau teigiamas“ arba „teigiamas“, kai tavo kodas tikisi positive. Tai skirtumas tarp vertės, kurią gali naudoti tiesiogiai, ir vertės, kurią vėliau reikia normalizuoti.

from enum import Enum

class Sentiment(str, Enum):
    positive = "positive"
    negative = "negative"
    neutral = "neutral"

class Analysis(BaseModel):
    sentiment: Sentiment
    confidence: float
    keywords: list[str]

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Analyze this comment: 'Great service, fast delivery!'",
    text={
        "format": {
            "type": "json_schema",
            "name": "sentiment_analysis",
            "strict": True,
            "schema": Analysis.model_json_schema()
        }
    }
)

analysis = Analysis.model_validate_json(response.output_text)
print(f"Sentiment: {analysis.sentiment.value} ({analysis.confidence:.0%})")
# Rezultatas: Sentiment: positive (95%)

Ko reikalauja griežtas režimas (strict mode)

Garantija turi savo kainą: kai strict: True, schema turi atitikti specifinį JSON schemos poaibį. Šie apribojimai yra pagrindinė 400 klaidų priežastis pradedantiesiems, todėl geriausia juos žinoti iš anksto:

  • Visi laukeliai turi būti išvardyti skiltyje required
  • additionalProperties turi būti False
  • Palaikomi tipai: string, number, integer, boolean, array, object, null
  • Negalima naudoti oneOf arba anyOf su mišriais tipais
  • Naudok Optional[str], kuris išverčiamas į {"anyOf": [{"type": "string"}, {"type": "null"}]}

Taisyklė dėl required dažnai nustebina: neprivalomas laukelis išreiškiamas ne pašalinant jį iš sąrašo, o leidžiant reikšmę null, būtent tai ir sukuria Optional[str] „Pydantic“ pusėje.

Svarbiausi punktai

  • Išvesties struktūravimas garantuoja, kad atsakymas atitiks tavo JSON schemą
  • „Responses API“ naudok text={"format": {"type": "json_schema", ...}}
  • „Pydantic“ yra idealus įrankis schemoms apibrėžti ir tikrinti
  • Įjunk strict: True, kad garantuotum schemos laikymąsi
  • Idealu duomenų išgavimui, klasifikavimui ir struktūruotam generavimui