Strategije preverjanja veljavnosti in ponovnih poskusov
Na tej strani
Preverjanje veljavnosti: zadnja obrambna črta pred proizvodnjo
Tudi pri uporabi prilagojenih strukturiranih izhodov je preverjanje veljavnosti nujno. Shema zagotavlja strukturo, ne pa semantične skladnosti. Polje price lahko vsebuje vrednost -999.0: to je veljavno število s plavajočo vejico, ki popolnoma ustreza shemi, vendar za ceno nima smisla.
Razlika je jasna. Pydantic in Zod samodejno opravita strukturno preverjanje: obvezna polja, tipi polj, omejitve naštevanj (enum) in gnezdenje struktur. Za to ti ni treba napisati niti vrstice kode. Semantično preverjanje pa je v celoti tvoja odgovornost. Sem spadajo numerične meje (cena mora biti večja od nič, ocena med 0 in 1), doslednost med polji (vsota mora biti enaka seštevku postavk), formati nizov (dejansko veljaven e-poštni naslov, pravilno oblikovan datum) in poslovna logika (datum zapadlosti mora biti kasneje od datuma izstavitve računa).
Vgradnja poslovnih pravil v shemo
Pydantic ti omogoča, da te preverbe vgradiš neposredno v model, tako da postanejo neločljivi del strukture. Dekorator @field_validator obravnava posamezna polja – na primer zagotavlja, da je količina pozitivna ali da enotna cena ni negativna. Dekorator @model_validator(mode="after") se izvede, ko so vsa polja izpolnjena, kar omogoča preverjanja med polji, kot je preverjanje, ali navedena vsota ustreza zmnožku količine in enotne cene z natančnostjo do enega 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ža isto logiko z uporabo vgrajenih omejitev, kot sta .positive() in .nonnegative() za polja, ter .refine() za pravila, ki zajemajo celoten 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 poskus z povratnimi informacijami
Ko preverjanje veljavnosti ne uspe, je najučinkovitejši vzorec pošiljanje napake nazaj modelu, da se lahko popravi. Spodnja funkcija zaporedno izvaja tri preverbe po vrstnem redu pomembnosti: popolnost odgovora, obstoj objekta (ni null) in skladnost s poslovnimi pravili. Ob neuspehu doda napačen odgovor in sporočilo o napaki v pogovor, kar naslednjemu poskusu zagotovi natančen diagnostični kontekst. Upoštevaj kopijo seznama sporočil na začetku funkcije – brez nje bi onesnažil zgodovino pogovora klicatelja.
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 nadomestnih načrtov
Ponovni poskus ne reši vsega: včasih je dokument preveč netipičen za shemo. Namesto nenadnega neuspeha raje postopoma zmanjšaj zahteve. Prvi poskus uporabi prilagojene strukturirane izhode, kar je najbolj zanesljiva možnost. Če ta ne uspe, preklopi na način JSON (JSON Mode), ki je bolj dopustljiv, nato pa izhod prepusti metodi model_validate() – s tem ohraniš omejitve sheme, ne da bi se zanašal na to, da jih bo model popolnoma ustvaril. Kot zadnjo možnost funkcija vrne None, kar klicatelju prepusti odločitev med ročno obdelavo v čakalni vrsti ali opustitvijo.
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
Pravočasno zaustavi dotok
V visokofrekvenčnem cevovodu izpad API-ja spremeni ponovne poskuse v ojačevalnik: vsak dokument trikrat ne uspe, tvoj račun se potroji, latenca pa poskoči. Prekinitveno stikalo (circuit breaker) spremlja napake v drsečem časovnem oknu in blokira klice, ko je presežen določen prag – v tukaj prikazani konfiguraciji je to pet napak v šestdesetih sekundah. Uspeh stikalo zapre in počisti števec.
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
Poskrbi za vidnost
Vsa ta mehanika ostane slepa brez sledenja. Zabeleži vsak klic z njegovim trajanjem in vključeno shemo, ne glede na to, ali uspe ali ne. Ti podatki ti kasneje omogočijo, da ugotoviš, ali degradacija izvira iz težave z modelom, vrste dokumenta ali spremembe poziva.
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 ugotovitve
- Strukturno preverjanje (tipi) je samodejno; semantično preverjanje (logika) je tvoja odgovornost.
- Ponovni poskus s povratnimi informacijami je najučinkovitejši vzorec: napako pošlji nazaj modelu.
- Implementiraj kaskado nadomestnih rešitev: prilagojeni izhod > način JSON > privzeta vrednost.
- V proizvodnem okolju z visoko frekvenco uporabi prekinitveno stikalo za preprečevanje kaskadnih napak.
- Zabeleži vsak klic zaradi nadzora in diagnostike.