Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Rakenteinen tuloste: taattu JSON

Oppitunti 9 / 22 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Rakenteinen tuloste: taattu JSON
  2. Ongelma, jonka tämä ratkaisee
  3. Pydantic käsin kirjoitetun JSON-skeeman sijaan
  4. Kaksi yleistä käyttötapausta
  5. Mitä tiukka tila vaatii
  6. Keskeiset asiat

Rakenteinen tuloste: taattu JSON

Rakenteinen tuloste on yksi Responses API:n tehokkaimmista ominaisuuksista. Sen sijaan, että toivoisit mallin palauttavan kelvollista JSONia, takaa sen määrittelemällä skeeman. Malli pakotetaan rakenteellisesti noudattamaan sitä. Tämä muuttaa kielimallin luovasta tekstingeneraattorista luotettavaksi osaksi automatisoitua käsittelyputkea.

Ongelma, jonka tämä ratkaisee

JSONin pyytäminen kehotteessa toimii useimmiten, mikä tekee lähestymistavasta juuri siksi vaarallisen. Yhden sadasta kerrasta malli lisää vastauksen alkuun esittelylauseen, käärii kaiken Markdown-koodilohkoon tai nimeää kentän uudelleen – ja tuotannossa ajettava json.loads() heittää poikkeuksen pyynnöllä, jota et pysty toistamaan.

from openai import OpenAI
client = OpenAI()

# Ilman rakennetta – malli voi palauttaa minkä tahansa muodon
response = client.responses.create(
    model="gpt-5.6-terra",
    input="Give me info about Paris in JSON."
)
print(response.output_text)
# Arvaamaton tulos:
# Joskus kelvollinen JSON, joskus JSONia sisältävä teksti,
# joskus odottamaton muoto...

Parametri text muuttaa takuun luonnetta. Määrittelet muodon json_schema yhdessä odotetun skeeman kanssa, jolloin tuloste noudattaa sitä: deserialisoinnista tulee turvallinen operaatio.

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

# Tulos on TAATTU kelvolliseksi JSONiksi:
# City: Paris
# Population: 2,161,000
# Landmarks: Eiffel Tower, Louvre, Notre-Dame, Arc de Triomphe, Sacré-Cœur

Pydantic käsin kirjoitetun JSON-skeeman sijaan

Skeemojen kirjoittaminen käsin muuttuu nopeasti työlääksi ja alttiiksi kirjoitusvirheille. Pydanticin avulla voit kuvata ne Python-luokkina, generoida JSON-skeeman metodilla model_json_schema() ja sen jälkeen validoida ja tyypittää vastauksen metodilla model_validate_json(). Ketjun päässä saat käyttöösi täysiverisen Python-olion editorin täydennystuella anonyymin sanakirjan sijaan.

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

# Jäsennä ja validoi Pydanticilla
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'}")

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

Mikään ei rajoita sinua litteisiin rakenteisiin. Yhdistelemällä luokkia kuvaat sisäkkäisiä olioita ja oliolistoja, joita tarvitset heti, kun luot realistisen asiakasprofiilin: yritys sisältää yhteystietoja, ja jokaisella yhteystiedolla on osoite.

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

Kaksi yleistä käyttötapausta

Ensimmäinen on tiedon ekstraktio: kirjoitetun tekstin muuttaminen käytettäväksi tietueeksi. Luonnollisella kielellä kirjoitetusta konferenssi-ilmoituksesta tulee tietokantarivi, jossa on otsikko, päivämäärä, sijainti ja osallistujamäärä – ilman säännöllisiä lausekkeita ja hajoamatta, vaikka sanamuoto muuttuisi.

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

Toinen on luokittelu. Määrittelemällä enumeraation rajoitat mallin suljettuun sanastoon: se ei voi vastata “melko myönteinen” tai “positiivinen”, kun koodisi odottaa arvoa positive. Tämä on ero arvon välillä, jota voit käyttää suoraan, ja arvon, joka on normalisoitava jälkikäteen.

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

Mitä tiukka tila vaatii

Takuu tulee kompromissina: kun strict: True, skeeman on noudatettava tiettyä JSON-skeeman osajoukkoa. Nämä rajoitukset ovat aloittelijoiden yleisin syy 400-virheille, joten ne kannattaa tuntea etukäteen:

  • Kaikkien ominaisuuksien on oltava listattuna kohdassa required
  • additionalProperties on oltava False
  • Tuetut tyypit: string, number, integer, boolean, array, object, null
  • Ei oneOf tai anyOf sekatyyppien kanssa
  • Käytä Optional[str], joka kääntyy muotoon {"anyOf": [{"type": "string"}, {"type": "null"}]}

Sääntö required:stä yllättää usein: valinnaista kenttää ei ilmaista poistamalla sitä listasta, vaan sallimalla arvo null, täsmälleen niin kuin Optional[str] tuottaa Pydanticin puolella.

Keskeiset asiat

  • Rakenteinen tuloste takaa, että vastaus noudattaa JSON-skeemaasi
  • Käytä Responses API:ssa muotoa text={"format": {"type": "json_schema", ...}}
  • Pydantic on ihanteellinen työkalu skeemojen määrittelyyn ja validointiin
  • Ota käyttöön strict: True taatun skeeman noudattamisen varmistamiseksi
  • Ihanteellinen tiedon ekstraktioon, luokitteluun ja rakenteiseen generointiin