Guardrails AI: Validación de Salida Estructurada con JSON Schema

Guardrails AI es una biblioteca de Python de código abierto diseñada para hacer las salidas de los LLM fiables y predecibles. Envuelve cualquier llamada a la API de un LLM — OpenAI, Anthropic, Cohere, modelos locales — con un pipeline de validación que comprueba la respuesta del modelo contra un esquema definido por el usuario y un conjunto de validadores a nivel de campo antes de devolver el resultado a tu código de aplicación.

La abstracción central es el objeto `Guard`. Construyes un Guard a partir de un modelo de Pydantic o de una definición JSON Schema, opcionalmente adjuntas validadores a campos individuales, y luego llamas al Guard en lugar de llamar al LLM directamente. El Guard se encarga de la construcción del prompt, el parseo de la respuesta, la validación y la repetición automática del prompt cuando la validación falla, todo en un único pipeline auditable.

Dónde encaja Guardrails AI en la pila de LLM

Guardrails se sitúa entre tu código de aplicación y el proveedor del LLM. No reemplaza el modelo ni cambia cómo se llama al modelo: añade una capa de cumplimiento de contratos alrededor de la llamada. Piensa en él como un validador de esquemas para respuestas de API, salvo que la "API" es un modelo de lenguaje que produce lenguaje natural y la "respuesta" necesita parsearse a datos estructurados antes de poder validarse.

• Guard: La interfaz principal — envuelve una llamada al LLM y aplica esquema + validadores.
• ValidationOutcome: El objeto de resultado devuelto por una llamada al Guard — contiene la salida validada, el estado de aprobación/fallo y los errores de campo.
• Validator: Un callable adjunto a un campo del esquema que aplica una regla específica (tipo, rango, regex, comprobación externa).
• reask: El mecanismo de reintento — cuando la validación falla, Guardrails vuelve a prompting al modelo con el contexto del error.
• Hub: El registro de validadores de Guardrails — una colección curada de validadores de la comunidad instalables mediante `guardrails hub install`.

El problema fundamental es que los modelos de lenguaje se entrenan para producir texto plausible, no para respetar contratos programáticos. Incluso cuando le indicas a un modelo que devuelva JSON, puede producir salida con campos faltantes, tipos de valor incorrectos, campos extra que tu código posterior no espera, valores alucinados fuera de los rangos permitidos, o fragmentos de texto alrededor del bloque JSON que rompen el parseo por completo.

Los cinco modos de fallo de la salida de LLM sin validar

• Fallo de parseo: El modelo envuelve el JSON en vallas de código markdown, añade comentarios antes o después, o produce JSON malformado que no puede parsearse.
• Campos requeridos faltantes: El modelo omite un campo que se le pidió rellenar, provocando un KeyError o un error de referencia nula en el código posterior.
• Violaciones de tipo: Un campo que se esperaba numérico llega como cadena, o un booleano llega como la cadena "true" en lugar del literal `true`.
• Violaciones de restricciones de valor: Un campo de calificación devuelve 11 cuando el rango permitido es 1-10, o un campo enum devuelve un valor fuera de la lista definida.
• Estructura alucinada: El modelo inventa campos adicionales o anida objetos de forma distinta a como especifica el esquema.

Cualquiera de estos fallos puede corromper silenciosamente datos posteriores, provocar excepciones en tiempo de ejecución o dejar que valores incorrectos se propaguen a la lógica de negocio. Para prototipos de bajo riesgo, el parseo optimista es aceptable. Para pipelines de producción — extracción de facturas, parseo de datos clínicos, señales de detección de fraude, enriquecimiento de registros de clientes — cada violación de campo es un problema de calidad de datos que hay que detectar y gestionar.

El contrato entre tu aplicación y el LLM es tan fuerte como la validación que apliques a cada respuesta. Esperar no es una estrategia de validación.

JSON Schema es el lenguaje que Guardrails AI usa para describir el aspecto de una respuesta LLM válida. Una definición JSON Schema especifica la estructura esperada del objeto: qué campos existen, sus tipos, cuáles son obligatorios y qué restricciones aplican a sus valores. Este esquema cumple dos propósitos: indica a Guardrails cómo validar la respuesta parseada, y Guardrails lo usa para construir la instrucción de prompt que le dice al modelo qué forma producir.

Qué cubre JSON Schema para la validación de LLM

Para los casos de uso de salida estructurada, las palabras clave de JSON Schema más útiles son la aplicación de tipos, las listas de campos requeridos, los valores enum, los formatos de cadena y los rangos numéricos. Juntas cubren la mayoría de las reglas a nivel de campo que una tarea de extracción o generación necesita aplicar.

{
  "$schema": "https://json-schema.org/draft-07/schema",
  "type": "object",
  "required": ["product_name", "rating", "sentiment", "summary"],
  "additionalProperties": false,
  "properties": {
    "product_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "rating": {
      "type": "integer",
      "minimum": 1,
      "maximum": 5
    },
    "sentiment": {
      "type": "string",
      "enum": ["positive", "neutral", "negative"]
    },
    "summary": {
      "type": "string",
      "minLength": 20,
      "maxLength": 500
    },
    "pros": {
      "type": "array",
      "items": { "type": "string" },
      "maxItems": 5
    },
    "cons": {
      "type": "array",
      "items": { "type": "string" },
      "maxItems": 5
    }
  }
}

Este esquema le dice a Guardrails que rechace cualquier respuesta donde `rating` esté fuera de 1-5, `sentiment` no sea uno de los tres valores permitidos, o `summary` tenga menos de 20 caracteres. Los campos listados en `required` deben estar presentes. `additionalProperties: false` rechaza cualquier campo extra que el modelo añada por su cuenta.

Generar un esquema a partir de una respuesta de ejemplo

Al diseñar una nueva tarea de extracción, obtener el esquema inicial correcto lleva tiempo. Un atajo práctico: ejecuta tu prompt una vez sin validación, examina el JSON crudo que devuelve el modelo y luego usa el Generador de JSON Schema para inferir automáticamente un esquema Draft-07 a partir de esa muestra. El esquema generado captura tipos, campos requeridos y estructura anidada. Después lo refinas: ajustando longitudes de cadena, añadiendo restricciones enum, fijando límites numéricos, en lugar de escribir cada palabra clave desde cero.

Entender el pipeline de validación te ayuda a depurar fallos y configurar la estrategia de respuesta correcta para cada campo. El pipeline se ejecuta en un orden fijo en cada llamada al Guard: inyección de prompt, parseo de respuesta, validación JSON Schema, ejecución de validadores a nivel de campo y ensamblado del resultado.

Guardrails AI admite dos estilos de definición de esquemas: el formato heredado Rail spec y el enfoque moderno de modelos Pydantic. Conocer ambos es útil porque encontrarás Rail specs en bases de código antiguas y ejemplos de la comunidad, mientras que Pydantic es el camino recomendado para todos los proyectos nuevos desde Guardrails v0.4+.

Modelos Pydantic como esquemas de Guard

La forma más limpia de definir un esquema de salida de Guardrails en Python es una subclase de `BaseModel` de Pydantic. Los modelos de Pydantic tienen exportación nativa a JSON Schema, comprobación de tipos en el IDE y una sintaxis de Python familiar. Adjuntas validadores de Guardrails usando `Field()` de Pydantic con metadatos personalizados, o importando clases de validadores directamente desde `guardrails`.

from pydantic import BaseModel, Field
from guardrails import Guard
from guardrails.hub import ValidRange, ValidChoices

class ProductReview(BaseModel):
    product_name: str = Field(description="Name of the product reviewed")
    rating: int = Field(
        description="Rating from 1 to 5",
        validators=[ValidRange(min=1, max=5, on_fail="reask")]
    )
    sentiment: str = Field(
        description="Overall sentiment of the review",
        validators=[ValidChoices(
            choices=["positive", "neutral", "negative"],
            on_fail="reask"
        )]
    )
    summary: str = Field(description="One paragraph summary of the review")

# Build the Guard from the Pydantic model
guard = Guard.from_pydantic(ProductReview)

# Call the LLM through the Guard
outcome = guard(
    openai.chat.completions.create,
    model="gpt-4o",
    messages=[{"role": "user", "content": f"Extract a review from: {raw_text}"}],
    num_reasks=2,
)

if outcome.validation_passed:
    review: ProductReview = outcome.validated_output
else:
    print(outcome.error)

El pipeline de Pydantic a JSON Schema

Bajo el capó, Guardrails llama a `model.model_json_schema()` para exportar tu modelo Pydantic como JSON Schema, y luego usa ese esquema tanto para la inyección de prompt como para la validación de la respuesta. Esto significa que cada modelo Pydantic que puedas escribir es automáticamente un contrato de Guardrails válido. Puedes inspeccionar el esquema generado tú mismo: pega una respuesta de muestra en el Generador de JSON Schema para ver el esquema equivalente y compáralo con la salida de tu modelo Pydantic.

Si tu aplicación está en TypeScript pero llama a un servicio Guardrails de Python, el Convertidor de JSON a Zod Schema genera un esquema Zod equivalente a partir del mismo JSON de muestra — útil para validar el mismo contrato en el lado del cliente sin duplicar manualmente la definición del esquema.

Rail specs: el formato heredado

Las Rail specs son archivos XML donde cada elemento `<output>` describe un campo con un atributo `type` y uno o más elementos hijo `<validator>`. Anteceden a la integración con Pydantic y son menos ergonómicos para desarrolladores Python, pero siguen completamente soportados. Si heredas una base de código Guardrails que usa archivos `.rail`, puedes migrar cada especificación a un modelo Pydantic de forma incremental: el comportamiento de validación es equivalente.

Un flujo de trabajo de Guardrails fiable combina diseño de esquemas sin conexión, pruebas locales y monitoreo en producción. La fase de diseño del esquema — donde defines el aspecto de una salida válida — es el paso más importante y el que más se beneficia de herramientas dedicadas.

Paso 1: Diseña el esquema sin conexión

Antes de escribir cualquier código de Guardrails, define tu esquema de salida como un documento JSON Schema independiente. Trabajar primero en JSON Schema te permite iterar sobre el contrato de forma independiente a la llamada al LLM: puedes validar payloads de muestra, ajustar restricciones y confirmar que el esquema es correcto antes de gastar créditos de API en pruebas.

El Validador de JSON Schema de Aback Tools permite pegar un JSON Schema y un payload candidato, y ver inmediatamente los errores de validación a nivel de campo. Úsalo para confirmar que tus arrays `required`, listas enum y rangos numéricos se comportan como esperas antes de traducir el esquema a un modelo Pydantic. El Formateador y Validador JSON es útil para comprobar que tu propio archivo de esquema es JSON sintácticamente válido antes de referenciarlo.

Paso 2: Genera Pydantic desde JSON

Si has recogido respuestas LLM de muestra durante el prototipado, el Convertidor de JSON a Dataclass / Pydantic de Python genera un modelo Pydantic a partir de un payload JSON de muestra en un paso. La herramienta infiere los tipos de campo, maneja objetos anidados y aplica `Optional` donde los campos pueden ausentarse. Usa la salida como punto de partida y añade validadores de Guardrails a cada campo según las restricciones de tu JSON Schema.

Paso 3: Prueba localmente con respuestas simuladas

Los Guards de Guardrails pueden llamarse con cualquier callable de Python, no solo con APIs de LLM en vivo. Durante el desarrollo, pasa una función simulada que devuelva una respuesta de cadena fija para probar el pipeline de validación sin llamadas a la API. Esto hace que iterar sobre cambios de esquema, configuraciones de validadores y prompts de reask sea rápido y gratuito antes de conectarte a un endpoint de modelo de pago.

Flujo de esquemas recomendado con Aback Tools

• Generador de JSON Schema - infiere un esquema inicial a partir de una respuesta LLM de muestra.
• Validador de JSON Schema - valida payloads candidatos contra tu esquema sin conexión.
• Formateador y Validador JSON - comprueba que los archivos de esquema son JSON válido antes de usarlos.
• JSON a Dataclass de Python - genera un modelo Pydantic a partir de un payload de muestra.
• JSON a Zod Schema - genera un contrato para TypeScript para la validación en el cliente.

Guardrails AI mejora significativamente la fiabilidad de la salida estructurada, pero no es una garantía de corrección. Entender las limitaciones te ayuda a diseñar tu pipeline con respaldos apropiados en lugar de confiar incondicionalmente en el Guard.

Los bucles de reask no siempre convergen

Cuando un modelo falla consistentemente un validador específico, añadir más reintentos reask no ayuda: solo cuesta más créditos de API por el mismo resultado. Algunos modos de fallo son sistemáticos: el modelo genuinamente no entiende una restricción, o la restricción es demasiado estricta para que el modelo la satisfaga de forma fiable dado el input. Audita tus tasas de fallo de validadores y trata los validadores con alta tasa de fallo como señales para revisar la definición de la restricción o el prompt.

JSON Schema no captura errores semánticos

Un esquema puede confirmar que `sentiment` es uno de `["positive", "neutral", "negative"]`, pero no puede verificar que el sentimiento asignado sea realmente correcto para el texto de entrada. JSON Schema y los validadores aplican contratos estructurales y sintácticos: no pueden reemplazar la revisión humana ni las comprobaciones de calidad posteriores para la exactitud del contenido. Usa Guardrails para aplicar el formato y la estructura de la salida, y aplica métricas de evaluación separadas para la corrección del contenido.

Sobrecarga de latencia y coste

Cada intento de reask es una llamada adicional a la API del LLM a coste completo de tokens. Para un Guard configurado con `num_reasks=3`, una extracción en el peor caso puede disparar cuatro llamadas al LLM antes de fallar. En pipelines de alto rendimiento, esta sobrecarga es significativa. Perfila la tasa de reask de tu Guard en staging antes de desplegar a producción, y establece `num_reasks=0` para campos no críticos donde las acciones on_fail `filter` o `noop` son alternativas aceptables al reintento.