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

Väljund struktureerituna: garanteeritud JSON

Õppetund 9 / 22 Värskendatud 29. juuli 2026 Arendajatele
Sellel lehel
  1. Väljund struktureerituna: garanteeritud JSON
  2. Probleem, mida see lahendab
  3. Pydantic käsitsi kirjutatud JSON Schema asemel
  4. Kaks levinud kasutusjuhtu
  5. Mida range režiim nõuab
  6. Peamised punktid

Väljund struktureerituna: garanteeritud JSON

Väljund struktureerituna on Responses API üks võimsamaid funktsioone. Selle asemel, et loota mudeli poolt kehtiva JSON-i tagastamisele, garanteerid selle, esitades skeemi. Mudel on seejärel struktuurselt sunnitud seda järgima. See muudab keelemudeli loomingulisest tekstigeneraatorist usaldusväärseks komponendiks automatiseeritud töötlemise ahelas.

Probleem, mida see lahendab

JSON-i küsimine vihjes toimib enamasti, mis teebki selle lähenemise ohtlikuks. Ühel juhul sajast lisab mudel vastuse ette sissejuhatava lause, pakib kõik Markdowni koodiplokki või nimetab välja ümber – ja sinu json.loads() viskab tootmises erandi päringule, mida sa ei suuda reprodutseerida.

from openai import OpenAI
client = OpenAI()

# Ilma struktuurita — mudel võib tagastada ükskõik millises formaadis
response = client.responses.create(
    model="gpt-5.6-terra",
    input="Give me info about Paris in JSON."
)
print(response.output_text)
# Ettearvamatu tulemus:
# Vahel kehtiv JSON, vahel tekst, mis sisaldab JSON-i,
# vahel ootamatu formaat...

Parameeter text muudab garantii olemust. Sa deklareerid formaadi json_schema koos oodatava skeemiga ja väljund vastab sellele: deserialiseerimine muutub ohutuks operatsiooniks.

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'])}")

# Tulemus on GARANTEERITULT kehtiv JSON:
# City: Paris
# Population: 2,161,000
# Landmarks: Eiffel Tower, Louvre, Notre-Dame, Arc de Triomphe, Sacré-Cœur

Pydantic käsitsi kirjutatud JSON Schema asemel

Skeemide käsitsi kirjutamine muutub kiiresti tüütuks ja vigadele altiks. Pydantic võimaldab neid kirjeldada Pythoni klassidena, genereerida JSON Schema funktsiooniga model_json_schema() ning seejärel valideerida ja tüübistada vastus funktsiooniga model_validate_json(). Ahela lõpus saad täisväärtusliku Pythoni objekti koos redaktori automaatse täiendamisega, mitte anonüümse sõnastiku.

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()
        }
    }
)

# Parsi ja valideeri Pydanticuga
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'}")

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

Midagi ei piira sind lamedate struktuuridega. Klasse komponeerides kirjeldad pesastatud objekte ja objektide loendeid, mida vajad niipea, kui lood realistlikku kliendiprofiili: ettevõte sisaldab kontakte ja igal kontaktil on aadress.

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

Kaks levinud kasutusjuhtu

Esimene on ekstraheerimine: kirjaliku teksti muutmine kasutatavaks kirjeiks. Loomulikus keeles kirjutatud konverentsiteade muutub andmebaasi reaks, mis sisaldab pealkirja, kuupäeva, asukohta ja osalejate arvu – ilma regulaaravaldisteta ja katkemata iga kord, kui sõnastus muutub.

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)")
# Tulemus: PyCon France 2026 - November 15-16, 2026 at Lyon (800 attendees)

Teine on klassifitseerimine. Loetelu deklareerides piirad mudeli suletud sõnavaraga: ta ei saa vastata „pigem positiivne“ või „positiivne“, kui sinu kood ootab väärtust positive. See on erinevus väärtuse vahel, mida saad otse kasutada, ja väärtuse vahel, mida pead hiljem normaliseerima.

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%})")
# Tulemus: Sentiment: positive (95%)

Mida range režiim nõuab

Garantiiga kaasneb kompromiss: kui strict: True, peab skeem järgima JSON Schema spetsiifilist alamhulka. Need piirangud on algajate jaoks 400 vigade peamine põhjus, seega on kõige parem nendega enne kokkupuutumist tutvuda:

  • Kõik omadused peavad olema loetletud võtmes required
  • additionalProperties peab olema False
  • Toetatud tüübid: string, number, integer, boolean, array, object, null
  • Puuduvad oneOf või anyOf segatüüpidega
  • Kasuta Optional[str], mis tõlgitakse kujule {"anyOf": [{"type": "string"}, {"type": "null"}]}

Reegel required kohta üllatab sageli: valikulist välja ei väljendata selle loendist eemaldamisega, vaid lubades väärtust null, täpselt nii, nagu Optional[str] Pydanticu poolel teeb.

Peamised punktid

  • Struktureeritud väljund garanteerib, et vastus järgib sinu JSON skeemi
  • Kasuta Responses API-s text={"format": {"type": "json_schema", ...}}
  • Pydantic on ideaalne tööriist skeemide defineerimiseks ja valideerimiseks
  • Luba strict: True, et garanteerida skeemile vastavust
  • Ideaalne andmete ekstraheerimiseks, klassifitseerimiseks ja struktureeritud genereerimiseks