Strategie walidacji i ponawiania prób
Na tej stronie
Walidacja: ostatnia linia obrony przed produkcją
Nawet przy użyciu niestandardowych wyjść strukturalnych walidacja pozostaje kluczowa. Schemat gwarantuje strukturę, ale nie spójność semantyczną. Pole price może zawierać wartość -999.0: jest to poprawny typ float, idealnie zgodny ze schematem, który jednak nie ma sensu w kontekście ceny.
Różnica jest oczywista. Pydantic i Zod obsługują walidację strukturalną automatycznie: wymagane pola, typy pól, ograniczenia enum oraz struktury zagnieżdżone. Nie musisz pisać do tego żadnego kodu. Walidacja semantyczna leży jednak całkowicie po Twojej stronie. Obejmuje ona granice liczbowe (cena większa od zera, wynik między 0 a 1), spójność między polami (suma musi równać się sumie pozycji), formaty ciągów (prawidłowy adres e-mail, poprawnie sformatowana data) oraz logikę biznesową (termin płatności późniejszy niż data wystawienia faktury).
Osadzanie reguł biznesowych w schemacie
Pydantic pozwala wbudować te sprawdzenia bezpośrednio w model, czyniąc je nierozerwalnymi ze strukturą. Dekorator @field_validator obsługuje pojedyncze pola – na przykład zapewniając, że ilość jest dodatnia lub cena jednostkowa nie jest ujemna. @model_validator(mode="after") uruchamia się dopiero po wypełnieniu wszystkich pól, co umożliwia sprawdzanie zależności między polami, takie jak weryfikacja, czy podana suma zgadza się z iloczynem ilości i ceny jednostkowej z dokładnością do jednego grosza.
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 wyraża tę samą logikę, używając wbudowanych ograniczeń, takich jak .positive() i .nonnegative() dla pól, oraz .refine() dla reguł dotyczących całego obiektu, stosowanych do kompletnych danych.
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" }
);
Ponawianie prób z informacją zwrotną
Gdy walidacja nie powiedzie się, najskuteczniejszym wzorcem jest odesłanie błędu z powrotem do modelu, aby mógł się poprawić. Poniższa funkcja łączy trzy sprawdzenia w kolejności od najważniejszego: kompletność odpowiedzi, obiekt niebędący null oraz zgodność z regułami biznesowymi. W przypadku niepowodzenia dołącza ona błędną odpowiedź i komunikat o błędzie do konwersacji, dostarczając kolejnej próbie precyzyjny kontekst diagnostyczny. Zwróć uwagę na skopiowanie listy wiadomości na początku funkcji – bez tego zanieczyściłbyś historię konwersacji wywołującego.
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 planów awaryjnych
Ponawianie prób nie rozwiązuje wszystkiego: czasami dokument jest zbyt nietypowy dla schematu. Zamiast gwałtownie przerywać działanie, zastosuj graceful degradation. Pierwsza próba wykorzystuje niestandardowe wyjścia strukturalne, czyli najbardziej niezawodną opcję. Jeśli to zawiedzie, przełącz się na tryb JSON, który jest bardziej elastyczny, a następnie przekaż wynik przez model_validate() – zachowuje to ograniczenia schematu bez polegania na modelu, by generował je idealnie. Jako ostateczność funkcja zwraca None, pozostawiając wywołującemu decyzję między ręcznym kolejkowaniem a porzuceniem zadania.
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
Terminowe odcięcie dopływu
W potoku o wysokiej częstotliwości awaria API zamienia mechanizm ponawiania prób w wzmacniacz błędów: każdy dokument zawodzi trzy razy, rachunek rośnie trzykrotnie, a opóźnienia skaczą. Wyłącznik nadprądowy (circuit breaker) monitoruje liczbę niepowodzeń w ruchomym oknie czasowym i blokuje wywołania po przekroczeniu progu – w przedstawionej konfiguracji jest to pięć błędów w ciągu sześćdziesięciu sekund. Sukces zamyka obwód i czyści licznik.
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
Zapewnij widoczność
Cały ten mechanizm pozostaje ślepy bez śladów audytowych. Loguj każde wywołanie wraz z jego czasem trwania i użytym schematem, niezależnie od tego, czy zakończyło się sukcesem, czy porażką. Dane te pozwalają później ustalić, czy degradacja wynika z problemu modelu, typu dokumentu, czy zmiany promptu.
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
Kluczowe wnioski
- Walidacja strukturalna (typy) jest automatyczna; walidacja semantyczna (logika) leży po Twojej stronie.
- Ponawianie prób z informacją zwrotną to najskuteczniejszy wzorzec: odsyłaj błąd z powrotem do modelu.
- Wdróż kaskadę planów awaryjnych: Niestandardowe > Tryb JSON > wartość domyślna.
- W środowisku produkcyjnym o wysokiej częstotliwości używaj wyłącznika nadprądowego, aby zapobiec kaskadom błędów.
- Loguj każde wywołanie w celach monitorowania i diagnostyki.