Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Strateġiji ta' Validazzjoni u Riprovament

Lezzjoni 11 / 12 Aġġornat 2 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Validazzjoni: L-Aħħar Linja ta’ Difiża Qabel il-Produzzjoni
  2. Inkorporazzjoni tar-Regoli tan-Negozju fl-Iskema
  3. Riprovament b’Ritorn ta’ Informazzjoni (Feedback)
  4. Kaskata ta’ Pjanijiet ta’ Riżerva
  5. Waqqaf il-Fluss fil-Ħin
  6. Agħmilha Viżibbli
  7. Punti Ewlenin

Validazzjoni: L-Aħħar Linja ta’ Difiża Qabel il-Produzzjoni

Anke bl-Usciti Strutturati Personalizzati (Custom Structured Outputs), il-validazzjoni tibqa’ essenzjali. L-iskema tiggarantixxi l-istruttura, mhux il-kohorenza semantika. Kamp price jista’ jkun fih -999.0: float validu li jaqbel perfettament mal-iskema, iżda li m’għandu l-ebda sens għal prezz.

Id-distinzjoni hija ċara. Pydantic u Zod jittrattaw il-validazzjoni strutturali awtomatikament: kampijiet meħtieġa, tipi ta’ kampijiet, restrizzjonijiet tal-enum, u strutturi mbejjna. M’għandekx bżonn tikteb ebda kodiċi għal dan. Il-validazzjoni semantika, madankollu, hija r-responsabbiltà tiegħek biss. Dan jinkludi limiti numeriċi (prezz akbar minn żero, punteġġ bejn 0 u 1), konsistenza bejn il-kampijiet (it-total irid ikun ugwali għas-somma tal-oġġetti), formati tal-kliem (email verament valida, data f’format korrett), u loġika tan-negozju (data ta’ skadenza aktar tard mid-data tal-fattura).

Inkorporazzjoni tar-Regoli tan-Negozju fl-Iskema

Pydantic jippermettilek li tħaffer dawn il-verifiki direttament fil-mudell, u jagħmilhom inseparabbli mill-istruttura. @field_validator jittratta kampijiet individwali—pereżempju, li jiżgura li kwantità hija pożittiva jew li prezz unitarju mhuwiex negattiv. @model_validator(mode="after") jinxtegħel darba wara li l-kampijiet kollha jkunu mimlija, u jippermetti verifiki bejn il-kampijiet, bħall-verifika li t-total iddikjarat jaqbel ma’ kwantità × prezz unitarju fi ħdan ċenteżmu wieħed.

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 jesprimi l-istess loġika billi juża restrizzjonijiet integrati bħal .positive() u .nonnegative() għall-kampijiet, u .refine() għar-regoli bejn l-oġġetti applikati għall-oġġett sħiħ.

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

Riprovament b’Ritorn ta’ Informazzjoni (Feedback)

Meta l-validazzjoni tfalli, l-aktar mudell effettiv huwa li tibgħat l-iżball lura lill-mudell sabiex ikun jista’ jikkoreġi ruħu. Il-funzjoni hawn taħt tgħaqqad tliet verifiki f’ordni ta’ importanza: tweġiba sħiħa, oġġett mhux null, u konformità mar-regoli tan-negozju. Fil-każ ta’ falliment, iżżid it-tweġiba żbaljata u l-messaġġ tal-iżball mal-konversazzjoni, u tagħti lit-tentattiv li jmiss kuntest dijanjostiku preċiż. Innota l-kopja tal-lista tal-messaġġi fil-bidu tal-funzjoni—mingħajrha, tkun qed tniġġes l-istorja tal-konversazzjoni ta’ min sejjaħlek.

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

Kaskata ta’ Pjanijiet ta’ Riżerva

Ir-riprovament ma jsolvix kollox: xi kultant dokument ikun wisq atipiku għall-iskema. Minflok ma tfalli għal kollox, iddegrada b’mod gradwali. L-ewwel tentattiv juża Usciti Strutturati Personalizzati, l-għażla l-aktar affidabbli. Jekk dan ifalli, mur għall-Modalità JSON, li hija aktar permissiva, imbagħad għaddi l-output permezz ta’ model_validate()—dan iżomm ir-restrizzjonijiet tal-iskema mingħajr ma tiddependi fuq il-mudell biex jiġġenerahom perfettament. Bħala l-aħħar riżorsa, il-funzjoni tirritorna None, u tħalli lil min sejjaħlek jiddeċiedi bejn il-queue manwali jew l-abbandun.

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

Waqqaf il-Fluss fil-Ħin

F’pipeline b’frekwenza għolja, interruzzjoni tal-API ssir amplifikatur tar-riprovament: kull dokument ifalli tliet darbiet, il-kont tiegħek jittriplika, u l-latency tiżdied b’mod qawwi. “Circuit breaker” jimmonitorja l-fallimenti fuq tieqa li tiċċaqlaq u jimblokaw is-sejħiet ladarba jinqabeż limitu—ħames fallimenti f’sittin sekonda fil-konfigurazzjoni murija hawnhekk. Suċċess jagħlaq iċ-ċirkwit u jħassar il-kontatur.

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

Agħmilha Viżibbli

Dan il-makkinarju kollu jibqa’ għami mingħajr traċċi. Irreġistra kull sejħa bid-durata tagħha u l-iskema involuta, kemm jekk tirnexxi kif ukoll jekk tfalli. Din id-data tippermettilek aktar tard tiddetermina jekk id-degradazzjoni ġejx minn problema fil-mudell, tip ta’ dokument, jew bidla fil-prompt.

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

Punti Ewlenin

  • Il-validazzjoni strutturali (tipi) hija awtomatika; il-validazzjoni semantika (loġika) hija r-responsabbiltà tiegħek
  • Ir-riprovament b’ritorn ta’ informazzjoni huwa l-aktar mudell effettiv: ibgħat l-iżball lura lill-mudell
  • Implimenta kaskata ta’ riżerva: Personalizzat > Modalità JSON > valur default
  • F’produzzjoni b’frekwenza għolja, uża “circuit breaker” biex tipprevjeni kaskati ta’ żbalji
  • Irreġistra kull sejħa għall-monitoraġġ u d-dijanjostika