Премини към основното съдържание
Български— Изберете език
Меню

Структуриран изход: Гарантиран JSON

Урок 9 от 22 Обновен 29 юли 2026 г. Програмист
На тази страница
  1. Структуриран изход: Гарантиран JSON
  2. Проблемът, който това решава
  3. Pydantic вместо ръчно написана JSON схема
  4. Два често срещани случая на употреба
  5. Какво изисква стриктният режим
  6. Ключови изводи

Структуриран изход: Гарантиран 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 за гарантирано съответствие със схемата
  • Идеален за извличане на данни, класификация и структурирано генериране