Pāriet uz galveno saturu
Latviešu— Izvēlēties valodu
Izvēlne

Izvades strukturēšana: garantēts JSON

Nodarbība 9 no 22 Atjaunota 2026. gada 29. jūlijs Programmētājs
Šajā lapā
  1. Izvades strukturēšana: garantēts JSON
  2. Problēma, ko tas atrisina
  3. Pydantic manuāli rakstītas JSON shēmas vietā
  4. Divi bieži sastopami lietojumi
  5. Ko prasa stingrais režīms
  6. Galvenās atziņas

Izvades strukturēšana: garantēts JSON

Izvades strukturēšana (Structured Output) ir viena no Responses API spēcīgākajām funkcijām. Tā vietā, lai cerētu, ka modelis atgriezīs derīgu JSON, tu to garantē, norādot shēmu. Tad modelis tiek strukturāli ierobežots, lai tai sekotu. Tas pārvērš valodas modeli no radoša teksta ģeneratora par uzticamu automatizētas apstrādes cauruļvada komponenti.

Problēma, ko tas atrisina

JSON pieprasīšana uzvednē (prompt) vairumā gadījumu strādā, kas tieši padara šo pieeju bīstamu. Reizi simtos reižu modelis savu atbildi sāk ar ievadteikumu, ietver visu Markdown koda blokā vai pārdēvē kādu lauku — un tavs json.loads() ražošanas vidē izmet izņēmumu pie pieprasījuma, kuru nevari reproducēt.

from openai import OpenAI
client = OpenAI()

# Bez struktūras — modelis var atgriezt jebkuru formātu
response = client.responses.create(
    model="gpt-5.6-terra",
    input="Give me info about Paris in JSON."
)
print(response.output_text)
# Neparedzams rezultāts:
# Dažreiz derīgs JSON, dažreiz teksts, kas satur JSON,
# dažkārt negaidīts formāts...

Parametrs text maina garantijas dabu. Tu deklarē formātu json_schema kopā ar paredzēto shēmu, un izvade tai atbilst: deserializācija kļūst par drošu operāciju.

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

# Rezultāts GARANTĒTI ir derīgs JSON:
# City: Paris
# Population: 2,161,000
# Landmarks: Eiffel Tower, Louvre, Notre-Dame, Arc de Triomphe, Sacré-Cœur

Pydantic manuāli rakstītas JSON shēmas vietā

Shēmu rakstīšana ar roku ātri kļūst apnicīga un pakļauta kļūdām. Pydantic ļauj tās aprakstīt kā Python klases, ģenerēt JSON shēmu ar model_json_schema() un pēc tam validēt un tipizēt atbildi ar `model_validate_json() Ķēdes galā tu iegūsti pilnvērtīgu Python objektu ar redaktora automātisko pabeigšanu, nevis anonīmu vārdnīcu.

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

# Parsē un validē ar 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'}")

# Rezultāts:
# Product: ASUS ROG Strix G18
# Price: 2499.99 EUR
# In stock: Yes

Nekas neierobežo tevi ar plakanām struktūrām. Komponējot klases, tu apraksti ligzdotus objektus un objektu sarakstus, kas tev būs nepieciešami, tiklīdz izveidosi reālistisku klienta profilu: uzņēmums satur kontaktus, un katram kontaktam ir adrese.

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

Divi bieži sastopami lietojumi

Pirmais ir ekstrakcija: rakstīta teksta pārvēršana izmantojamā ierakstā. Dabiskā valodā rakstīts konferences paziņojums kļūst par datubāzes rindu ar nosaukumu, datumu, atrašanās vietu un dalībnieku skaitu — bez regulārām izteiksmēm un bez bojāšanās, mainoties formulējumam.

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

Otrais ir klasifikācija. Deklarējot enumerāciju, tu ierobežo modeli ar slēgtu vārdu krājumu: tas nevar atbildēt „drīzāk pozitīvi” vai „pozitīvs”, ja tavs kods sagaida positive. Šī ir atšķirība starp vērtību, ko vari izmantot tieši, un vērtību, kas pēc tam ir jānormalizē.

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

Ko prasa stingrais režīms

Garantijai ir sava cena: ja strict: True, shēmai ir jāatbilst specifiskai JSON shēmas apakškopai. Šie ierobežojumi ir galvenais 400 kļūdu cēlonis iesācējiem, tāpēc vislabāk tos zināt jau iepriekš:

  • Visiem īpašībām (properties) ir jābūt uzskaitītām required
  • additionalProperties ir jābūt False
  • Atbalstītie tipi: string, number, integer, boolean, array, object, null
  • Nav atļauts oneOf vai anyOf ar jauktiem tipiem
  • Izmanto Optional[str], kas tiek tulkots kā {"anyOf": [{"type": "string"}, {"type": "null"}]}

Noteikums par required bieži pārsteidz: opcionāls lauks netiek izteikts, to izņemot no saraksta, bet gan atļaujot vērtību null, tieši to, ko Pydantic pusē rada Optional[str].

Galvenās atziņas

  • Strukturētā izvade garantē, ka atbilde atbilst tavai JSON shēmai
  • Responses API izmanto text={"format": {"type": "json_schema", ...}}
  • Pydantic ir ideāls rīks shēmu definēšanai un validēšanai
  • Aktivizē strict: True, lai garantētu shēmas atbilstību
  • Ideāli piemērots datu ekstrakcijai, klasifikācijai un strukturētai ģenerēšanai