Strategii de validare și reîncercare
Pe această pagină
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