Estrategias de validación y reintento
En esta página
Validación: la última línea de defensa antes de producción
Incluso con Salidas Estructuradas Personalizadas, la validación sigue siendo esencial. El esquema garantiza la estructura, no la coherencia semántica. Un campo price podría contener -999.0: un float válido que encaja perfectamente con el esquema, pero que carece de sentido para un precio.
La distinción es clara. Pydantic y Zod gestionan automáticamente la validación estructural: campos obligatorios, tipos de campo, restricciones de enumeración y estructuras anidadas. No necesitas escribir código para esto. La validación semántica, sin embargo, es enteramente tu responsabilidad. Esto incluye límites numéricos (un precio mayor que cero, una puntuación entre 0 y 1), consistencia entre campos (el total debe igualar la suma de las líneas), formatos de cadena (un correo electrónico genuinamente válido, una fecha correctamente formateada) y lógica de negocio (una fecha de vencimiento posterior a la fecha de la factura).
Incrustar reglas de negocio en el esquema
Pydantic te permite incrustar estas comprobaciones directamente en el modelo, haciendo que sean inseparables de la estructura. @field_validator gestiona campos individuales; por ejemplo, asegurar que una cantidad sea positiva o que un precio unitario no sea negativo. @model_validator(mode="after") se ejecuta una vez poblados todos los campos, lo que permite comprobaciones cruzadas, como verificar que el total declarado coincide con cantidad × precio unitario dentro de un céntimo.
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 expresa la misma lógica utilizando restricciones integradas como .positive() y .nonnegative() para los campos, y .refine() para reglas entre objetos aplicadas al objeto completo.
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" }
);
Reintento con retroalimentación
Cuando la validación falla, el patrón más eficaz es devolver el error al modelo para que pueda corregirse. La siguiente función encadena tres comprobaciones en orden de importancia: respuesta completa, objeto no nulo y cumplimiento de las reglas de negocio. En caso de fallo, añade la respuesta errónea y el mensaje de error a la conversación, proporcionando al siguiente intento un contexto de diagnóstico preciso. Observa la copia de la lista de mensajes al inicio de la función; sin ella, contaminarías el historial de conversación del llamador.
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"
):
"""Extracción con reintento y retroalimentación de errores estructurada."""
conversation = list(messages) # Copia para evitar modificar el original
for attempt in range(max_retries):
try:
response = client.chat.parse(
model=model,
messages=conversation,
response_format=schema,
temperature=0,
max_tokens=2048
)
# Comprobar que la respuesta está completa
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")
# Validación semántica adicional
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:
# Añadir retroalimentación al contexto
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}"
)
Una cascada de planes de respaldo
El reintento no lo soluciona todo: a veces un documento es demasiado atípico para el esquema. En lugar de fallar abruptamente, degrada el servicio de forma controlada. El primer intento utiliza Salidas Estructuradas Personalizadas, la opción más fiable. Si eso falla, recurre al Modo JSON, que es más permisivo, y luego pasa la salida por model_validate(); esto mantiene las restricciones del esquema sin depender de que el modelo las genere perfectamente. Como último recurso, la función devuelve None, dejando que el llamador decida entre ponerlo en cola manual o abandonarlo.
def extract_with_fallback(client, text, schema, system_prompt):
"""Extracción con cascada de respaldo."""
# Intento 1: Salida Estructurada Personalizada (óptimo)
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")
# Intento 2: Modo JSON (más 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) # Intentar validación con Pydantic
except Exception:
print("JSON Mode failed, falling back to manual extraction")
# Intento 3: Devolver objeto parcial o error
return None
Corta el grifo a tiempo
En una canalización de alta frecuencia, una caída de la API convierte el reintento en un amplificador: cada documento falla tres veces, tu factura se triplica y la latencia se dispara. Un disyuntor («circuit breaker») monitoriza los fallos en una ventana deslizante y bloquea las llamadas una vez superado un umbral; cinco fallos en sesenta segundos en la configuración mostrada aquí. Un éxito cierra el circuito y limpia el contador.
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)
# Limpiar errores fuera de la ventana
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
# Comprobar si ha pasado la ventana
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
# Uso
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
Hazlo visible
Toda esta maquinaria permanece ciega sin trazas. Registra cada llamada con su duración y el esquema implicado, tanto si tiene éxito como si falla. Estos datos te permiten determinar posteriormente si la degradación proviene de un problema del modelo, de un tipo de documento o de un cambio en el 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
Puntos clave
- La validación estructural (tipos) es automática; la validación semántica (lógica) es tu responsabilidad
- El reintento con retroalimentación es el patrón más eficaz: devuelve el error al modelo
- Implementa una cascada de respaldo: Personalizado > Modo JSON > valor por defecto
- En producción de alta frecuencia, utiliza un disyuntor para evitar cascadas de errores
- Registra cada llamada para monitorización y diagnóstico