Stratégies de validation et de nouvelle tentative
Šiame puslapyje
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 entre les 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 croisées, 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 erronée 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 fais passer la sortie через 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 un 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) # Tenter la 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’un changement 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
Svarbiausi punktai
- 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