Strategie di convalida e retry
In questa pagina
Convalida: l’ultima linea di difesa prima della produzione
Anche con gli Output Strutturati Personalizzati, la convalida rimane essenziale. Lo schema garantisce la struttura, non la coerenza semantica. Un campo price potrebbe contenere -999.0: un float valido che rispetta perfettamente lo schema, ma che non ha alcun senso per un prezzo.
La distinzione è chiara. Pydantic e Zod gestiscono automaticamente la convalida strutturale: campi obbligatori, tipi di campo, vincoli enum e strutture nidificate. Non devi scrivere alcun codice per questo. La convalida semantica, invece, è interamente tua responsabilità. Include limiti numerici (un prezzo maggiore di zero, un punteggio tra 0 e 1), coerenza tra campi (il totale deve essere uguale alla somma delle righe), formati di stringa (un’email genuinamente valida, una data correttamente formattata) e logica aziendale (una data di scadenza successiva alla data della fattura).
Incorporare le regole aziendali nello schema
Pydantic ti permette di incorporare questi controlli direttamente nel modello, rendendoli inseparabili dalla struttura. @field_validator gestisce i singoli campi, ad esempio assicurandosi che una quantità sia positiva o che un prezzo unitario non sia negativo. @model_validator(mode="after") viene eseguito una volta popolati tutti i campi, consentendo controlli incrociati, come verificare che il totale dichiarato corrisponda a quantità × prezzo unitario entro un centesimo.
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 esprime la stessa logica utilizzando vincoli integrati come .positive() e .nonnegative() per i campi, e .refine() per le regole cross-object applicate all’oggetto completo.
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" }
);
Retry con feedback
Quando la convalida fallisce, il modello più efficace consiste nell’inviare l’errore al modello affinché possa correggersi. La funzione seguente concatena tre controlli in ordine di importanza: risposta completa, oggetto non nullo e conformità alle regole aziendali. In caso di fallimento, aggiunge la risposta errata e il messaggio di errore alla conversazione, fornendo al tentativo successivo un contesto diagnostico preciso. Nota la copia dell’elenco dei messaggi all’inizio della funzione: senza di essa, inquineresti la cronologia della conversazione del chiamante.
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"
):
"""Extraction with retry and structured error feedback."""
conversation = list(messages) # Copy to avoid modifying the original
for attempt in range(max_retries):
try:
response = client.chat.parse(
model=model,
messages=conversation,
response_format=schema,
temperature=0,
max_tokens=2048
)
# Check that the response is complete
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")
# Additional semantic validation
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:
# Add feedback to context
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}"
)
Una cascata di piani di fallback
Il retry non risolve tutto: a volte un documento è troppo atipico per lo schema. Invece di fallire bruscamente, degrada con grazia. Il primo tentativo utilizza gli Output Strutturati Personalizzati, l’opzione più affidabile. Se questo fallisce, passa alla Modalità JSON, che è più permissiva, quindi elabora l’output tramite model_validate(): ciò mantiene i vincoli dello schema senza fare affidamento sul modello per generarli perfettamente. Come ultima risorsa, la funzione restituisce None, lasciando al chiamante la decisione tra accodamento manuale o abbandono.
def extract_with_fallback(client, text, schema, system_prompt):
"""Extraction with fallback cascade."""
# Attempt 1: Custom Structured Output (best)
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")
# Attempt 2: JSON Mode (more flexible)
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) # Attempt Pydantic validation
except Exception:
print("JSON Mode failed, falling back to manual extraction")
# Attempt 3: Return partial object or error
return None
Interrompi il flusso in tempo utile
In una pipeline ad alta frequenza, un’interruzione dell’API trasforma il retry in un amplificatore: ogni documento fallisce tre volte, la fattura triplica e la latenza schizza alle stelle. Un circuit breaker monitora i guasti su una finestra scorrevole e blocca le chiamate una volta superata una soglia, ad esempio cinque guasti in sessanta secondi nella configurazione mostrata qui. Un successo chiude il circuito e azzera il contatore.
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)
# Clean up errors outside the window
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
# Check if the window has passed
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
# Usage
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
Rendi tutto visibile
Tutto questo macchinario rimane cieco senza tracce. Registra ogni chiamata con la sua durata e lo schema coinvolto, indipendentemente dal successo o dal fallimento. Questi dati ti permettono in seguito di determinare se il degrado deriva da un problema del modello, da un tipo di documento o da una modifica del prompt.
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
Punti chiave
- La convalida strutturale (tipi) è automatica; la convalida semantica (logica) è tua responsabilità
- Il retry con feedback è il modello più efficace: invia l’errore al modello
- Implementa una cascata di fallback: Personalizzato > Modalità JSON > valore predefinito
- In produzione ad alta frequenza, usa un circuit breaker per prevenire cascate di errori
- Registra ogni chiamata per il monitoraggio e la diagnostica