Validatie- en retry-strategieën
Op deze pagina
Validatie: de laatste verdedigingslinie voordat u naar productie gaat
Zelfs met Custom Structured Outputs blijft validatie essentieel. Het schema garandeert de structuur, niet de semantische coherentie. Een veld price kan bijvoorbeeld -999.0 bevatten: een geldige float die perfect overeenkomt met het schema, maar die geen enkele zin heeft als prijs.
Het onderscheid is duidelijk. Pydantic en Zod behandelen structurele validatie automatisch: verplichte velden, veldtypen, enum-beperkingen en geneste structuren. U hoeft hiervoor geen code te schrijven. Semantische validatie is echter volledig uw verantwoordelijkheid. Dit omvat numerieke grenswaarden (een prijs groter dan nul, een score tussen 0 en 1), consistentie tussen velden (het totaal moet gelijk zijn aan de som van de regelitems), string-formaten (een echt geldig e-mailadres, een correct opgemaakte datum) en bedrijfslogica (een vervaldatum die later ligt dan de factuurdatum).
Bedrijfsregels inbedden in het schema
Met Pydantic kunt u deze controles direct in het model inbedden, waardoor ze onlosmakelijk verbonden zijn met de structuur. @field_validator handelt individuele velden af—bijvoorbeeld om ervoor te zorgen dat een hoeveelheid positief is of een eenheidsprijs niet negatief. @model_validator(mode="after") wordt uitgevoerd zodra alle velden zijn ingevuld, waardoor controles tussen velden mogelijk zijn, zoals het verifiëren dat het opgegeven totaal binnen één cent overeenkomt met hoeveelheid × eenheidsprijs.
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 drukt dezelfde logica uit met ingebouwde beperkingen zoals .positive() en .nonnegative() voor velden, en .refine() voor regels die objecten overschrijden en worden toegepast op het volledige object.
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 met feedback
Wanneer validatie mislukt, is het meest effectieve patroon om de fout terug te sturen naar het model, zodat het zichzelf kan corrigeren. De onderstaande functie ketent drie controles aan elkaar in volgorde van belang: volledige respons, niet-null object en naleving van bedrijfsregels. Bij falen voegt deze de foutieve respons en het foutbericht toe aan het gesprek, waardoor de volgende poging een precieze diagnostische context heeft. Let op de kopie van de berichtenlijst aan het begin van de functie; zonder deze zou u de gespreksgeschiedenis van de aanroeper vervuilen.
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}"
)
Een cascade van fallback-plannen
Retry lost niet alles op: soms is een document te atypisch voor het schema. In plaats van abrupt te falen, degradeert u geleidelijk. De eerste poging gebruikt Custom Structured Outputs, de meest betrouwbare optie. Als dat mislukt, valt u terug op JSON Mode, dat soepeler is, en voert u de output door model_validate()—dit behoudt schemabeperkingen zonder te vertrouwen op het model om ze perfect te genereren. Als laatste redmiddel geeft de functie None terug, waardoor de aanroeper kan beslissen tussen handmatige wachtrijplaatsing of afbreken.
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
Sluit de kraan op tijd
In een pipeline met hoge frequentie verandert een API-storing retry in een versterker: elk document faalt drie keer, uw factuur verdrievoudigt en de latentie piekt. Een circuit breaker bewaakt fouten over een glijdend venster en blokkeert oproepen zodra een drempelwaarde wordt overschreden—vijf fouten in zestig seconden in de hier getoonde configuratie. Een succes sluit het circuit en wist de teller.
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
Maak het zichtbaar
Al deze mechanismen blijven blind zonder traces. Log elke oproep met de duur en het betrokken schema, ongeacht of deze slaagt of faalt. Met deze gegevens kunt u later bepalen of degradatie voortkomt uit een modelprobleem, een documenttype of een wijziging in de 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
Belangrijkste punten
- Structurele validatie (typen) is automatisch; semantische validatie (logica) is uw verantwoordelijkheid
- Retry met feedback is het meest effectieve patroon: stuur de fout terug naar het model
- Implementeer een fallback-cascade: Custom > JSON Mode > standaardwaarde
- Gebruik in productieomgevingen met hoge frequentie een circuit breaker om foutcascades te voorkomen
- Log elke oproep voor monitoring en diagnostiek