Структуриран изход: Гарантиран JSON
На тази страница
Структуриран изход: Гарантиран JSON
Структурираният изход е една от най-мощните функции на Responses API. Вместо да се надявате, че моделът ще върне валиден JSON, Вие го гарантирате, като предоставите схема. Тогава моделът е структурно ограничен да я следва. Това трансформира езиковия модел от креативен генератор на текст в надежден компонент на автоматизиран процес за обработка на данни.
Проблемът, който това решава
Искането на JSON в подкана (prompt) работи в повечето случаи, което точно прави подхода опасен. Един път на сто,modelът може да добави уводно изречение преди отговора, да обвие всичко в Markdown блок с код или да преименува поле – и Вашият json.loads() ще хвърли изключение в продукционна среда при заявка, която не можете да възпроизведете.
from openai import OpenAI
client = OpenAI()
# Без структура — моделът може да върне всеки формат
response = client.responses.create(
model="gpt-5.6-terra",
input="Give me info about Paris in JSON."
)
print(response.output_text)
# Непредсказуем резултат:
# Понякога валиден JSON, понякога текст, съдържащ JSON,
# понякога неочакван формат...
Параметърът text променя естеството на гаранцията. Вие декларирате формат json_schema заедно с очакваната схема и изходът се съобразява с нея: десериализацията става безопасна операция.
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'])}")
# Резултат, ГАРАНТИРАНО валиден JSON:
# City: Paris
# Population: 2,161,000
# Landmarks: Eiffel Tower, Louvre, Notre-Dame, Arc de Triomphe, Sacré-Cœur
Pydantic вместо ръчно написана JSON схема
Ръчното писане на схеми бързо става досадно и податливо на правописни грешки. Pydantic Ви позволява да ги описвате като Python класове, да генерирате JSON схемата с model_json_schema() и след това да валидирате и типизирате отговора с model_validate_json(). В края на веригата получавате пълен Python обект с автоматично довършване в редактора, вместо анонимен речник.
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()
}
}
)
# Парсиране и валидиране с 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'}")
# Резултат:
# Product: ASUS ROG Strix G18
# Price: 2499.99 EUR
# In stock: Yes
Нищо не Ви ограничава до плоски структури. Чрез композиране на класове описвате вложени обекти и списъци от обекти, което ще Ви е необходимо веднага щом създадете реалистичен профил на клиент: една компания съдържа контакти, а всеки контакт има адрес.
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}")
Два често срещани случая на употреба
Първият е извличане: превръщане на написан текст в използваем запис. Обява за конференция, написана на естествен език, се превръща в ред в база данни със заглавие, дата, местоположение и брой участници – без регулярни изрази и без прекъсване, когато формулировката се промени.
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)")
# Резултат: PyCon France 2026 - November 15-16, 2026 at Lyon (800 attendees)
Вторият случай е класификация. Чрез деклариране на изброим тип (enumeration), Вие ограничавате модела до затворен речник: той не може да отговори „по-скоро положително“ или „позитивно“, когато Вашият код очаква positive. Това е разликата между стойност, която можете да използвате директно, и стойност, която трябва да нормализирате впоследствие.
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%})")
# Резултат: Sentiment: positive (95%)
Какво изисква стриктният режим
Гаранцията идва с компромис: когато strict: True, схемата трябва да се придържа към специфично подмножество от JSON Schema. Тези ограничения са водещата причина за грешки 400 при начинаещите, затова е най-добре да ги знаете, преди да се сблъскате с тях:
- Всички свойства трябва да бъдат изброени в
required additionalPropertiesтрябва да бъдеFalse- Поддържани типове:
string,number,integer,boolean,array,object,null - Без
oneOfилиanyOfсъс смесени типове - Използвайте
Optional[str], което се превежда в{"anyOf": [{"type": "string"}, {"type": "null"}]}
Правилото относно required често изненадва хората: незадължително поле не се изразява чрез премахването му от списъка, а чрез разрешаване на стойността null, точно както прави Optional[str] от страна на Pydantic.
Ключови изводи
- Структурираният изход гарантира, че отговорът се придържа към Вашата JSON схема
- Използвайте
text={"format": {"type": "json_schema", ...}}в Responses API - Pydantic е идеалният инструмент за дефиниране и валидиране на схеми
- Активирайте
strict: Trueза гарантирано съответствие със схемата - Идеален за извличане на данни, класификация и структурирано генериране