Ograniczenia trybu JSON i obsługa błędów
Na tej stronie
Ważne nie oznacza poprawne
Tryb JSON gwarantuje składniowo poprawny kod JSON, ale nie semantycznie poprawny. Ta różnica może wydawać się subtelna podczas rozwoju, ale staje się krytyczna w środowisku produkcyjnym. Kod JSON, który parsuje się bez błędów, ale zawiera nieoczekiwane klucze, tworzy dokładnie taki rodzaj błędu, którego namierzenie zajmuje dni, ponieważ żaden wyjątek nie zostanie zgłoszony w momencie wystąpienia problemu.
Brak gwarancji schematu
Mechanizm ten nie wie nic o Twoim schemacie: nigdy nie widział struktury, której oczekuje Twój kod. Model może pominąć pole, którego potrzebujesz, dodać takie, o które nie prosiłeś, zmienić nazwę klucza – np. firstName zamiast first_name – lub zmienić typ, zwracając "42" jako ciąg znaków, gdy oczekiwałeś liczby 42. Żadne z tych zachowań nie czyni kodu JSON niepoprawnym.
# Oczekujesz tego:
# {"name": "Alice", "age": 30, "city": "Paris"}
# Ale możesz otrzymać:
# {"nom": "Alice", "âge": "trente ans", "ville": "Paris", "pays": "France"}
Kod JSON jest poprawny, ale struktura nie zgadza się z tym, czego oczekuje Twój kod. To jest fundamentalna różnica w porównaniu z Niestandardowymi Wyjściami Strukturalnymi (Custom Structured Outputs).
Obowiązkowa walidacja po stronie klienta
Ponieważ schemat nie jest gwarantowany, odpowiedzialność za walidację spoczywa na Tobie. Minimalny wzorzec wykonuje trzy czynności po kolei: próbuje przeprowadzić parsowanie, weryfikuje, czy elementem głównym jest obiekt (a nie lista lub skalar), a następnie sprawdza obecność wymaganych kluczy. Każde niepowodzenie zgłasza wyjątek ValueError z komunikatem, którego możesz użyć w swoich logach.
import json
from typing import Optional
def parse_and_validate(raw_content: str, required_keys: list[str]) -> dict:
"""Parsuj JSON i zweryfikuj wymagane klucze."""
try:
data = json.loads(raw_content)
except json.JSONDecodeError as e:
raise ValueError(f"Niepoprawny JSON: {e}")
if not isinstance(data, dict):
raise ValueError(f"Oczekiwano obiektu JSON, otrzymano {type(data).__name__}")
missing = [k for k in required_keys if k not in data]
if missing:
raise ValueError(f"Brakujące klucze: {missing}")
return data
# Użycie
try:
result = parse_and_validate(
response.choices[0].message.content,
required_keys=["name", "category", "priority"]
)
process_ticket(result)
except ValueError as e:
log_error(f"Niepoprawne wyjście: {e}")
fallback_processing(raw_content)
Wersja w TypeScript idzie o krok dalej, weryfikując nie tylko obecność kluczy, ale także sprawdzając, czy zwrócona kategoria należy do dozwolonej listy. Jest to sprawdzenie, którego najczęściej brakuje, a które zapobiega cichemu przemyceniu zgłoszenia sklasyfikowanego jako "urgent_billing" przez system routingu.
interface TicketClassification {
category: string;
priority: string;
sentiment: string;
summary: string;
}
function validateTicket(raw: string): TicketClassification {
const data = JSON.parse(raw);
const requiredKeys = ["category", "priority", "sentiment", "summary"];
const missing = requiredKeys.filter((k) => !(k in data));
if (missing.length > 0) {
throw new Error(`Brakujące klucze: ${missing.join(", ")}`);
}
const validCategories = ["billing", "account", "technical", "feature_request", "other"];
if (!validCategories.includes(data.category)) {
throw new Error(`Niepoprawna kategoria: ${data.category}`);
}
return data as TicketClassification;
}
Trzy rodzaje awarii, z którymi się spotkasz
Pierwszym jest ucięty kod JSON. Jeśli odpowiedź osiągnie limit max_tokens, zostanie przerwana w trakcie przesyłania i stanie się niepoprawna – zamykający nawias klamrowy nigdy nie zostanie dostarczony. Objaw ten możesz zauważyć jeszcze przed parsowaniem: finish_reason wynosi "length" zamiast "stop".
response = client.chat.complete(
model="mistral-small-latest",
messages=messages,
response_format={"type": "json_object"},
max_tokens=50 # Zbyt mało dla kompletnego JSON
)
# response.choices[0].finish_reason będzie wynosić "length" zamiast "stop"
if response.choices[0].finish_reason == "length":
print("Ostrzeżenie: Ucięta odpowiedź, zwiększ max_tokens")
Zawsze sprawdzaj finish_reason: jeśli wynosi "length", odpowiedź jest niekompletna, niezależnie od tego, co mówi reszta treści.
Druga awaria dotyczy typów. Wiek może przyjść jako ciąg znaków, cena jako liczba całkowita, gdy oczekujesz liczby zmiennoprzecinkowej. Zamiast ufać wyjściu, opakuj dostęp do danych w funkcję pomocniczą, która próbuje dokonać konwersji i w razie niepowodzenia wraca do wartości domyślnej.
def safe_get_int(data: dict, key: str, default: int = 0) -> int:
"""Wyodrębnij liczbę całkowitą, dokonując konwersji w razie potrzeby."""
value = data.get(key)
if value is None:
return default
if isinstance(value, int):
return value
if isinstance(value, float):
return int(value)
if isinstance(value, str):
try:
return int(value)
except ValueError:
return default
return default
# Użycie
age = safe_get_int(data, "age", default=0)
Trzecim problemem jest zmiana nazw kluczy. Przy monicie w języku francuskim model może łatwo zamienić phone na telephone lub name na nom. Mapowanie synonimów pochłania te warianty bez konieczności ponawiania wywołania.
def normalize_keys(data: dict, key_mapping: dict) -> dict:
"""Normalizuj klucze przy użyciu mapowania synonimów."""
normalized = {}
for standard_key, aliases in key_mapping.items():
for alias in aliases:
if alias in data:
normalized[standard_key] = data[alias]
break
return normalized
# Mapowanie synonimów
mapping = {
"name": ["name", "nom", "full_name", "fullName"],
"email": ["email", "mail", "e-mail", "emailAddress"],
"phone": ["phone", "telephone", "tel", "phoneNumber"],
}
normalized = normalize_keys(raw_data, mapping)
Ponawianie z informacją zwrotną
Gdy walidacja zawiedzie mimo najlepszych starań, najlepszą reakcją nie jest ponowienie dokładnie tego samego wywołania, lecz poinformowanie modelu o tym, co poszło nie tak. Przekazując jego własną odpowiedź z powrotem do konwersacji wraz z komunikatem o błędzie, dostarczasz kontekst niezbędny do samokorekty, co zazwyczaj następuje już przy drugiej próbie.
import json
def call_with_retry(client, messages, max_retries=3):
"""Wywołaj z ponawianiem i informacją zwrotną o błędzie."""
for attempt in range(max_retries):
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
response_format={"type": "json_object"},
temperature=0
)
raw = response.choices[0].message.content
try:
data = json.loads(raw)
validate_schema(data) # Twoja funkcja walidująca
return data
except (json.JSONDecodeError, ValueError) as e:
if attempt < max_retries - 1:
# Dodaj informację zwrotną o błędzie do kontekstu
messages.append({"role": "assistant", "content": raw})
messages.append({
"role": "user",
"content": f"Twoja odpowiedź jest niepoprawna: {e}. Popraw ją i zwróć poprawny JSON."
})
else:
raise RuntimeError(f"Niepowodzenie po {max_retries} próbach: {e}")
Sygnał do zmiany podejścia
Jeśli łapiesz się na pisaniu rozległego kodu walidacyjnego, jest to silny sygnał, że czas migrate do Niestandardowych Wyjść Strukturalnych (Custom Structured Outputs). Potwierdzają to trzy typowe progi: gdy liczba pól do walidacji przekracza pięć, funkcja kontrolna staje się dłuższa niż samo wywołanie; gdy typy stają się złożone, zawierając zagnieżdżone listy lub wyliczenia, ręczna walidacja staje się nierozerwalnie związana z błędami, które wprowadza; a w przypadku dowolnego krytycznego potoku produkcyjnego, delegowanie ograniczeń do schematu jest po prostu bezpieczniejsze niż ich ręczna rekonstrukcja.
Kluczowe wnioski
- Tryb JSON gwarantuje poprawny kod JSON, ale nie poprawny schemat
- Zawsze waliduj wyjście po stronie klienta: sprawdzaj wymagane klucze, poprawne typy i wartości mieszczące się w określonych granicach
- Sprawdzaj
finish_reason, aby wykryć ucięte odpowiedzi - Wdróż mechanizm ponawiania z informacją zwrotną o błędzie
- Jeśli walidacja staje się złożona, przejdź na Niestandardowe Wyjścia Strukturalne