Begränsningar och felhantering i JSON-läge
På denna sida
Giltigt betyder inte korrekt
JSON-läge garanterar syntaktiskt giltig JSON, inte semantiskt korrekt JSON. Denna distinktion kan verka subtil under utvecklingen, men blir avgörande i produktion. JSON som parsas utan fel men innehåller oväntade nycklar skapar exakt den typ av bugg som tar dagar att spåra, eftersom inget undantag utlöses när problemet faktiskt uppstår.
Inga schemagarantier
Mekanismen vet ingenting om ditt schema: den har aldrig sett den struktur din kod förväntar sig. Modellen kan utelämna ett fält du behöver, lägga till ett du inte begärt, byta namn på en nyckel – firstName istället för first_name – eller ändra en typ genom att returnera "42" som en sträng när du förväntade dig talet 42. Inget av detta är ogiltig JSON.
# Du förväntar dig detta:
# {"name": "Alice", "age": 30, "city": "Paris"}
# Men du kan få:
# {"nom": "Alice", "âge": "trente ans", "ville": "Paris", "pays": "France"}
JSON:en är giltig, men strukturen matchar inte vad din kod förväntar sig. Detta är den fundamentala skillnaden jämfört med anpassade strukturerade utdata.
Obligatorisk validering på klientsidan
Eftersom schemat inte garanteras faller valideringen på dig. Det minimala mönstret gör tre saker i ordning: det försöker parsa, verifierar att roten är ett objekt (inte en lista eller skalär), och kontrollerar sedan efter obligatoriska nycklar. Varje fel lyfter ett ValueError med ett meddelande du kan använda i dina loggar.
import json
from typing import Optional
def parse_and_validate(raw_content: str, required_keys: list[str]) -> dict:
"""Parsa JSON och verifiera obligatoriska nycklar."""
try:
data = json.loads(raw_content)
except json.JSONDecodeError as e:
raise ValueError(f"Ogiltig JSON: {e}")
if not isinstance(data, dict):
raise ValueError(f"Förväntade JSON-objekt, fick {type(data).__name__}")
missing = [k for k in required_keys if k not in data]
if missing:
raise ValueError(f"Saknade nycklar: {missing}")
return data
# Användning
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"Ogiltigt utdata: {e}")
fallback_processing(raw_content)
TypeScript-versionen går ett steg längre genom att verifiera, utöver nycklarnas närvaro, att den returnerade kategorin tillhör den tillåtna listan. Detta är den kontroll som oftast saknas, och den som förhindrar att ett ärende klassificerat som "urgent_billing" smiter igenom din routning i tysthet.
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(`Saknade nycklar: ${missing.join(", ")}`);
}
const validCategories = ["billing", "account", "technical", "feature_request", "other"];
if (!validCategories.includes(data.category)) {
throw new Error(`Ogiltig kategori: ${data.category}`);
}
return data as TicketClassification;
}
Tre fel du kommer att stöta på
Det första är trunkerad JSON. Om svaret når max_tokens-gränsen klipps det av mitt i strömmen och blir ogiltigt – den avslutande klammern anländer aldrig. Du kan upptäcka symtomen innan du ens parsar: finish_reason är lika med "length" istället för "stop".
response = client.chat.complete(
model="mistral-small-latest",
messages=messages,
response_format={"type": "json_object"},
max_tokens=50 # För litet för komplett JSON
)
# response.choices[0].finish_reason kommer att vara "length" istället för "stop"
if response.choices[0].finish_reason == "length":
print("Varning: Trunkerat svar, öka max_tokens")
Kontrollera alltid finish_reason: om det är lika med "length" är svaret ofullständigt, oavsett vad resten av innehållet säger.
Det andra felet gäller typer. En ålder kan anlända som en sträng, ett pris som ett heltal när du förväntar dig ett flyttal. Istället för att lita på utdatat, kapsla in åtkomsten i en hjälpare som försöker konvertera och faller tillbaka på ett standardvärde om det misslyckas.
def safe_get_int(data: dict, key: str, default: int = 0) -> int:
"""Extrahera ett heltal, med konvertering vid behov."""
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
# Användning
age = safe_get_int(data, "age", default=0)
Det tredje är namnbyte på nycklar. Med en fransk prompt kan modellen lätt byta ut phone mot telephone, eller name mot nom. En synonymmappning absorberar dessa variationer utan att kräva att du försöker anropet igen.
def normalize_keys(data: dict, key_mapping: dict) -> dict:
"""Normalisera nycklar med hjälp av en synonymmappning."""
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
# Synonymmappning
mapping = {
"name": ["name", "nom", "full_name", "fullName"],
"email": ["email", "mail", "e-mail", "emailAddress"],
"phone": ["phone", "telephone", "tel", "phoneNumber"],
}
normalized = normalize_keys(raw_data, mapping)
Försök igen med återkoppling
När valideringen misslyckas trots dina bästa ansträngningar är det bästa svaret inte att försöka igen med exakt samma anrop: det är att tala om för modellen vad som gick fel. Genom att mata tillbaka dess eget svar i konversationen tillsammans med felmeddelandet ger du den den kontext som behövs för att självrätta sig, vanligtvis vid andra försöket.
import json
def call_with_retry(client, messages, max_retries=3):
"""Anropa med försök och felåterkoppling."""
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) # Din valideringsfunktion
return data
except (json.JSONDecodeError, ValueError) as e:
if attempt < max_retries - 1:
# Lägg till felåterkoppling i kontexten
messages.append({"role": "assistant", "content": raw})
messages.append({
"role": "user",
"content": f"Ditt svar är ogiltigt: {e}. Rätta det och returnera giltig JSON."
})
else:
raise RuntimeError(f"Misslyckades efter {max_retries} försök: {e}")
Signalen att ändra strategi
Om du märker att du skriver omfattande valideringskod är det en stark signal att det är dags att migrera till anpassade strukturerade utdata. Tre typiska tröskelvärden bekräftar detta: bortom fem fält att validera blir kontrollfunktionen längre än själva anropet; när typerna blir komplexa med nästlade listor eller enumerationer blir manuell validering oskiljaktig från de buggar den introducerar; och för varje kritisk produktionspipeline är det helt enkelt säkrare att delegera begränsningar till schemat än att återskapa dem för hand.
Viktiga punkter
- JSON-läge garanterar giltig JSON, inte ett giltigt schema
- Validera alltid utdata på klientsidan: kontrollera efter obligatoriska nycklar, korrekta typer och värden inom gränser
- Kontrollera
finish_reasonför att upptäcka trunkerade svar - Implementera en mekanism för försök med felåterkoppling
- Om valideringen blir komplex, migrera till anpassade strukturerade utdata