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.
Rozszerzenie praktyczne

Operacyjny skrót

Ten rozdział należy do rodziny Projektowanie interakcji i ma formę Standard. Poniższe dopowiedzenie ma jeden cel: przełożyć treść na działania, które da się wdrożyć, zmierzyć i utrzymać.

Checklista

  • Ustal cel i kryteria poprawności (co znaczy „dobry wynik”).
  • Zamknij format wyjścia (JSON / tabela / sekcje) i przygotuj walidację.
  • Ogranicz przestrzeń odpowiedzi: instrukcje, słownik terminów, limity.
  • Dodaj kontrolę jakości: self-check, sanity-checks, fallback, „no-answer”.
  • Zapisz jako szablon (prompt_template) i wersjonuj jak kod.
  • Wprowadź testy regresyjne (golden set) i przeglądy po zmianach.

Najczęstsze pułapki

  • Mieszanie instrukcji z danymi wejściowymi (brak separacji „co” vs „na czym”).
  • Format wynikowy „opisowy” bez kontraktu – brak automatycznej kontroli.
  • Zbyt ogólne polecenia („napisz mądrze”) bez parametrów i ograniczeń.
  • Brak strategii na niepewność: model zaczyna „zgadywać” zamiast eskalować.

Artefakty w Luage

prompt_template output_contract policy:language.standard trace_id golden_set

Standard działa dopiero wtedy, gdy ma właściciela, wersję, ślad (trace) oraz test regresyjny.

Szablon do skopiowania

Minimalny szablon promptu (do biblioteki)

prompt_template: support.reply@v3
intent: support.reply
inputs:
  - user_message
  - locale
constraints:
  - "Jeśli brak źródła → powiedz, że nie wiesz i poproś o doprecyzowanie"
output:
  format: markdown
  sections: ["Odpowiedź", "Co dalej"]

Traktuj szablon jak kod: owner, wersja, testy i przegląd. Wtedy to działa powtarzalnie.

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.