Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Validatie- en retry-strategieën

Les 11 van 12 Bijgewerkt op 2 november 2026 Ontwikkelaar
Op deze pagina
  1. Validatie: de laatste verdedigingslinie voordat u naar productie gaat
  2. Bedrijfsregels inbedden in het schema
  3. Retry met feedback
  4. Een cascade van fallback-plannen
  5. Sluit de kraan op tijd
  6. Maak het zichtbaar
  7. Belangrijkste punten

Validatie: de laatste verdedigingslinie voordat u naar productie gaat

Zelfs met Custom Structured Outputs blijft validatie essentieel. Het schema garandeert de structuur, niet de semantische coherentie. Een veld price kan bijvoorbeeld -999.0 bevatten: een geldige float die perfect overeenkomt met het schema, maar die geen enkele zin heeft als prijs.

Het onderscheid is duidelijk. Pydantic en Zod behandelen structurele validatie automatisch: verplichte velden, veldtypen, enum-beperkingen en geneste structuren. U hoeft hiervoor geen code te schrijven. Semantische validatie is echter volledig uw verantwoordelijkheid. Dit omvat numerieke grenswaarden (een prijs groter dan nul, een score tussen 0 en 1), consistentie tussen velden (het totaal moet gelijk zijn aan de som van de regelitems), string-formaten (een echt geldig e-mailadres, een correct opgemaakte datum) en bedrijfslogica (een vervaldatum die later ligt dan de factuurdatum).

Bedrijfsregels inbedden in het schema

Met Pydantic kunt u deze controles direct in het model inbedden, waardoor ze onlosmakelijk verbonden zijn met de structuur. @field_validator handelt individuele velden af—bijvoorbeeld om ervoor te zorgen dat een hoeveelheid positief is of een eenheidsprijs niet negatief. @model_validator(mode="after") wordt uitgevoerd zodra alle velden zijn ingevuld, waardoor controles tussen velden mogelijk zijn, zoals het verifiëren dat het opgegeven totaal binnen één cent overeenkomt met hoeveelheid × eenheidsprijs.

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 drukt dezelfde logica uit met ingebouwde beperkingen zoals .positive() en .nonnegative() voor velden, en .refine() voor regels die objecten overschrijden en worden toegepast op het volledige object.

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

Retry met feedback

Wanneer validatie mislukt, is het meest effectieve patroon om de fout terug te sturen naar het model, zodat het zichzelf kan corrigeren. De onderstaande functie ketent drie controles aan elkaar in volgorde van belang: volledige respons, niet-null object en naleving van bedrijfsregels. Bij falen voegt deze de foutieve respons en het foutbericht toe aan het gesprek, waardoor de volgende poging een precieze diagnostische context heeft. Let op de kopie van de berichtenlijst aan het begin van de functie; zonder deze zou u de gespreksgeschiedenis van de aanroeper vervuilen.

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

Een cascade van fallback-plannen

Retry lost niet alles op: soms is een document te atypisch voor het schema. In plaats van abrupt te falen, degradeert u geleidelijk. De eerste poging gebruikt Custom Structured Outputs, de meest betrouwbare optie. Als dat mislukt, valt u terug op JSON Mode, dat soepeler is, en voert u de output door model_validate()—dit behoudt schemabeperkingen zonder te vertrouwen op het model om ze perfect te genereren. Als laatste redmiddel geeft de functie None terug, waardoor de aanroeper kan beslissen tussen handmatige wachtrijplaatsing of afbreken.

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

Sluit de kraan op tijd

In een pipeline met hoge frequentie verandert een API-storing retry in een versterker: elk document faalt drie keer, uw factuur verdrievoudigt en de latentie piekt. Een circuit breaker bewaakt fouten over een glijdend venster en blokkeert oproepen zodra een drempelwaarde wordt overschreden—vijf fouten in zestig seconden in de hier getoonde configuratie. Een succes sluit het circuit en wist de teller.

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

Maak het zichtbaar

Al deze mechanismen blijven blind zonder traces. Log elke oproep met de duur en het betrokken schema, ongeacht of deze slaagt of faalt. Met deze gegevens kunt u later bepalen of degradatie voortkomt uit een modelprobleem, een documenttype of een wijziging in de 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

Belangrijkste punten

  • Structurele validatie (typen) is automatisch; semantische validatie (logica) is uw verantwoordelijkheid
  • Retry met feedback is het meest effectieve patroon: stuur de fout terug naar het model
  • Implementeer een fallback-cascade: Custom > JSON Mode > standaardwaarde
  • Gebruik in productieomgevingen met hoge frequentie een circuit breaker om foutcascades te voorkomen
  • Log elke oproep voor monitoring en diagnostiek