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

Режим JSON и налагане на схема

Урок 10 от 16 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. Режим JSON и налагане на схема
  2. Режим JSON срещу Структуриран изход
  3. Структуриран изход с JSON схема
  4. Правила за строг структуриран изход
  5. Помощник за изграждане на схеми
  6. Пример: Извличане на структурирани данни
  7. Измерване на ползата от ограничението
  8. Ключови изводи

Урокът е актуализиран на 3 ноември 2026 г. въз основа на документацията на OpenAI: параметрите temperature и top_p се приемат само при усилие за разсъждение (reasoning effort) със стойност none, докато моделите от серията GPT-5.6 разсъждават по подразбиране (medium). Следователно заявките, които задават тези параметри, трябва изрично да посочват reasoning={"effort": "none"} (Responses API) или reasoning_effort="none" (Chat Completions). Източници: Използване на GPT-6 · GPT-5.6 Terra.

Режим JSON и налагане на схема

Структурираният изход (Structured Output) на OpenAI гарантира, че отговорът на модела е валиден JSON, съответстващ на дефинирана от Вас схема. Край на крехкото анализиране с регулярни изрази или грешки във формата – ограничението се прилага на ниво генериране.

Този нюанс е критичен и променя всичко за разработчика. Молбата „отговори в JSON“ в промпта е просто молба: моделът се подчинява повечето време, но един ден ще добави префикс „Ето искания JSON:“, ще включи Markdown обратни кавички или ще пропусне запетая, и Вашият json.loads ще хвърли изключение в продукцията в 3 сутринта по време на най-голямата седмична партида. При Структурирания изход ограничението важи по време на декодирането: токени, които биха породили невалиден или несъответстващ JSON, просто не могат да бъдат избрани. Спрете да молите и започнете да налагате.

Режим JSON срещу Структуриран изход

OpenAI предлага два нива на ограничение и разликата зависи от една дума. Режимът JSON гарантира валиден JSON без структурни ограничения; Структурираният изход гарантира JSON, съответстващ на JSON схема, която сте написали.

Режимът JSON решава половината от проблема. Сигурни сте, че можете да анализирате отговора, но не и какво съдържа: моделът може да наименува поле annee при една заявка и year при следващата, или да обвие списъка си в обект resultats, който не е използвал предния ден. За прототип или суров дисплей, предназначен за човек, това е достатъчно; щом изходът захранва код, който достъпва полета по име, Ви е необходимо второто ниво.

from openai import OpenAI

client = OpenAI()

# Обикновен режим JSON (валиден JSON, свободна структура)
response = client.responses.create(
    model="gpt-5.6-terra",
    instructions="Always respond in JSON.",
    input="List 3 programming languages with their year of creation.",
    text={"format": {"type": "json_object"}}
)

import json
data = json.loads(response.output_text)
print(data)

Структуриран изход с JSON схема

Това е най-мощната функция. Вие дефинирате JSON схема и API гарантира, че изходът ѝ съответства. Примерът по-долу анализира настроението на клиентски отзив и илюстрира три допълващи се употреби на схемата.

enum върху sentiment предотвратява измислянето от модела на междинна категория като „по-скоро положително“: той трябва да избере между четирите предоставени стойности, правейки изхода директно използваем във филтър или табло. description на полето score действа като локален мини-промпт, указвайки очакваната скала, без да се налага да я обяснявате в общите инструкции, и остава прикрепено към полето, дори ако промптът еволюира. Накрая, масивът aspects Ви позволява да декомпозирате противоречив отзив – тук продуктът е харесан, но доставката е провалена – вместо да смазвате този нюанс в една единствена оценка, която не помага на никого.

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Analyze the sentiment of: 'The product is excellent "
          "but the delivery was catastrophic.'",
    text={
        "format": {
            "type": "json_schema",
            "name": "sentiment_analysis",
            "schema": {
                "type": "object",
                "properties": {
                    "sentiment": {
                        "type": "string",
                        "enum": ["positive", "negative", "mixed", "neutral"]
                    },
                    "score": {
                        "type": "number",
                        "description": "Score from -1.0 (very negative) to 1.0 (very positive)"
                    },
                    "aspects": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "aspect": {"type": "string"},
                                "sentiment": {
                                    "type": "string",
                                    "enum": ["positive", "negative", "neutral"]
                                }
                            },
                            "required": ["aspect", "sentiment"],
                            "additionalProperties": False
                        }
                    },
                    "summary": {"type": "string"}
                },
                "required": ["sentiment", "score", "aspects", "summary"],
                "additionalProperties": False
            },
            "strict": True
        }
    }
)

result = json.loads(response.output_text)
# Гарантирано: result има точно дефинираните полета
print(f"Sentiment: {result['sentiment']}")
print(f"Score: {result['score']}")
for aspect in result["aspects"]:
    print(f"  - {aspect['aspect']}: {aspect['sentiment']}")

Правила за строг структуриран изход

Режимът strict: true налага свои собствени ограничения върху схемата. Всички полета трябва да фигурират в required, а additionalProperties трябва да бъде false за всеки обект. Позволените типове са string, number, integer, boolean, array, object и null, плюс enum за ограничаване на стойностите. Въпреки това, нито pattern, нито minLength/maxLength се приемат: детайлната валидация се извършва на страната на клиента.

Тези правила могат да изненадат при първия опит, защото забраняват незадължителното поле, както обикновено се пише в JSON Schema. Компромисът е удобен: Вашият код никога не трябва да тества дали даден ключ съществува; той винаги е там. За поле, което законно може да бъде празно – липсващ телефонен номер в документ, крайна дата за текущ договор – отговорът не е да го премахнете от required, а да позволите да бъде null. Що се отнася до липсата на pattern и граници за дължина, това сигнализира за следващия урок: схемата гарантира формата, но бизнес валидацията остава Ваша работа, след като отговорът бъде получен.

Помощник за изграждане на схеми

Ръчното писане на блока text.format за всяко обаждане бързо става досадно и податливо на печатни грешки – липсващ ключ name, misplaced strict и грешката се връща от API, без да посочва къде да търсите. Няколко реда обвиващ код централизират структурата, прилагат ниска температура по подразбиране (тъй като вариативността не добавя нищо към извличането) и правят мястото на извикване четимо.

def structured_query(prompt: str, schema: dict,
                     schema_name: str = "response",
                     model: str = "gpt-5.6-terra",
                     system: str = "") -> dict:
    """Wrapper for Structured Output requests."""
    response = client.responses.create(
        model=model,
        reasoning={"effort": "none"},  # temperature requires effort none
        instructions=system or "Respond in JSON according to the provided schema.",
        input=prompt,
        text={
            "format": {
                "type": "json_schema",
                "name": schema_name,
                "schema": schema,
                "strict": True
            }
        },
        temperature=0.1
    )
    return json.loads(response.output_text)

Пример: Извличане на структурирани данни

Ето случая на употреба, който сам по себе си оправдава изучаването на тази техника: трансформиране на фактура, получена като обикновен текст, в обект, използваем от Вашата счетоводна система. Схемата описва три нива – заглавката на фактурата, вложен обект vendor и масив lines, където всеки елемент има една и съща форма. Следователно моделът трябва едновременно да локализира информация, разпръсната из целия документ, и да я постави на правилното място, включително за ред, изразен в часове, а не в единици, където единичната цена се разбира като почасова ставка.

Обърнете внимание, че общите суми се появяват в схемата като полета за извличане, а не за преизчисляване. Молим модела да чете; контролът на аритметиката се случва впоследствие във Вашия код, където просто сравнение между сумата на редовете и извлеченото total_ht ще маркира документите за човешки преглед.

invoice_schema = {
    "type": "object",
    "properties": {
        "invoice_number": {"type": "string"},
        "date": {"type": "string"},
        "vendor": {
            "type": "object",
            "properties": {
                "name": {"type": "string"},
                "siret": {"type": "string"},
                "address": {"type": "string"}
            },
            "required": ["name", "siret", "address"],
            "additionalProperties": False
        },
        "lines": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "description": {"type": "string"},
                    "quantity": {"type": "integer"},
                    "unit_price_excl_tax": {"type": "number"},
                    "vat_percent": {"type": "number"}
                },
                "required": ["description", "quantity",
                             "unit_price_excl_tax", "vat_percent"],
                "additionalProperties": False
            }
        },
        "total_excl_tax": {"type": "number"},
        "total_incl_tax": {"type": "number"}
    },
    "required": ["invoice_number", "date", "vendor",
                  "lines", "total_excl_tax", "total_incl_tax"],
    "additionalProperties": False
}

invoice_text = """
Invoice No. 2026-0042
Date: 15/03/2026
Vendor: TechServ SARL, SIRET 123 456 789 00012
12 rue de la Paix, 75002 Paris

- REST API Development x1: 3500.00 EUR excl. tax (VAT 20%)
- Cloud hosting (3 months) x1: 450.00 EUR excl. tax (VAT 20%)
- Technical support x10h: 150.00 EUR excl. tax/h (VAT 20%)

Total excl. tax: 5450.00 EUR
Total incl. tax: 6540.00 EUR
"""

result = structured_query(
    invoice_text,
    invoice_schema,
    schema_name="invoice",
    system="Extract the data from this invoice."
)

Измерване на ползата от ограничението

Приложете този принцип към документ, който познавате добре: дефинирайте JSON схема за извличане на ключова информация от автобиография – име, опит, умения, образование – и я тествайте върху три автобиографии в обикновен текст, избрани умишлено заради техните хетерогенни оформления. Уверете се, че изходът спазва схемата, дори когато даден раздел липсва напълно.

След това повторете същото извличане без Структуриран изход, просто искайки JSON в промпта, и запазете шестте изхода един до друг. Сравнението на двете серии показва какво носи ограничението: разликата рядко е в извлеченото съдържание, почти винаги е в стабилността на имената на полетата и наличието на очакваните ключове.

Ключови изводи

  • Структурираният изход гарантира JSON, съответстващ на схемата на ниво генериране
  • Използвайте strict: true за максимално съответствие
  • Всички полета трябва да бъдат required с additionalProperties: false
  • Идеален за извличане на данни, класификация и обработващи конвейери
  • Детайлната валидация (дължина, шаблон) се извършва на страната на клиента след получаване