Salt la conținutul principal
Română— Alege o limbă
Meniu

Strategii de validare și reîncercare

Lecția 11 din 12 Actualizată 2 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Validarea: ultima linie de apărare înainte de producție
  2. Integrarea regulilor de afaceri în schemă
  3. Reîncercare cu feedback
  4. O cascadă de planuri de rezervă
  5. Închideți robinetul la timp
  6. Asigurați vizibilitatea
  7. Puncte cheie

Validarea: ultima linie de apărare înainte de producție

Chiar și cu ieșiri structurate personalizate (Custom Structured Outputs), validarea rămâne esențială. Schema garantează structura, nu coerența semantică. Un câmp price poate conține -999.0: un float valid care se potrivește perfect cu schema, dar care nu are niciun sens pentru un preț.

Distincția este clară. Pydantic și Zod gestionează automat validarea structurală: câmpuri obligatorii, tipuri de câmpuri, constrângeri de enum și structuri imbricate. Nu trebuie să scrieți niciun cod pentru aceasta. Validarea semantică, însă, vă revine în întregime. Aceasta include limite numerice (un preț mai mare decât zero, un scor între 0 și 1), consistența între câmpuri (totalul trebuie să fie egal cu suma elementelor din linie), formatele de șiruri (o adresă de e-mail genuin validă, o dată formatată corect) și logica de afaceri (o dată de scadență ulterioară datei facturii).

Integrarea regulilor de afaceri în schemă

Pydantic vă permite să integrați aceste verificări direct în model, făcându-le inseparabile de structură. @field_validator gestionează câmpurile individuale – de exemplu, asigurându-se că o cantitate este pozitivă sau că un preț unitar nu este negativ. @model_validator(mode="after") rulează o singură dată după ce toate câmpurile au fost populate, permițând verificări între câmpuri, cum ar fi verificarea faptului că totalul declarat corespunde cu cantitatea × prețul unitar, cu o toleranță de un cent.

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 exprimă aceeași logică folosind constrângeri integrate precum .positive() și .nonnegative() pentru câmpuri, și .refine() pentru reguli care implică întregul obiect.

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" }
  );

Reîncercare cu feedback

Când validarea eșuează, cel mai eficient model este să trimiteți eroarea înapoi la model pentru a se putea autocorecta. Funcția de mai jos înlănțuie trei verificări în ordinea importanței: răspuns complet, obiect non-null și conformitatea cu regulile de afaceri. În caz de eșec, aceasta adaugă răspunsul eronat și mesajul de eroare la conversație, oferind următoarei încercări un context de diagnostic precis. Observați copierea listei de mesaje la începutul funcției – fără aceasta, ați polua istoricul conversației apelantului.

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}"
                )

O cascadă de planuri de rezervă

Reîncercarea nu rezolvă totul: uneori, un document este prea atipic pentru schemă. În loc să eșuați brusc, degradați procesul cu grație. Prima încercare folosește ieșiri structurate personalizate (Custom Structured Outputs), opțiunea cea mai fiabilă. Dacă aceasta eșuează, treceți la Modul JSON, care este mai permisiv, apoi transmiteți ieșirea prin model_validate() – astfel păstrați constrângerile schemei fără a vă baza pe model pentru a le genera perfect. Ca ultimă soluție, funcția returnează None, lăsând apelantul să decidă între punerea în coadă manuală sau abandonare.

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

Închideți robinetul la timp

Într-un pipeline de înaltă frecvență, o pană a API-ului transformă reîncercarea într-un amplificator: fiecare document eșuează de trei ori, factura se triplează, iar latența explodează. Un disjunctor (circuit breaker) monitorizează eșecurile pe o fereastră glisantă și blochează apelurile odată ce un prag este depășit – cinci eșecuri în șaizeci de secunde în configurația prezentată aici. Un succes închide circuitul și resetează contorul.

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

Asigurați vizibilitatea

Toată această mecanică rămâne oarbă fără urme (traces). Înregistrați în jurnal (log) fiecare apel cu durata sa și schema implicată, indiferent dacă reușește sau eșuează. Aceste date vă permit să determinați ulterior dacă degradarea provine de la o problemă a modelului, un tip de document sau o modificare a promptului.

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

Puncte cheie

  • Validarea structurală (tipuri) este automată; validarea semantică (logică) vă revine dumneavoastră
  • Reîncercarea cu feedback este cel mai eficient model: trimiteți eroarea înapoi la model
  • Implementați o cascadă de rezervă: Personalizat > Modul JSON > valoare implicită
  • În producția de înaltă frecvență, utilizați un disjunctor pentru a preveni cascadele de erori
  • Înregistrați în jurnal fiecare apel pentru monitorizare și diagnosticare