Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Strateegiad valideerimiseks ja uuesti proovimiseks

Õppetund 11 / 12 Värskendatud 2. november 2026 Arendajatele
Sellel lehel
  1. Valideerimine: viimane kaitsejoon enne tootmisse viimist
  2. Ärireeglite skeemi sisse põimimine
  3. Uuesti proovimine tagasisidega
  4. Varuplaanide kaskaad
  5. Lülita kraan õigel ajal kinni
  6. Tee see nähtavaks
  7. Peamised punktid

Valideerimine: viimane kaitsejoon enne tootmisse viimist

Isegi kui kasutad kohandatud struktureeritud väljundeid, jääb valideerimine hädavajalikuks. Skeem garanteerib struktuuri, mitte semantilist kooskõla. Väli price võib sisaldada väärtust -999.0: see on kehtiv ujukomaarv, mis vastab skeemile täiuslikult, kuid hinnana ei oma see mingit mõtet.

Erinevus on selge. Pydantic ja Zod teevad struktuurse valideerimise automaatselt: nõutavad väljad, väljatüübid, loendipiirangud ja pesastatud struktuurid. Selle jaoks ei pea sa ühtegi koodirida kirjutama. Semantiline valideerimine on aga täielikult sinu vastutus. Siia kuuluvad arvulised piirid (hind peab olema suurem kui null, skoor vahemikus 0–1), väljadevaheline kooskõla (summa peab võrduma ridade summadega), stringivormingud (tegelikult kehtiv e-posti aadress, korrektselt vormindatud kuupäev) ja ärireeglid (tähtaeg peab olema hilisem kui arve kuupäev).

Ärireeglite skeemi sisse põimimine

Pydantic võimaldab sul need kontrollid otse mudelisse põimida, muutes need struktuurist lahutamatuks. @field_validator haldab üksikuid välju – näiteks veendumaks, et kogus on positiivne või ühiku hind pole negatiivne. @model_validator(mode="after") käivitub alles siis, kui kõik väljad on täidetud, võimaldades teha väljadevahelisi kontrolle, nagu näiteks kontrollida, kas deklareeritud summa vastab koguse ja ühiku hinna korrutisele ühe sendi täpsusega.

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 väljendab sama loogikat, kasutades sisseehitatud piiranguid nagu .positive() ja .nonnegative() väljade jaoks ning .refine() objektidevaheliste reeglite jaoks, mida rakendatakse kogu objektile.

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" }
  );

Uuesti proovimine tagasisidega

Kui valideerimine ebaõnnestub, on kõige tõhusam muster saata viga mudelile tagasi, et see saaks ennast parandada. Allpool olev funktsioon aheldab kolm kontrolli tähtsuse järjekorras: vastuse täielikkus, objekti olemasolu (mitte-null) ja ärireeglite järgimine. Ebaõnnestumisel lisab see vigase vastuse ja veateate vestlusesse, pakkudes järgmisele katsele täpset diagnostilist konteksti. Pane tähele sõnumite loendi koopia tegemist funktsiooni alguses – ilma selleta saastaksid kutsuja vestlusajalugu.

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}"
                )

Varuplaanide kaskaad

Uuesti proovimine ei lahenda kõike: mõnikord on dokument skeemi jaoks liiga ebatüüpiline. Järsu ebaõnnestumise asemel taandu sujuvalt. Esimene katse kasutab kohandatud struktureeritud väljundeid, mis on kõige usaldusväärsem variant. Kui see ebaõnnestub, mine üle JSON-režiimile, mis on lubavam, ja seejärel lase väljund läbi model_validate() – see säilitab skeemi piirangud, tuginedamata mudelile nende täiuslikuks genereerimiseks. Viimase abinõuna tagastab funktsioon None, jättes kutsuja otsustada, kas järjekorda käsitsi lisada või protsessist loobuda.

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

Lülita kraan õigel ajal kinni

Suure sagedusega töövoos muudab API tõrge uuesti proovimise võimendiks: iga dokument ebaõnnestub kolm korda, sinu arve kolmekordistub ja latentsus hüppab. Vooluahela katkestaja (circuit breaker) jälgib tõrkeid liukuva akna jooksul ja blokeerib päringud, kui lävi ületatakse – siin näidatud konfiguratsioonis viis tõrget kuuekümne sekundi jooksul. Õnnestumine sulgeb ahela ja nullib loenduri.

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

Tee see nähtavaks

Kogu see masinavärk jääb pimedaks ilma jälgedeta. Logi iga väljakutse koos selle kestuse ja kaasatud skeemiga, olenemata sellest, kas see õnnestus või ebaõnnestus. Need andmed võimaldavad sul hiljem kindlaks teha, kas halvenemine tuleneb mudeli probleemist, dokumendi tüübist või viiba muutusest.

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

Peamised punktid

  • Strukturaalne valideerimine (tüübid) on automaatne; semantiline valideerimine (loogika) on sinu vastutus
  • Uuesti proovimine tagasisidega on kõige tõhusam muster: saada viga mudelile tagasi
  • Rakenda varuplaanide kaskaad: kohandatud > JSON-režiim > vaikimisi väärtus
  • Suure sagedusega tootmiskeskkonnas kasuta vooluahela katkestajat, et vältida vigade kaskaadi
  • Logi iga väljakutse jälgimiseks ja diagnostikaks