Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Stratégie de validation et de nouvelle tentative

Lekcia 11 z 12 Aktualizované 2. novembra 2026 Vývojár
Na tejto strane
  1. Validation : la dernière ligne de défense avant la mise en production
  2. Intégrer les règles métier dans le schéma
  3. Nouvelle tentative avec rétroaction
  4. Une cascade de plans de repli
  5. Couper le robinet à temps
  6. Rendre cela visible
  7. Kľúčové poznatky

Validation : la dernière ligne de défense avant la mise en production

Même avec des sorties structurées personnalisées, la validation reste essentielle. Le schéma garantit la structure, pas la cohérence sémantique. Un champ price peut contenir -999.0 : un nombre à virgule flottante valide qui correspond parfaitement au schéma, mais qui n’a aucun sens pour un prix.

La distinction est claire. Pydantic et Zod gèrent automatiquement la validation structurelle : champs obligatoires, types de champs, contraintes d’énumération et structures imbriquées. Tu n’as besoin d’écrire aucun code pour cela. La validation sémantique, en revanche, t’incombe entièrement. Cela inclut les bornes numériques (un prix supérieur à zéro, un score entre 0 et 1), la cohérence inter-champs (le total doit égaler la somme des lignes), les formats de chaîne (un e-mail réellement valide, une date correctement formatée) et la logique métier (une date d’échéance postérieure à la date de facture).

Intégrer les règles métier dans le schéma

Pydantic te permet d’intégrer ces vérifications directement dans le modèle, les rendant indissociables de la structure. @field_validator gère les champs individuels — par exemple, s’assurer qu’une quantité est positive ou qu’un prix unitaire n’est pas négatif. @model_validator(mode="after") s’exécute une fois tous les champs remplis, permettant des vérifications inter-champs, comme vérifier que le total déclaré correspond à la quantité × le prix unitaire à un centime près.

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 exprime la même logique en utilisant des contraintes intégrées comme .positive() et .nonnegative() pour les champs, et .refine() pour les règles inter-objets appliquées à l’objet complet.

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

Nouvelle tentative avec rétroaction

Lorsque la validation échoue, le modèle le plus efficace consiste à renvoyer l’erreur au modèle pour qu’il puisse se corriger lui-même. La fonction ci-dessous enchaîne trois vérifications par ordre d’importance : réponse complète, objet non nul et conformité aux règles métier. En cas d’échec, elle ajoute la réponse défectueuse et le message d’erreur à la conversation, fournissant au prochain essai un contexte de diagnostic précis. Note la copie de la liste des messages au début de la fonction — sans elle, tu polluerais l’historique de conversation de l’appelant.

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 avec nouvelle tentative et rétroaction d'erreur structurée."""
    conversation = list(messages)  # Copie pour éviter de modifier l'original

    for attempt in range(max_retries):
        try:
            response = client.chat.parse(
                model=model,
                messages=conversation,
                response_format=schema,
                temperature=0,
                max_tokens=2048
            )

            # Vérifier que la réponse est complète
            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")

            # Validation sémantique supplémentaire
            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:
                # Ajouter la rétroaction au contexte
                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}"
                )

Une cascade de plans de repli

La nouvelle tentative ne résout pas tout : parfois, un document est trop atypique pour le schéma. Au lieu d’échouer brutalement, dégrade-toi gracieusement. La première tentative utilise les sorties structurées personnalisées, l’option la plus fiable. Si cela échoue, bascule vers le mode JSON, plus permissif, puis passe la sortie via model_validate() — cela conserve les contraintes du schéma sans compter sur le modèle pour les générer parfaitement. En dernier recours, la fonction renvoie None, laissant l’appelant décider entre une mise en file d’attente manuelle ou l’abandon.

def extract_with_fallback(client, text, schema, system_prompt):
    """Extraction avec cascade de repli."""

    # Tentative 1 : Sortie structurée personnalisée (meilleur)
    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")

    # Tentative 2 : Mode JSON (plus 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)  # Tentative de validation Pydantic
    except Exception:
        print("JSON Mode failed, falling back to manual extraction")

    # Tentative 3 : Renvoyer un objet partiel ou une erreur
    return None

Couper le robinet à temps

Dans un pipeline à haute fréquence, une panne d’API transforme la nouvelle tentative en amplificateur : chaque document échoue trois fois, ta facture triple et la latence explose. Un disjoncteur surveille les échecs sur une fenêtre glissante et bloque les appels une fois un seuil franchi — cinq échecs en soixante secondes dans la configuration montrée ici. Un succès ferme le circuit et réinitialise le compteur.

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)
        # Nettoyer les erreurs en dehors de la fenêtre
        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
        # Vérifier si la fenêtre est passée
        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

# Utilisation
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

Rendre cela visible

Toute cette machinerie reste aveugle sans traces. Journalise chaque appel avec sa durée et le schéma impliqué, qu’il réussisse ou échoue. Ces données te permettent ensuite de déterminer si la dégradation provient d’un problème de modèle, d’un type de document ou d’une modification du 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

Kľúčové poznatky

  • La validation structurelle (types) est automatique ; la validation sémantique (logique) est ta responsabilité
  • La nouvelle tentative avec rétroaction est le modèle le plus efficace : renvoie l’erreur au modèle
  • Implémente une cascade de repli : Personnalisé > Mode JSON > valeur par défaut
  • En production à haute fréquence, utilise un disjoncteur pour empêcher les cascades d’erreurs
  • Journalise chaque appel pour la surveillance et le diagnostic