Validerings- og genforsøgsstrategier
På denne side
Validering: Det sidste forsvar før produktion
Selv med Custom Structured Outputs er validering afgørende. Skemaet garanterer strukturen, ikke den semantiske sammenhæng. Et price-felt kan indeholde -999.0: et gyldigt flydende tal, der matcher skemaet perfekt, men som giver ingen mening som en pris.
Forskellen er klar. Pydantic og Zod håndterer strukturel validering automatisk: påkrævede felter, felttyper, enum-begrænsninger og nestede strukturer. Du behøver ikke skrive kode til dette. Semantisk validering er derimod udelukkende dit ansvar. Dette inkluderer numeriske grænser (en pris større end nul, en score mellem 0 og 1), konsistens på tværs af felter (totalen skal svare til summen af linjeposter), strengformater (en reelt gyldig e-mail, et korrekt formateret dato) og forretningslogik (en forfaldsdato senere end fakturadatoen).
Indlejring af forretningsregler i skemaet
Pydantic lader dig indlejre disse tjek direkte i modellen, hvilket gør dem uadskillelige fra strukturen. @field_validator håndterer individuelle felter – for eksempel at sikre, at en mængde er positiv, eller at en enhedspris ikke er negativ. @model_validator(mode="after") kører, når alle felter er udfyldt, hvilket muliggør tjek på tværs af felter, såsom at verificere, at den angivne total svarer til mængde × enhedspris inden for én 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 udtrykker den samme logik ved hjælp af indbyggede begrænsninger som .positive() og .nonnegative() for felter samt .refine() for regler på tværs af objekter, der anvendes på det komplette 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" }
);
Genforsøg med feedback
Når valideringen fejler, er det mest effektive mønster at sende fejlen tilbage til modellen, så den kan rette sig selv. Funktionen nedenfor kæder tre tjek sammen i rækkefølge efter vigtighed: komplet svar, ikke-nul objekt og overholdelse af forretningsregler. Ved fejl tilføjes det fejlagtige svar og fejlmeddelelsen til samtalen, hvilket giver næste forsøg præcis diagnostisk kontekst. Bemærk kopien af meddelelseslisten i starten af funktionen – uden den ville du forurene callerens samtalehistorik.
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}"
)
En kaskade af reserveplaner
Genforsøg løser ikke alt: nogle gange er et dokument for atypisk til skemaet. I stedet for at fejle brat, skal du degradere gradvist. Det første forsøg bruger Custom Structured Outputs, den mest pålidelige mulighed. Hvis det fejler, falder du tilbage til JSON Mode, som er mere lempelig, og sender derefter outputtet gennem model_validate() – dette bevarer skemabegrænsninger uden at stole på, at modellen genererer dem perfekt. Som sidste udvej returnerer funktionen None, hvilket overlader det til calleren at vælge mellem manuel kø eller opgave.
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
Luk hanen i tide
I en pipeline med høj frekvens bliver et API-udfald til en forstærker ved genforsøg: hvert dokument fejler tre gange, din regning tredobles, og ventetiden eksploderer. En „circuit breaker” overvåger fejl i et glidende vindue og blokerer kald, når en tærskel overskrides – her fem fejl på tres sekunder. En succes lukker kredsløbet og nulstiller tælleren.
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
Gør det synligt
Alt dette maskineri forbliver blindt uden spor. Log hvert kald med dets varighed og det involverede skema, uanset om det lykkes eller fejler. Disse data giver dig mulighed for senere at afgøre, om nedbrydningen skyldes et modelproblem, en dokumenttype eller en ændring i prompten.
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
Vigtige pointer
- Strukturel validering (typer) er automatisk; semantisk validering (logik) er dit ansvar
- Genforsøg med feedback er det mest effektive mønster: send fejlen tilbage til modellen
- Implementér en reservekaskade: Custom > JSON Mode > standardværdi
- Brug en „circuit breaker” i produktion med høj frekvens for at forhindre fejlkaskader
- Log hvert kald til overvågning og diagnosticering