Rakenteinen tuloste: taattu JSON
Tällä sivulla
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 additionalPropertieson oltavaFalse- Tuetut tyypit:
string,number,integer,boolean,array,object,null - Ei
oneOftaianyOfsekatyyppien 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: Truetaatun skeeman noudattamisen varmistamiseksi - Ihanteellinen tiedon ekstraktioon, luokitteluun ja rakenteiseen generointiin