Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Strategije preverjanja veljavnosti in ponovnih poskusov

Lekcija 11 od 12 Posodobljeno 2. november 2026 Razvijalec
Na tej strani
  1. Preverjanje veljavnosti: zadnja obrambna črta pred proizvodnjo
  2. Vgradnja poslovnih pravil v shemo
  3. Ponovni poskus z povratnimi informacijami
  4. Kaskada nadomestnih načrtov
  5. Pravočasno zaustavi dotok
  6. Poskrbi za vidnost
  7. Ključne ugotovitve

Preverjanje veljavnosti: zadnja obrambna črta pred proizvodnjo

Tudi pri uporabi prilagojenih strukturiranih izhodov je preverjanje veljavnosti nujno. Shema zagotavlja strukturo, ne pa semantične skladnosti. Polje price lahko vsebuje vrednost -999.0: to je veljavno število s plavajočo vejico, ki popolnoma ustreza shemi, vendar za ceno nima smisla.

Razlika je jasna. Pydantic in Zod samodejno opravita strukturno preverjanje: obvezna polja, tipi polj, omejitve naštevanj (enum) in gnezdenje struktur. Za to ti ni treba napisati niti vrstice kode. Semantično preverjanje pa je v celoti tvoja odgovornost. Sem spadajo numerične meje (cena mora biti večja od nič, ocena med 0 in 1), doslednost med polji (vsota mora biti enaka seštevku postavk), formati nizov (dejansko veljaven e-poštni naslov, pravilno oblikovan datum) in poslovna logika (datum zapadlosti mora biti kasneje od datuma izstavitve računa).

Vgradnja poslovnih pravil v shemo

Pydantic ti omogoča, da te preverbe vgradiš neposredno v model, tako da postanejo neločljivi del strukture. Dekorator @field_validator obravnava posamezna polja – na primer zagotavlja, da je količina pozitivna ali da enotna cena ni negativna. Dekorator @model_validator(mode="after") se izvede, ko so vsa polja izpolnjena, kar omogoča preverjanja med polji, kot je preverjanje, ali navedena vsota ustreza zmnožku količine in enotne cene z natančnostjo do enega centa.

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 izraža isto logiko z uporabo vgrajenih omejitev, kot sta .positive() in .nonnegative() za polja, ter .refine() za pravila, ki zajemajo celoten 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" }
  );

Ponovni poskus z povratnimi informacijami

Ko preverjanje veljavnosti ne uspe, je najučinkovitejši vzorec pošiljanje napake nazaj modelu, da se lahko popravi. Spodnja funkcija zaporedno izvaja tri preverbe po vrstnem redu pomembnosti: popolnost odgovora, obstoj objekta (ni null) in skladnost s poslovnimi pravili. Ob neuspehu doda napačen odgovor in sporočilo o napaki v pogovor, kar naslednjemu poskusu zagotovi natančen diagnostični kontekst. Upoštevaj kopijo seznama sporočil na začetku funkcije – brez nje bi onesnažil zgodovino pogovora klicatelja.

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 nadomestnih načrtov

Ponovni poskus ne reši vsega: včasih je dokument preveč netipičen za shemo. Namesto nenadnega neuspeha raje postopoma zmanjšaj zahteve. Prvi poskus uporabi prilagojene strukturirane izhode, kar je najbolj zanesljiva možnost. Če ta ne uspe, preklopi na način JSON (JSON Mode), ki je bolj dopustljiv, nato pa izhod prepusti metodi model_validate() – s tem ohraniš omejitve sheme, ne da bi se zanašal na to, da jih bo model popolnoma ustvaril. Kot zadnjo možnost funkcija vrne None, kar klicatelju prepusti odločitev med ročno obdelavo v čakalni vrsti ali opustitvijo.

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

Pravočasno zaustavi dotok

V visokofrekvenčnem cevovodu izpad API-ja spremeni ponovne poskuse v ojačevalnik: vsak dokument trikrat ne uspe, tvoj račun se potroji, latenca pa poskoči. Prekinitveno stikalo (circuit breaker) spremlja napake v drsečem časovnem oknu in blokira klice, ko je presežen določen prag – v tukaj prikazani konfiguraciji je to pet napak v šestdesetih sekundah. Uspeh stikalo zapre in počisti števec.

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

Poskrbi za vidnost

Vsa ta mehanika ostane slepa brez sledenja. Zabeleži vsak klic z njegovim trajanjem in vključeno shemo, ne glede na to, ali uspe ali ne. Ti podatki ti kasneje omogočijo, da ugotoviš, ali degradacija izvira iz težave z modelom, vrste dokumenta ali spremembe poziva.

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

Ključne ugotovitve

  • Strukturno preverjanje (tipi) je samodejno; semantično preverjanje (logika) je tvoja odgovornost.
  • Ponovni poskus s povratnimi informacijami je najučinkovitejši vzorec: napako pošlji nazaj modelu.
  • Implementiraj kaskado nadomestnih rešitev: prilagojeni izhod > način JSON > privzeta vrednost.
  • V proizvodnem okolju z visoko frekvenco uporabi prekinitveno stikalo za preprečevanje kaskadnih napak.
  • Zabeleži vsak klic zaradi nadzora in diagnostike.