Standard

Structured Outputs: standard kontraktu odpowiedzi (JSON Schema)

Jak zbudować odpowiedzi, które są weryfikowalne maszynowo, wersjonowane i odporne na „ładny tekst, który nie przechodzi walidacji”.

Contract-first: kiedy JSON jest wymaganiem, a nie opcją

Structured Outputs to praktyka, w której wynik modelu jest traktowany jak interfejs. To oznacza: schema, walidację, wersjonowanie i obsługę błędów tak samo, jak w klasycznych systemach API.

Projektowanie schematu (praktyka)

  • Minimalizm: tylko pola, które są naprawdę potrzebne do wykonania kolejnego kroku.
  • Enumy zamiast dowolnych stringów (np. statusy, typy decyzji).
  • Jawne błędy: osobny obiekt error z kodem i opisem.
  • Wersja kontraktu w odpowiedzi (contract_version).

Walidacja i pętla naprawcza

Walidacja schematu nie jest „opcją”. Jeżeli wynik nie przechodzi walidacji, system powinien:

  1. zarejestrować błąd (trace + payload + reason),
  2. wykonać repair (krótką pętlę korekcyjną),
  3. a gdy to się nie uda – przejść do fallback lub HITL.
contract_response:
  contract_version: "support.reply@3"
  status: "OK"        # OK | NEEDS_REVIEW | DENY
  answer_md: "..."
  citations: [{doc:"policy@2.1", span:"p3-p4"}]
  error: null
Uwaga: schema stabilizuje system tylko wtedy, gdy jest spięta z testami regresji. W przeciwnym razie zmiany w promptach będą „przepychały” nowe formaty bez kontroli.

Najczęstsze antywzorce

  • „Luźny JSON” bez walidacji – pozorny porządek, realny chaos.
  • Zbyt bogate schematy (dziesiątki pól) – rosną koszty i awaryjność.
  • Brak wersjonowania – brak możliwości migracji i audytu.
W tym rozdziale
  • po co structured outputs
  • standard kontraktu odpowiedzi
  • pętla walidacji i naprawy
  • przykładowy schemat
  • telemetria i regresje

Dlaczego structured outputs

Jeśli odpowiedź ma być dalej przetwarzana (workflow, UI, automatyzacje), to „ładny tekst” nie jest kontraktem. W praktyce produkcyjnej potrzebujemy odpowiedzi o z góry określonej strukturze, która przechodzi walidację.

Zasada: model nie jest parserem. Model generuje, a system weryfikuje. Kontrakt powinien być tak samo wersjonowany jak API.

Standard Luage: kontrakt odpowiedzi

  • Jednoznaczny format (np. JSON) i brak „opisu dookoła”.
  • Wersja schematu w payload (np. schema_version).
  • Walidacja runtime: parse → validate → (opcjonalnie) repair → validate.
  • Tryb awaryjny: jeśli walidacja nie przechodzi, system zwraca bezpieczny błąd i trace.
Rysunek 1. Pętla walidacji odpowiedzi
Model generuje JSON Walidator parse + schema Naprawa opcjonalnie Publish

Przykładowy schemat (minimalny)

{
  "type": "object",
  "required": ["schema_version", "answer", "citations"],
  "properties": {
    "schema_version": { "type": "string", "enum": ["1.0"] },
    "answer": { "type": "string", "minLength": 1 },
    "citations": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["doc_id", "version", "excerpt"],
        "properties": {
          "doc_id": { "type": "string" },
          "version": { "type": "string" },
          "excerpt": { "type": "string" }
        }
      }
    }
  }
}

Kontrola jakości i audyt

  • Metryka: odsetek odpowiedzi niezgodnych ze schematem (na etap, na model, na scenariusz).
  • Telemetria: trace_id, schema_version, validator_errors, repair_attempts.
  • Regresje: golden set z „trudnymi” przypadkami (np. znaki specjalne, polskie cudzysłowy, długie listy).

Checklist (skrót)

  • Schemat wersjonowany i testowany.
  • Walidator w runtime + obsługa błędów + re-try/repair.
  • Wyraźny kontrakt: „tylko JSON”, brak komentarzy.
  • Audyt: loguj wynik walidacji i napraw.
Powiązane
Na tej stronie
Spis
    Nawigacja
    ← Poprzedni Następny →
    Status merytoryczny
    Ten rozdział jest częścią Compendium. Metryka (wersja, owner, terminy przeglądu) jest wypełniana automatycznie na podstawie manifestu.