Validálási és újrapróbálkozási stratégiák
Ezen az oldalon
Validálás: Az utolsó védvonal a élesítés előtt
Még az egyéni strukturált kimenetek használata esetén is elengedhetetlen a validálás. A séma garantálja a szerkezetet, de nem a szemantikai koherenciát. Egy price mező tartalmazhat -999.0 értéket: ez egy érvényes lebegőpontos szám, amely tökéletesen illeszkedik a sémához, mégsem van értelme ár esetén.
A különbség egyértelmű. A Pydantic és a Zod automatikusan kezeli a strukturális validálást: kötelező mezők, mezőtípusok, enum-korlátozások és beágyazott struktúrák. Ehhez nem kell kódot írnod. A szemantikai validálás azonban teljes mértékben a te felelősséged. Ide tartoznak a numerikus korlátok (az árnak nagyobbnak kell lennie nullánál, a pontszámnak 0 és 1 között kell lennie), a mezők közötti konzisztencia (a végösszegnek meg kell egyeznie a tételsorok összegével), a karakterlánc-formátumok (egy valóban érvényes e-mail cím, egy helyesen formázott dátum) és az üzleti logika (a fizetési határidőnek későbbinek kell lennie, mint a számla kelte).
Üzleti szabályok beágyazása a sémába
A Pydantic lehetővé teszi, hogy ezeket az ellenőrzéseket közvetlenül a modellbe ágyazd, így azok elválaszthatatlanná válnak a szerkezettől. Az @field_validator egyes mezőket kezel – például biztosítja, hogy a mennyiség pozitív legyen, vagy az egységár ne legyen negatív. Az @model_validator(mode="after") egyszer fut le, miután az összes mező feltöltődött, lehetővé téve a mezők közötti ellenőrzéseket, például annak igazolását, hogy a megadott végösszeg egy cent pontossággal megegyezik a mennyiség szorozva az egységárral értékkel.
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
A Zod ugyanerre a logikára épül beépített korlátozásokkal, mint például a .positive() és .nonnegative() a mezőkhöz, valamint a .refine() használatával a teljes objektumra alkalmazott, objektumok közötti szabályokhoz.
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" }
);
Újrapróbálkozás visszacsatolással
Ha a validálás sikertelen, a leghatékonyabb minta, ha visszaküldöd a hibát a modellnek, hogy kijavíthassa magát. Az alábbi függvény három ellenőrzést láncol össze fontossági sorrendben: teljes válasz, nem null objektum és üzleti szabályoknak való megfelelés. Hiba esetén a hibás választ és a hibaüzenetet hozzáfűzi a beszélgetéshez, így a következő kísérlet pontos diagnosztikai kontextust kap. Figyeld meg az üzenetlista másolatát a függvény elején – enélkül szennyeznéd a hívó fél beszélgetési előzményeit.
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}"
)
Tartalék tervek kaszkádja
Az újrapróbálkozás nem old meg mindent: néha egy dokumentum túl atipikus a sémához. A hirtelen leállás helyett alkalmazz fokozatos visszalépést. Az első kísérlet az egyéni strukturált kimeneteket használja, ami a legmegbízhatóbb lehetőség. Ha ez sikertelen, lépj vissza a JSON módra, amely engedékenyebb, majd vezesd át a kimenetet a model_validate() függvényen – ez megtartja a séma korlátozásait anélkül, hogy a modelltől várnád a tökéletes generálást. Utolsó lehetőségként a függvény None értéket ad vissza, így a hívó fél dönthet a manuális sorba állítás vagy a feladás között.
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
Idejében zárd el a csapot
Nagy gyakoriságú folyamatok esetén egy API-kimaradás felerősítőként hat az újrapróbálkozásra: minden dokumentum háromszor bukik el, a számlád megháromszorozódik, és a késleltetés megugrik. Egy megszakító áramkör (circuit breaker) figyeli a hibákat egy csúszó ablakban, és blokkolja a hívásokat, ha átlépi a küszöbértéket – a itt bemutatott konfigurációban öt hiba hatvan másodpercen belül. Egy siker bezárja az áramkört és törli a számlálót.
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
Tedd láthatóvá
Mindez a gépezet vak marad nyomkövetés nélkül. Naplózz minden hívást az időtartamával és az érintett sémával, függetlenül attól, hogy sikerült-e vagy sem. Ezek az adatok később lehetővé teszik annak meghatározását, hogy a romlás modellhibából, dokumentumtípusból vagy prompt-változtatásból ered-e.
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
Főbb megállapítások
- A strukturális validálás (típusok) automatikus; a szemantikai validálás (logika) a te felelősséged
- A visszacsatolással történő újrapróbálkozás a leghatékonyabb minta: küldd vissza a hibát a modellnek
- Implementálj tartalék kaszkádot: Egyéni > JSON mód > alapértelmezett érték
- Nagy gyakoriságú éles környezetben használj megszakító áramkört a hibakaszádok megelőzésére
- Naplózz minden hívást a monitorozás és a diagnosztika érdekében