Stratēģijas validācijai un atkārtošanai
Šajā lapā
Validācija: pēdējā aizsardzības līnija pirms ražošanas vides
Pat izmantojot pielāgotas strukturētas izvades, validācija joprojām ir obligāta. Shēma garantē struktūru, bet ne semantisko loģiku. Lauks price var saturēt vērtību -999.0: tas ir derīgs peldošais komats, kas perfekti atbilst shēmai, taču cenai tas nav jēdzīgi.
Atšķirība ir skaidra. Pydantic un Zod automātiski veic strukturālo validāciju: obligātie lauki, lauku tipi, enum ierobežojumi un ligzdotās struktūras. Tam tev nav jāraksta nekāds kods. Semantiskā validācija tomēr ir pilnībā tava atbildība. Tajā ietilpst skaitliskās robežas (cenai jābūt lielākai par nulli, vērtējumam no 0 līdz 1), lauku savstarpējā saskaņotība (kopsummai jābūt vienādai ar rindu pozīciju summu), virkņu formāti (patiesi derīgs e-pasts, pareizi formatēts datums) un biznesa loģika (apmaksas termiņam jābūt vēlākam par rēķina datumu).
Biznesa noteikumu iekļaušana shēmā
Pydantic ļauj šīs pārbaudes iegult tieši modelī, padarot tās neatdalāmas no struktūras. @field_validator apstrādā atsevišķus laukus — piemēram, nodrošinot, ka daudzums ir pozitīvs vai vienības cena nav negatīva. @model_validator(mode="after") tiek izpildīts vienreiz, kad visi lauki ir aizpildīti, ļaujot veikt starplaiku pārbaudes, piemēram, pārliecinoties, ka norādītā kopsumma atbilst reizinājumam „daudzums × vienības cena” ar precizitāti līdz vienam centam.
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 izsaka to pašu loģiku, izmantojot iebūvētos ierobežojumus, piemēram, .positive() un .nonnegative() laukiem, un .refine() noteikumiem, kas attiecas uz visu objektu.
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" }
);
Atkārtošana ar atgriezenisko saiti
Kad validācija neizdodas, visefektīvākā pieeja ir nosūtīt kļūdu atpakaļ modelim, lai tas varētu sevi labot. Tālāk redzamā funkcija secīgi veic trīs pārbaudes pēc nozīmīguma: pilnīga atbilde, objekts nav null un atbilstība biznesa noteikumiem. Neveiksmes gadījumā tā pievieno kļūdaino atbildi un kļūdas ziņojumu sarunai, nodrošinot nākamajam mēģinājumam precīzu diagnostikas kontekstu. Ņem vērā ziņojumu saraksta kopiju funkcijas sākumā — bez tā tu piesārņotu izsaucošās puses sarunas vēsturi.
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"
):
"""Ekstrahēšana ar atkārtošanu un strukturētu kļūdu atgriezenisko saiti."""
conversation = list(messages) # Kopē, lai nemainītu oriģinālu
for attempt in range(max_retries):
try:
response = client.chat.parse(
model=model,
messages=conversation,
response_format=schema,
temperature=0,
max_tokens=2048
)
# Pārbauda, vai atbilde ir pilnīga
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")
# Papildu semantiskā validācija
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:
# Pievieno atgriezenisko saiti kontekstam
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}"
)
Rezerves plānu kaskāde
Atkārtošana neatrisina visu: dažreiz dokuments ir pārāk netipisks shēmai. Tā vietā, lai pēkšņi apstātos, veic pakāpenisku degradāciju. Pirmais mēģinājums izmanto pielāgotas strukturētas izvades — visuzticamāko opciju. Ja tas neizdodas, pārej uz JSON režīmu, kas ir elastīgāks, un pēc tam nododi izvadi caur model_validate() — tas saglabā shēmas ierobežojumus, nepaļaujoties uz to, ka modelis tos ģenerēs perfekti. Kā pēdējo līdzekli funkcija atgriež None, ļaujot izsaucošajai pusei izlemt starp manuālu rindojumu vai atteikšanos.
def extract_with_fallback(client, text, schema, system_prompt):
"""Ekstrahēšana ar rezerves plānu kaskādi."""
# 1. mēģinājums: Pielāgota strukturēta izvade (labākais)
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")
# 2. mēģinājums: JSON režīms (elastīgāks)
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) # Mēģina Pydantic validāciju
except Exception:
print("JSON Mode failed, falling back to manual extraction")
# 3. mēģinājums: Atgriež daļēju objektu vai kļūdu
return None
Laicīgi apturi plūsmu
Augstas frekvences cauruļvadā API pārtraukums pārvērš atkārtošanu pastiprinātājā: katrs dokuments neizdodas trīs reizes, tavs rēķins trīskāršojas, un latentums strauji pieaug. Ķēdes pārtraucējs (circuit breaker) uzrauga kļūdas slīdošajā logā un bloķē izsaukumus, tiklīdz tiek sasniegts slieksnis — šeit parādītajā konfigurācijā tas ir piecas kļūdas sešdesmit sekundēs. Veiksmīgs izsaukums aizver ķēdi un notīra skaitītāju.
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)
# Notīra kļūdas ārpus loga
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
# Pārbauda, vai logs ir pagājis
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
# Lietošana
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
Padari to redzamu
Visi šie mehānismi paliek akli bez izsekojamības. Reģistrē katru izsaukumu ar tā ilgumu un iesaistīto shēmu neatkarīgi no tā, vai tas beidzas veiksmīgi vai neveiksmīgi. Šie dati ļauj vēlāk noteikt, vai degradāciju izraisa modeļa problēma, dokumenta veids vai prompta izmaiņas.
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
Galvenās atziņas
- Strukturālā validācija (tipi) ir automātiska; semantiskā validācija (loģika) ir tava atbildība
- Atkārtošana ar atgriezenisko saiti ir visefektīvākais modelis: nosūti kļūdu atpakaļ modelim
- Ievies rezerves plānu kaskādi: Pielāgots > JSON režīms > noklusējuma vērtība
- Augstas frekvences ražošanas vidē izmanto ķēdes pārtraucēju, lai novērstu kļūdu kaskādes
- Reģistrē katru izsaukumu uzraudzībai un diagnostikai