Strategije validacije i ponovnih pokušaja
Na ovoj stranici
Validacija: Posljednja linija obrane prije produkcije
Čak i uz prilagođene strukturirane izlaze (Custom Structured Outputs), validacija ostaje ključna. Shema jamči strukturu, ali ne i semantičku koherentnost. Polje price može sadržavati -999.0: valjan float koji savršeno odgovara shemi, ali nema smisla kao cijena.
Razlika je jasna. Pydantic i Zod automatski rješavaju strukturnu validaciju: obavezna polja, tipovi polja, ograničenja enuma i ugniježđene strukture. Za to ne moraš pisati nikakav kod. Semantička validacija, međutim, u potpunosti je tvoja odgovornost. To uključuje numeričke granice (cijena veća od nule, ocjena između 0 i 1), dosljednost između polja (ukupni iznos mora biti zbroj stavki), formate nizova (stvarno valjana e-mail adresa, ispravno formatiran datum) i poslovnu logiku (datum dospijeća kasniji od datuma računa).
Ugradnja poslovnih pravila u shemu
Pydantic ti omogućuje da ove provjere ugradiš izravno u model, čineći ih neodvojivima od strukture. @field_validator obrađuje pojedinačna polja—na primjer, osigurava da je količina pozitivna ili da jedinična cijena nije negativna. @model_validator(mode="after") pokreće se jednom kada su sva polja popunjena, omogućujući provjere između polja, poput verifikacije da navedeni ukupni iznos odgovara količini × jediničnoj cijeni unutar jednog centa.
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 izražava istu logiku koristeći ugrađena ograničenja poput .positive() i .nonnegative() za polja, te .refine() za pravila koja se odnose na cijeli objekt.
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" }
);
Ponovni pokušaj s povratnom informacijom
Kada validacija ne uspije, najučinkovitiji obrazac je poslati pogrešku natrag modelu kako bi se mogao ispraviti. Funkcija u nastavku lančano provodi tri provjere po važnosti: potpunost odgovora, postojanje objekta (nije null) i usklađenost s poslovnim pravilima. U slučaju neuspjeha, dodaje neispravan odgovor i poruku o pogrešci u razgovor, dajući sljedećem pokušaju precizan dijagnostički kontekst. Obrati pažnju na kopiranje popisa poruka na početku funkcije—bez toga bi onečistio povijest razgovora pozivatelja.
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}"
)
Kaskada rezervnih planova
Ponovni pokušaj ne rješava sve: ponekad je dokument previše atipičan za shemu. Umjesto naglog prekida, primijeni postupno degradiranje. Prvi pokušaj koristi prilagođene strukturirane izlaze, najpouzdaniju opciju. Ako to ne uspije, prebaci se na JSON Mode, koji je fleksibilniji, a zatim proslijedi izlaz kroz model_validate()—time zadržavaš ograničenja sheme bez oslanjanja na model da ih savršeno generira. Kao posljednje sredstvo, funkcija vraća None, prepuštajući pozivatelju odluku o ručnom stavljanju u red čekanja ili odustajanju.
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
Pravovremeno zatvori slavinu
U cjevovodu visoke frekvencije, zastoj API-ja pretvara ponovne pokušaje u pojačivač: svaki dokument ne uspije tri puta, tvoj račun se utrostručuje, a latencija raste. „Circuit breaker“ (osigurač kruga) prati neuspjehe u kliznom prozoru i blokira pozive nakon što se prijeđe prag—pet neuspjeha u šezdeset sekundi u ovdje prikazanoj konfiguraciji. Uspjeh zatvara krug i briše brojač.
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
Učini to vidljivim
Sav ovaj mehanizam ostaje slijep bez tragova. Zabilježi svaki poziv s njegovim trajanjem i uključenom shemom, bez obzira na to je li uspio ili ne. Ti podaci ti kasnije omogućuju da utvrdiš proizlazi li degradacija iz problema s modelom, vrste dokumenta ili promjene prompta.
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
Ključne točke
- Strukturna validacija (tipovi) je automatska; semantička validacija (logika) je tvoja odgovornost
- Ponovni pokušaj s povratnom informacijom najučinkovitiji je obrazac: pošalji pogrešku natrag modelu
- Implementiraj kaskadu rezervnih opcija: Prilagođeno > JSON Mode > zadana vrijednost
- U produkciji visoke frekvencije koristi „circuit breaker“ za sprječavanje kaskadnih pogrešaka
- Bilježi svaki poziv radi nadzora i dijagnostike