Przejdź do głównej treści
Polski— Wybierz język
Menu

Tryb JSON i wymuszanie schematu

Lekcja 10 z 16 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Tryb JSON i wymuszanie schematu
  2. Tryb JSON a Strukturyzowane Wyjście
  3. Strukturyzowane Wyjście ze schematem JSON
  4. Zasady ścisłego Strukturyzowanego Wyjścia
  5. Pomocnik do budowania schematów
  6. Przykład: Strukturyzowana ekstrakcja danych
  7. Mierzenie korzyści z ograniczeń
  8. Kluczowe wnioski

Lekcja zaktualizowana 3 listopada 2026 na podstawie dokumentacji OpenAI: parametry temperature i top_p są akceptowane wyłącznie przy wysiłku rozumowania (reasoning effort) ustawionym na none, podczas gdy modele GPT-5.6 domyślnie rozumują z wysiłkiem medium. Wywołania ustawiające te parametry muszą zatem określać reasoning={"effort": "none"} (Responses API) lub reasoning_effort="none" (Chat Completions). Źródła: Using GPT-6 · GPT-5.6 Terra.

Tryb JSON i wymuszanie schematu

Strukturyzowane wyjście (Structured Output) od OpenAI gwarantuje, że odpowiedź modelu będzie poprawnym kodem JSON zgodnym ze zdefiniowanym przez Ciebie schematem. Koniec z krującym parsowaniem przy użyciu wyrażeń regularnych czy błędami formatowania – ograniczenie jest stosowane już na poziomie generowania tokenów.

Ten niuans jest kluczowy i zmienia wszystko dla programisty. Prośba „odpowiedz w JSON“ w prompcie to błaganie: model słucha większość czasu, ale pewnego dnia doda prefiks „Oto żądany JSON:“, otoczy odpowiedź znacznikami Markdown albo zapomni o przecinku, a Twój json.loads wyrzuci wyjątek w produkcji o 3 nad ranem podczas największego wsadu tygodnia. Przy Strukturyzowanym Wyjściu ograniczenie działa podczas dekodowania: tokeny, które wygenerowałyby niepoprawny lub niezgodny JSON, po prostu nie mogą zostać wybrane. Przestajesz błagać, a zaczynasz wymuszać.

Tryb JSON a Strukturyzowane Wyjście

OpenAI oferuje dwa poziomy ograniczeń, a różnica polega na jednym słowie. Tryb JSON gwarantuje poprawny składniowo JSON bez ograniczeń strukturalnych; Strukturyzowane Wyjście gwarantuje JSON zgodny ze schematem JSON Schema, który napisałeś.

Tryb JSON rozwiązuje tylko połowę problemu. Masz pewność, że sparsujesz odpowiedź, ale nie wiesz, co ona zawiera: model może nazwać pole annee w jednym żądaniu, a year w kolejnym, albo opakować listę w obiekt resultats, którego nie używał dzień wcześniej. Dla prototypu lub surowego wyświetlania przeznaczonego dla człowieka to wystarczy; gdy tylko wyjście zasila kod odwołujący się do pól po nazwie, potrzebujesz drugiego poziomu.

from openai import OpenAI

client = OpenAI()

# Prosty tryb JSON (poprawny JSON, dowolna struktura)
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)

Strukturyzowane Wyjście ze schematem JSON

To najbardziej potężna funkcja. Definiujesz schemat JSON, a API gwarantuje, że wyjście będzie mu odpowiadać. Poniższy przykład analizuje sentyment recenzji klienta i ilustruje trzy komplementarne zastosowania schematu.

Wyliczenie (enum) dla pola sentiment zapobiega wymyślaniu przez model kategorii pośrednich typu „raczej pozytywny“: musi wybrać jedną z czterech podanych wartości, co sprawia, że wyjście jest bezpośrednio użyteczne w filtrze lub dashboardzie. Opis (description) pola score działa jak lokalny mini-prompt, wskazując oczekiwaną skalę bez konieczności tłumaczenia tego w ogólnych instrukcjach, i pozostaje przypisany do pola nawet jeśli prompt ewoluuje. Wreszcie, tablica aspects pozwala rozbić sprzeczną recenzję – tutaj produkt liked, ale dostawa failed – zamiast spłaszczać ten niuans do pojedynczej oceny, która nikomu nie pomaga.

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)
# Gwarancja: result ma dokładnie zdefiniowane pola
print(f"Sentiment: {result['sentiment']}")
print(f"Score: {result['score']}")
for aspect in result["aspects"]:
    print(f"  - {aspect['aspect']}: {aspect['sentiment']}")

Zasady ścisłego Strukturyzowanego Wyjścia

Tryb strict: true nakłada własne ograniczenia na schemat. Wszystkie pola muszą występować w required, a additionalProperties musi być ustawione na false dla każdego obiektu. Dozwolone typy to string, number, integer, boolean, array, object oraz null, plus enum do ograniczania wartości. Jednak ani pattern, ani minLength/maxLength nie są akceptowane: walidacja szczegółowa odbywa się po stronie klienta.

Te reguły mogą być zaskakujące przy pierwszej próbie, ponieważ zabraniają opcjonalnych pól w formie, w jakiej zwykle zapisuje się je w JSON Schema. Kompromis jest jednak komfortowy: Twój kod nigdy nie musi testować, czy klucz istnieje; zawsze tam jest. Dla pola, które legalnie może być puste – np. brakujący numer telefonu w dokumencie czy data końcowa dla trwającej umowy – rozwiązaniem nie jest usuwanie go z required, lecz允许enie mu przyjmowania wartości null. Brak pattern i ograniczeń długości sygnalizuje natomiast temat następnej lekcji: schemat gwarantuje formę, ale walidacja biznesowa pozostaje Twoim zadaniem po otrzymaniu odpowiedzi.

Pomocnik do budowania schematów

Ręczne pisanie bloku text.format dla każdego wywołania szybko staje się żmudne i podatne na literówki – brakujący klucz name, źle umieszczone strict i błąd wraca z API bez wskazania, gdzie szukać problemu. Kilka linii kodu pomocniczego centralizuje strukturę, domyślnie stosuje niską temperaturę (gdyż zmienność nic nie wnosi do ekstrakcji) i czyni miejsce wywołania czytelnym.

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)

Przykład: Strukturyzowana ekstrakcja danych

Oto przypadek użycia, który sam w sobie uzasadnia naukę tej techniki: transformacja faktury otrzymanej jako zwykły tekst w obiekt użyteczny dla systemu księgowego. Schemat opisuje trzy poziomy – nagłówek faktury, zagnieżdżony obiekt vendor oraz tablicę lines, gdzie każdy element ma ten sam kształt. Model musi więc zarówno zlokalizować informacje rozproszone po dokumencie, jak i umieścić je we właściwym miejscu, również w przypadku linii wyrażonej w godzinach zamiast sztuk, gdzie cena jednostkowa jest rozumiana jako stawka godzinowa.

Zauważ, że sumy pojawiają się w schemacie jako pola do ekstrakcji, a nie do przeliczania. Prosimy model o odczyt; kontrola arytmetyki dzieje się później w Twoim kodzie, gdzie proste porównanie sumy linii z wyekstrahowanym total_ht oflaguje dokumenty do przeglądu przez człowieka.

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

Mierzenie korzyści z ograniczeń

Zastosuj tę zasadę do dokumentu, który dobrze znasz: zdefiniuj schemat JSON do ekstrakcji kluczowych informacji z CV – imię i nazwisko, doświadczenie, umiejętności, edukacja – i przetestuj go na trzech CV w postaci zwykłego tekstu, celowo dobranych ze względu na ich heterogeniczne układy. Sprawdź, czy wyjście respektuje schemat nawet wtedy, gdy dana sekcja całkowicie отсутствует.

Następnie powtórz tę samą ekstrakcję bez Strukturyzowanego Wyjścia, prosząc po prostu o JSON w prompcie, i zestaw obok siebie sześć wyników. Porównanie obu serii pokazuje, co wnosi ograniczenie: różnica rzadko leży w wyekstrahowanej treści, prawie zawsze w stabilności nazw pól i obecności oczekiwanych kluczy.

Kluczowe wnioski

  • Strukturyzowane Wyjście gwarantuje JSON zgodny ze schematem już na poziomie generowania
  • Używaj strict: true dla maksymalnej zgodności
  • Wszystkie pola muszą być required, a additionalProperties ustawione na false
  • Idealne do ekstrakcji danych, klasyfikacji i potoków przetwarzania
  • Walidacja szczegółowa (długość, wzorzec) odbywa się po stronie klienta po otrzymaniu odpowiedzi