Ограничения на JSON режима и обработка на грешки
На тази страница
Валидно не означава правилно
JSON режимът гарантира синтактично валиден JSON, но не и семантично коректен JSON. Тази разлика може да изглежда тънка по време на разработката, но става критична в продукционна среда. JSON, който се парсва без грешки, но съдържа неочаквани ключове, създава точно онзи вид бъг, чието откриване отнема дни, тъй като при възникването на проблема не се задейства никакво изключение.
Липса на гаранции за схемата
Механизмът няма никаква представа за Вашата схема: той никога не е виждал структурата, която Вашият код очаква. Моделът може да пропусне поле, от което имате нужда, да добави такова, което не сте поискали, да преименува ключ – например firstName вместо first_name – или да промени типа, връщайки "42" като низ, когато сте очаквали числото 42. Нито едно от тези неща не представлява невалиден JSON.
# Очаквате това:
# {"name": "Alice", "age": 30, "city": "Paris"}
# Но може да получите:
# {"nom": "Alice", "âge": "trente ans", "ville": "Paris", "pays": "France"}
JSON е валиден, но структурата не съвпада с очакванията на Вашия код. Това е фундаменталната разлика спрямо Персонализираните структурирани изходи (Custom Structured Outputs).
Задължителна валидация от страна на клиента
Тъй като схемата не е гарантирана, валидацията пада върху Вас. Минималният шаблон изпълнява три неща последователно: опитва се да извърши парсване, проверява дали коренът е обект (а не списък или скалар), след което проверява за наличието на задължителни ключове. Всяка грешка поражда ValueError със съобщение, което можете да използвате във Вашите логове.
import json
from typing import Optional
def parse_and_validate(raw_content: str, required_keys: list[str]) -> dict:
"""Парсва JSON и проверява задължителните ключове."""
try:
data = json.loads(raw_content)
except json.JSONDecodeError as e:
raise ValueError(f"Невалиден JSON: {e}")
if not isinstance(data, dict):
raise ValueError(f"Очакваше се JSON обект, получено е {type(data).__name__}")
missing = [k for k in required_keys if k not in data]
if missing:
raise ValueError(f"Липсващи ключове: {missing}")
return data
# Употреба
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"Невалиден изход: {e}")
fallback_processing(raw_content)
Версията на TypeScript отива една стъпка по-нататък, като проверява, отвъд наличието на ключове, дали върнатата категория принадлежи към разрешения списък. Това е проверката, която най-често липсва, и именно тя предотвратява тихото преминаване на билет, класифициран като "urgent_billing", през Вашата система за маршрутизация.
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(`Липсващи ключове: ${missing.join(", ")}`);
}
const validCategories = ["billing", "account", "technical", "feature_request", "other"];
if (!validCategories.includes(data.category)) {
throw new Error(`Невалидна категория: ${data.category}`);
}
return data as TicketClassification;
}
Три вида грешки, с които ще се сблъскате
Първата е отрязан JSON. Ако отговорът достигне лимита на max_tokens, той се прекъсва по средата и става невалиден – затварящата скоба никога не пристига. Можете да откриете симптома още преди парсването: finish_reason е равен на "length" вместо на "stop".
response = client.chat.complete(
model="mistral-small-latest",
messages=messages,
response_format={"type": "json_object"},
max_tokens=50 # Твърде малко за пълен JSON
)
# response.choices[0].finish_reason ще бъде "length" вместо "stop"
if response.choices[0].finish_reason == "length":
print("Предупреждение: Отрязан отговор, увеличете max_tokens")
Винаги проверявайте finish_reason: ако е равен на "length", отговорът е непълен, независимо какво пише в останалата част от съдържанието.
Втората грешка засяга типовете. Възраст може да пристигне като низ, цена като цяло число, когато очаквате число с плаваща запетая. Вместо да се доверявате на изхода, обвийте достъпа в помощна функция, която опитва конвертиране и се връща към стойност по подразбиране при неуспех.
def safe_get_int(data: dict, key: str, default: int = 0) -> int:
"""Извлича цяло число, с конвертиране при необходимост."""
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
# Употреба
age = safe_get_int(data, "age", default=0)
Третата е преименуване на ключове. При френски подканаващ текст (prompt), моделът може лесно да смени phone на telephone или name на nom. Карта със синоними поглъща тези вариации, без да се налага да повтаряте извикването.
def normalize_keys(data: dict, key_mapping: dict) -> dict:
"""Нормализира ключовете чрез карта със синоними."""
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
# Карта със синоними
mapping = {
"name": ["name", "nom", "full_name", "fullName"],
"email": ["email", "mail", "e-mail", "emailAddress"],
"phone": ["phone", "telephone", "tel", "phoneNumber"],
}
normalized = normalize_keys(raw_data, mapping)
Повторен опит с обратна връзка
Когато валидацията се провали въпреки най-добрите Ви усилия, най-добрият отговор не е да повторите точно същото извикване: трябва да кажете на модела какво се е объркало. Като върнете неговия собствен отговор обратно в разговора заедно със съобщението за грешка, му предоставяте контекста, необходим за самокорекция, обикновено още при втория опит.
import json
def call_with_retry(client, messages, max_retries=3):
"""Извикване с повторен опит и обратна връзка за грешки."""
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) # Вашата функция за валидация
return data
except (json.JSONDecodeError, ValueError) as e:
if attempt < max_retries - 1:
# Добавяне на обратна връзка за грешката в контекста
messages.append({"role": "assistant", "content": raw})
messages.append({
"role": "user",
"content": f"Вашият отговор е невалиден: {e}. Коригирайте го и върнете валиден JSON."
})
else:
raise RuntimeError(f"Неуспех след {max_retries} опита: {e}")
Сигналът за промяна на подхода
Ако се окажете, че пишете обширен код за валидация, това е силен сигнал, че е време да преминете към Персонализирани структурирани изходи (Custom Structured Outputs). Три типични прага потвърждават това: при повече от пет полета за валидиране, контролната функция става по-дълга от самото извикване; щом типовете станат сложни с вложени списъци или изброими типове (enums), ръчната валидация става неразделна от бъговете, които въвежда; и за всеки критичен продукционен конвейер, делегирането на ограниченията към схемата е просто по-безопасно от тяхното ръчно възстановяване.
Ключови изводи
- JSON режимът гарантира валиден JSON, но не и валидна схема
- Винаги валидирайте изхода от страна на клиента: проверявайте за задължителни ключове, правилни типове и стойности в допустимите граници
- Проверете
finish_reason, за да откриете отрязани отговори - Внедрете механизъм за повторен опит с обратна връзка за грешки
- Ако валидацията стане сложна, преминете към Персонализирани структурирани изходи