Przejdź do głównej treści
Polski— Wybierz język
Menu

Strategie walidacji i ponawiania prób

Lekcja 11 z 12 Zaktualizowano 2 listopada 2026 Programista
Na tej stronie
  1. Walidacja: ostatnia linia obrony przed produkcją
  2. Osadzanie reguł biznesowych w schemacie
  3. Ponawianie prób z informacją zwrotną
  4. Kaskada planów awaryjnych
  5. Terminowe odcięcie dopływu
  6. Zapewnij widoczność
  7. Kluczowe wnioski

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.