Ir al contenido principal
Español— Elegir un idioma
Menú

Estrategias de validación y reintento

Lección 11 de 12 Actualizado el 2 de noviembre de 2026 Desarrollador
En esta página
  1. Validación: la última línea de defensa antes de producción
  2. Incrustar reglas de negocio en el esquema
  3. Reintento con retroalimentación
  4. Una cascada de planes de respaldo
  5. Corta el grifo a tiempo
  6. Hazlo visible
  7. Puntos clave

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