Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Strategie validace a opakování

Lekce 11 z 12 Aktualizováno 2. listopadu 2026 Vývojář
Na této stránce
  1. Validace: Poslední linie obrany před nasazením do produkce
  2. Vkládání obchodních pravidel do schématu
  3. Opakování s zpětnou vazbou
  4. Kaskáda záložních plánů
  5. Včas uzavři kohoutek
  6. Zajisti viditelnost
  7. Klíčové poznatky

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