Strategie validace a opakování
Na této stránce
Validace: Poslední linie obrany před nasazením do produkce
I při použití vlastních strukturovaných výstupů zůstává validace nezbytná. Schéma garantuje strukturu, nikoliv však sémantickou koherenci. Pole price může obsahovat -999.0: platný typ float, který dokonale odpovídá schématu, ale pro cenu nedává žádný smysl.
Rozdíl je jasný. Knihovny Pydantic a Zod zpracovávají strukturální validaci automaticky: povinná pole, typy polí, omezení výčtů (enum) a vnořené struktury. Pro toto nemusíš psát žádný kód. Sémantická validace je však plně v tvé režii. Zahrnuje číselné meze (cena větší než nula, skóre mezi 0 a 1), konzistenci mezi poli (celková částka se musí rovnat součtu řádků), formáty řetězců (skutečně platný e-mail, správně formátované datum) a obchodní logiku (datum splatnosti musí být později než datum faktury).
Vkládání obchodních pravidel do schématu
Pydantic ti umožňuje vložit tyto kontroly přímo do modelu, čímž se stanou neodlučitelnou součástí struktury. Dekorátor @field_validator zpracovává jednotlivá pole – například zajišťuje, že množství je kladné nebo jednotková cena není záporná. @model_validator(mode="after") se spustí až po naplnění všech polí, což umožňuje kontroly napříč poli, jako je ověření, zda uvedená celková částka odpovídá součinu množství × jednotková cena s tolerancí na setiny.
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 vyjadřuje stejnou logiku pomocí vestavěných omezení, jako jsou .positive() a .nonnegative() pro pole, a .refine() pro pravidla napříč objekty aplikovaná na celý 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" }
);
Opakování s zpětnou vazbou
Když validace selže, nejefektivnějším vzorcem je poslat chybu zpět modelu, aby se mohl opravit. Níže uvedená funkce řetězí tři kontroly v pořadí podle důležitosti: úplnost odpovědi, nenulový objekt a dodržení obchodních pravidel. Při selhání připojí chybnou odpověď a chybovou zprávu do konverzace, což poskytne dalšímu pokusu přesný diagnostický kontext. Všimni si kopie seznamu zpráv na začátku funkce – bez ní bys znečistil historii konverzace volajícího kódu.
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}"
)
Kaskáda záložních plánů
Opakování nevyřeší vše: někdy je dokument příliš atypický na to, aby odpovídal schématu. Místo náhlého selhání proveď graceful degradation (postupné snižování kvality). První pokus využívá vlastní strukturované výstupy, což je nejspolehlivější možnost. Pokud to selže, přejdi na režim JSON, který je benevolentnější, a poté předej výstup přes model_validate() – tím si zachováš omezení schématu, aniž bys spoléhal na to, že je model vygeneruje dokonale. Jako poslední možnost funkce vrátí None a nechá na volajícím, aby se rozhodl mezi manuálním zařazením do fronty nebo opuštěním úkolu.
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
Včas uzavři kohoutek
Ve vysoce frekventovaném pipeline se výpadek API změní v zesilovač chyb: každý dokument selže třikrát, tvůj účet se ztrojnásobí a latence vystřelí nahoru. Jistič (circuit breaker) monitoruje selhání v posuvném okně a jakmile je překročen práh, blokuje další volání – v zde uvedené konfiguraci je to pět selhání během šedesáti sekund. Úspěch jistič uzavře a vynuluje čítač.
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
Zajisti viditelnost
Všechny tyto mechanismy zůstávají slepé bez stop (traces). Loguj každé volání s jeho dobou trvání a použitým schématem, ať už uspěje, nebo selže. Tato data ti později umožní určit, zda degradace pramení z problému modelu, typu dokumentu, nebo změny 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
Klíčové poznatky
- Strukturální validace (typy) je automatická; sémantická validace (logika) je tvou odpovědností
- Opakování se zpětnou vazbou je nejefektivnější vzorec: pošli chybu zpět modelu
- Implementuj kaskádu záložních řešení: Vlastní > Režim JSON > výchozí hodnota
- Ve vysoce frekventované produkci použij jistič k prevenci kaskádových selhání
- Loguj každé volání pro účely monitoringu a diagnostiky