Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Strategie di convalida e retry

Lezione 11 di 12 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Convalida: l’ultima linea di difesa prima della produzione
  2. Incorporare le regole aziendali nello schema
  3. Retry con feedback
  4. Una cascata di piani di fallback
  5. Interrompi il flusso in tempo utile
  6. Rendi tutto visibile
  7. Punti chiave

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