Strategier för validering och försök
På denna sida
Validering: Sista försvarslinjen innan produktion
Även med anpassade strukturerade utdata är validering avgörande. Schemat garanterar struktur, inte semantisk koherens. Ett fält price kan innehålla -999.0: ett giltigt flyttal som matchar schemat perfekt, men som är meningslöst som pris.
Skillnaden är tydlig. Pydantic och Zod hanterar strukturell validering automatiskt: obligatoriska fält, fälttyper, enum-begränsningar och nästlade strukturer. Du behöver inte skriva någon kod för detta. Semantisk validering är dock helt ditt ansvar. Detta inkluderar numeriska gränser (ett pris större än noll, ett betyg mellan 0 och 1), konsistens mellan fält (summan måste vara lika med summan av radposterna), strängformat (en verkligen giltig e-postadress, ett korrekt formaterat datum) och affärslogik (ett förfallodatum senare än fakturadatumet).
Inbäddning av affärsregler i schemat
Med Pydantic kan du bädda in dessa kontroller direkt i modellen, vilket gör dem oskiljaktiga från strukturen. @field_validator hanterar enskilda fält – till exempel för att säkerställa att en kvantitet är positiv eller att ett enhetspris inte är negativt. @model_validator(mode="after") körs när alla fält har fyllts i, vilket möjliggör kontroller mellan fält, såsom att verifiera att den angivna totalen stämmer överens med kvantitet × enhetspris inom en öre.
from pydantic import BaseModel, Field, field_validator, model_validator
class InvoiceLine(BaseModel):
description: str
quantity: float
unit_price: float
total: float
@field_validator("quantity")
@classmethod
def quantity_positive(cls, v):
if v <= 0:
raise ValueError(f"Quantity must be positive, got: {v}")
return v
@field_validator("unit_price")
@classmethod
def price_non_negative(cls, v):
if v < 0:
raise ValueError(f"Unit price cannot be negative: {v}")
return v
@model_validator(mode="after")
def check_total(self):
expected = round(self.quantity * self.unit_price, 2)
if abs(self.total - expected) > 0.01:
raise ValueError(
f"Inconsistent total: {self.total} != {self.quantity} x {self.unit_price} = {expected}"
)
return self
Zod uttrycker samma logik med inbyggda begränsningar som .positive() och .nonnegative() för fält, samt .refine() för regler mellan objekt som tillämpas på hela objektet.
import { z } from "zod";
const InvoiceLineSchema = z
.object({
description: z.string(),
quantity: z.number().positive("Quantity must be positive"),
unitPrice: z.number().nonnegative("Price cannot be negative"),
total: z.number(),
})
.refine(
(data) => Math.abs(data.total - data.quantity * data.unitPrice) < 0.01,
{ message: "Total does not match quantity x unit price" }
);
Försök med återkoppling
När valideringen misslyckas är det mest effektiva mönstret att skicka felet tillbaka till modellen så att den kan korrigera sig själv. Funktionen nedan kedjar tre kontroller i ordning efter vikt: komplett svar, icke-null-objekt och efterlevnad av affärsregler. Vid misslyckande läggs det felaktiga svaret och felmeddelandet till i konversationen, vilket ger nästa försök en exakt diagnostisk kontext. Observera kopieringen av meddelandelistan i början av funktionen – utan den skulle du förorena anroparens konversationshistorik.
from mistralai.client import Mistral
from pydantic import BaseModel, ValidationError
import json
def extract_with_retry(
client: Mistral,
messages: list,
schema,
max_retries: int = 3,
model: str = "mistral-large-latest"
):
"""Extraktion med försök och strukturerad felåterkoppling."""
conversation = list(messages) # Kopiera för att undvika att ändra originalet
for attempt in range(max_retries):
try:
response = client.chat.parse(
model=model,
messages=conversation,
response_format=schema,
temperature=0,
max_tokens=2048
)
# Kontrollera att svaret är komplett
if response.choices[0].finish_reason != "stop":
raise ValueError(
f"Incomplete response (finish_reason={response.choices[0].finish_reason})"
)
parsed = response.choices[0].message.parsed
if parsed is None:
raise ValueError("Parsed response is None")
# Ytterligare semantisk validering
validate_business_rules(parsed)
return parsed
except (ValidationError, ValueError) as e:
error_msg = str(e)
print(f"Attempt {attempt + 1}/{max_retries} failed: {error_msg}")
if attempt < max_retries - 1:
# Lägg till återkoppling i kontexten
raw = response.choices[0].message.content if response else ""
conversation.append({"role": "assistant", "content": raw})
conversation.append({
"role": "user",
"content": f"Your response contains an error: {error_msg}. Please correct it."
})
else:
raise RuntimeError(
f"Failed after {max_retries} attempts. Last error: {error_msg}"
)
En kaskad av reservplaner
Försök löser inte allt: ibland är ett dokument för otypiskt för schemat. Istället för att misslyckas abrupt, degradera gradvis. Det första försöket använder anpassade strukturerade utdata, det mest pålitliga alternativet. Om det misslyckas, falla tillbaka till JSON-läge, vilket är mer tillåtande, och skicka sedan utdata genom model_validate() – detta behåller schemabegränsningar utan att förlita sig på att modellen genererar dem perfekt. Som sista utväg returnerar funktionen None, vilket lämnar åt anroparen att besluta om manuell köläggning eller avbrott.
def extract_with_fallback(client, text, schema, system_prompt):
"""Extraktion med reservkaskad."""
# Försök 1: Anpassad strukturerad utdata (bäst)
try:
return extract_with_retry(
client,
[
{"role": "system", "content": system_prompt},
{"role": "user", "content": text}
],
schema,
max_retries=2,
model="mistral-large-latest"
)
except RuntimeError:
print("Custom parse failed, falling back to JSON Mode")
# Försök 2: JSON-läge (mer flexibelt)
try:
response = client.chat.complete(
model="mistral-large-latest",
messages=[
{"role": "system", "content": system_prompt + "\nReturn valid JSON."},
{"role": "user", "content": text}
],
response_format={"type": "json_object"},
temperature=0
)
raw = json.loads(response.choices[0].message.content)
return schema.model_validate(raw) # Försök med Pydantic-validering
except Exception:
print("JSON Mode failed, falling back to manual extraction")
# Försök 3: Returnera partiellt objekt eller fel
return None
Bryt strömmen i tid
I en pipeline med hög frekvens blir ett API-avbrott en förstärkare för försök: varje dokument misslyckas tre gånger, din faktura tredubblas och latensen spikar. En strömbrytare (circuit breaker) övervakar misslyckanden över ett glidande fönster och blockerar anrop när en tröskel passeras – fem misslyckanden på sextio sekunder i konfigurationen som visas här. En framgång stänger kretsen och nollställer räknaren.
from collections import deque
from time import time
class CircuitBreaker:
def __init__(self, failure_threshold=5, window_seconds=60):
self.failures = deque()
self.threshold = failure_threshold
self.window = window_seconds
self.is_open = False
def record_failure(self):
now = time()
self.failures.append(now)
# Rensa fel utanför fönstret
while self.failures and self.failures[0] < now - self.window:
self.failures.popleft()
if len(self.failures) >= self.threshold:
self.is_open = True
def record_success(self):
self.is_open = False
self.failures.clear()
def can_proceed(self) -> bool:
if not self.is_open:
return True
# Kontrollera om fönstret har passerat
now = time()
while self.failures and self.failures[0] < now - self.window:
self.failures.popleft()
if len(self.failures) < self.threshold:
self.is_open = False
return True
return False
# Användning
breaker = CircuitBreaker(failure_threshold=5, window_seconds=60)
def safe_extract(client, text, schema):
if not breaker.can_proceed():
raise RuntimeError("Circuit open—too many recent errors")
try:
result = extract_with_retry(client, [...], schema)
breaker.record_success()
return result
except RuntimeError:
breaker.record_failure()
raise
Gör det synligt
All denna maskineri förblir blind utan spår. Logga varje anrop med dess varaktighet och det inblandade schemat, oavsett om det lyckas eller misslyckas. Dessa data låter dig senare avgöra om försämringen härrör från ett modellproblem, en dokumenttyp eller en promptändring.
import logging
import time
logger = logging.getLogger("structured_output")
def monitored_extract(client, text, schema, **kwargs):
start = time.time()
try:
result = extract_with_retry(client, [...], schema, **kwargs)
duration = time.time() - start
logger.info(f"Extraction succeeded in {duration:.2f}s — schema={schema.__name__}")
return result
except Exception as e:
duration = time.time() - start
logger.error(f"Extraction failed in {duration:.2f}s — schema={schema.__name__} — {e}")
raise
Viktiga punkter
- Strukturell validering (typer) är automatisk; semantisk validering (logik) är ditt ansvar
- Försök med återkoppling är det mest effektiva mönstret: skicka felet tillbaka till modellen
- Implementera en reservkaskad: Anpassad > JSON-läge > standardvärde
- I produktion med hög frekvens, använd en strömbrytare för att förhindra felkaskader
- Logga varje anrop för övervakning och diagnostik