Guardrails AI : Validation de Sortie Structurée avec JSON Schema

Guardrails AI est une bibliothèque Python open source conçue pour rendre les sorties LLM fiables et prévisibles. Elle enveloppe tout appel d'API LLM - OpenAI, Anthropic, Cohere, modèles locaux - d'un pipeline de validation qui vérifie la réponse du modèle par rapport à un schéma défini par l'utilisateur et un ensemble de validateurs au niveau des champs avant de renvoyer le résultat à votre code applicatif.

L'abstraction centrale est l'objet `Guard`. Vous construisez un Guard à partir d'un modèle Pydantic ou d'une définition JSON Schema, attachez éventuellement des validateurs à des champs individuels, puis appelez le Guard au lieu d'appeler le LLM directement. Le Guard gère la construction du prompt, l'analyse de la réponse, la validation et la relance automatique du prompt en cas d'échec de validation - le tout dans un pipeline unique et auditable.

Où Guardrails AI se situe dans la pile LLM

Guardrails se place entre votre code applicatif et le fournisseur LLM. Il ne remplace pas le modèle et ne change pas la façon dont le modèle est appelé - il ajoute une couche d'application de contrat autour de l'appel. Considérez-le comme un validateur de schéma pour réponses d'API, sauf que « l'API » est un modèle de langage produisant du langage naturel, et que la « réponse » doit être analysée en données structurées avant de pouvoir être validée.

• Guard : l'interface principale - enveloppe un appel LLM et applique schéma + validateurs.
• ValidationOutcome : l'objet résultat renvoyé par un appel Guard - contient la sortie validée, le statut succès/échec et les erreurs de champs.
• Validator : un appelable attaché à un champ de schéma qui applique une règle spécifique (type, plage, regex, vérification externe).
• reask : le mécanisme de relance - quand la validation échoue, Guardrails relance le prompt du modèle avec le contexte d'erreur.
• Hub : le registre de validateurs Guardrails - une collection organisée de validateurs communautaires installables via `guardrails hub install`.

Le problème fondamental est que les modèles de langage sont entraînés à produire du texte plausible - pas à respecter des contrats programmatiques. Même quand vous demandez à un modèle de renvoyer du JSON, il peut produire une sortie avec des champs manquants, des types de valeurs erronés, des champs supplémentaires que votre code aval ne prévoit pas, des valeurs hallucinées hors des plages autorisées, ou des fragments de texte autour du bloc JSON qui cassent totalement l'analyse.

Les cinq modes de défaillance d'une sortie LLM non validée

• Échec d'analyse : le modèle enveloppe le JSON dans des délimiteurs de code markdown, ajoute des commentaires avant ou après, ou produit un JSON malformé impossible à analyser.
• Champs requis manquants : le modèle omet un champ qu'on lui a demandé de renseigner, provoquant un KeyError ou une erreur de référence nulle dans le code aval.
• Violations de type : un champ attendu comme nombre arrive sous forme de chaîne, ou un booléen arrive comme la chaîne « true » plutôt que le littéral `true`.
• Violations de contraintes de valeur : un champ de note renvoie 11 alors que la plage autorisée est 1-10, ou un champ enum renvoie une valeur hors de la liste définie.
• Structure hallucinée : le modèle invente des champs supplémentaires ou imbrique les objets différemment de ce que le schéma spécifie.

N'importe laquelle de ces défaillances peut corrompre silencieusement les données aval, provoquer des exceptions à l'exécution ou laisser de mauvaises valeurs se propager dans la logique métier. Pour des prototypes à faible enjeu, l'analyse optimiste est acceptable. Pour les pipelines de production - extraction de factures, analyse de données cliniques, signaux de détection de fraude, enrichissement de fiches clients - chaque violation de champ est un problème de qualité de données à détecter et traiter.

Le contrat entre votre application et le LLM n'est pas plus fort que la validation que vous appliquez à chaque réponse. Espérer n'est pas une stratégie de validation.

JSON Schema est le langage utilisé par Guardrails AI pour décrire à quoi ressemble une réponse LLM valide. Une définition JSON Schema spécifie la structure d'objet attendue - quels champs existent, leurs types, lesquels sont requis, et quelles contraintes s'appliquent à leurs valeurs. Ce schéma remplit deux rôles : il indique à Guardrails comment valider la réponse analysée, et Guardrails l'utilise pour construire l'instruction de prompt qui dit au modèle quelle forme produire.

Ce que JSON Schema couvre pour la validation LLM

Pour les cas de sortie structurée, les mots-clés JSON Schema les plus utiles sont l'application des types, les listes de champs requis, les valeurs enum, les formats de chaînes et les plages numériques. Ensemble, ils couvrent la majorité des règles de champ qu'une tâche d'extraction ou de génération doit appliquer.

{
  "$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
    }
  }
}

Ce schéma ordonne à Guardrails de rejeter toute réponse où `rating` est hors de 1-5, où `sentiment` n'est pas l'une des trois valeurs autorisées, ou où `summary` fait moins de 20 caractères. Les champs listés dans `required` doivent être présents. `additionalProperties: false` rejette tout champ supplémentaire que le modèle ajouterait de lui-même.

Générer un schéma à partir d'une réponse d'exemple

Lors de la conception d'une nouvelle tâche d'extraction, obtenir le schéma initial correct demande du temps. Un raccourci pratique : exécutez votre prompt une fois sans validation, examinez le JSON brut renvoyé par le modèle, puis utilisez le Générateur de JSON Schema pour inférer automatiquement un schéma Draft-07 à partir de cet exemple. Le schéma généré capture les types, les champs requis et la structure imbriquée. Vous l'affinez ensuite - resserrage des longueurs de chaînes, ajout de contraintes enum, définition de bornes numériques - plutôt que d'écrire chaque mot-clé à partir de zéro.

Comprendre le pipeline de validation vous aide à déboguer les échecs et à configurer la bonne stratégie de réponse pour chaque champ. Le pipeline s'exécute dans un ordre fixe pour chaque appel Guard : injection de prompt, analyse de la réponse, validation JSON Schema, exécution des validateurs de champs et assemblage du résultat.

Guardrails AI prend en charge deux styles de définition de schémas : le format historique Rail spec et l'approche moderne des modèles Pydantic. Connaître les deux est utile car vous rencontrerez des Rail specs dans d'anciens codes et des exemples communautaires, tandis que Pydantic est la voie recommandée pour tout nouveau projet depuis Guardrails v0.4+.

Modèles Pydantic comme schémas Guard

La façon la plus propre de définir un schéma de sortie Guardrails en Python est une sous-classe `BaseModel` de Pydantic. Les modèles Pydantic offrent l'export JSON Schema natif, la vérification de types dans l'IDE et une syntaxe Python familière. Vous attachez les validateurs Guardrails via le `Field()` de Pydantic avec des métadonnées personnalisées, ou en important directement les classes de validateurs depuis `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)

Le pipeline Pydantic vers JSON Schema

Sous le capot, Guardrails appelle `model.model_json_schema()` pour exporter votre modèle Pydantic en JSON Schema, puis utilise ce schéma à la fois pour l'injection de prompt et la validation de la réponse. Cela signifie que tout modèle Pydantic que vous pouvez écrire est automatiquement un contrat Guardrails valide. Vous pouvez inspecter le schéma généré vous-même - collez une réponse d'exemple dans le Générateur de JSON Schema pour voir le schéma équivalent, puis comparez-le à la sortie de votre modèle Pydantic.

Si votre application est en TypeScript mais appelle un service Guardrails Python, le Convertisseur JSON vers Zod Schema génère un schéma Zod correspondant à partir du même JSON d'exemple - utile pour valider le même contrat côté client sans dupliquer manuellement la définition du schéma.

Rail specs - le format historique

Les Rail specs sont des fichiers XML où chaque élément `<output>` décrit un champ avec un attribut `type` et un ou plusieurs éléments enfants `<validator>`. Ils précèdent l'intégration Pydantic et sont moins ergonomiques pour les développeurs Python, mais restent entièrement pris en charge. Si vous héritez d'un code Guardrails utilisant des fichiers `.rail`, vous pouvez migrer chaque spécification vers un modèle Pydantic de façon incrémentale - le comportement de validation est équivalent.

Un flux de travail Guardrails fiable combine conception de schéma hors ligne, tests locaux et supervision en production. La phase de conception du schéma - où vous définissez à quoi ressemble une sortie valide - est l'étape la plus importante et bénéficie le plus d'un outillage dédié.

Étape 1 : Concevoir le schéma hors ligne

Avant d'écrire du code Guardrails, définissez votre schéma de sortie comme un document JSON Schema autonome. Travailler d'abord en JSON Schema permet d'itérer sur le contrat indépendamment de l'appel LLM - vous pouvez valider des payloads d'exemple, ajuster les contraintes et confirmer que le schéma est correct avant de dépenser des crédits d'API pour les tests.

Le Validateur de JSON Schema d'Aback Tools permet de coller un JSON Schema et un payload candidat, puis de voir immédiatement les erreurs de validation au niveau des champs. Utilisez-le pour confirmer que vos tableaux `required`, listes enum et plages numériques se comportent comme prévu avant de traduire le schéma en modèle Pydantic. Le Formateur & Validateur JSON est utile pour vérifier que votre fichier de schéma lui-même est un JSON syntaxiquement valide avant de le référencer.

Étape 2 : Générer Pydantic depuis JSON

Si vous avez collecté des réponses LLM d'exemple pendant le prototypage, le Convertisseur JSON vers Dataclass / Pydantic Python génère un modèle Pydantic à partir d'un payload JSON d'exemple en une étape. L'outil infère les types de champs, gère les objets imbriqués et applique `Optional` là où les champs peuvent être absents. Utilisez la sortie comme point de départ et ajoutez des validateurs Guardrails à chaque champ selon les contraintes de votre JSON Schema.

Étape 3 : Tester localement avec des réponses simulées

Les Guards Guardrails peuvent être appelés avec n'importe quel appelable Python, pas seulement des API LLM en direct. Pendant le développement, passez une fonction simulée renvoyant une réponse de chaîne fixe pour tester le pipeline de validation sans aucun appel d'API. Cela rend l'itération sur les modifications de schéma, les configurations de validateurs et les prompts reask rapide et gratuite avant de se connecter à un endpoint de modèle payant.

Flux de schémas recommandé avec Aback Tools

• Générateur de JSON Schema - infère un schéma de départ à partir d'une réponse LLM d'exemple.
• Validateur de JSON Schema - valide les payloads candidats contre votre schéma hors ligne.
• Formateur & Validateur JSON - vérifie que les fichiers de schéma sont un JSON valide avant usage.
• JSON vers Dataclass Python - génère un modèle Pydantic à partir d'un payload d'exemple.
• JSON vers Zod Schema - génère un contrat côté TypeScript pour la validation client.

Guardrails AI améliore sensiblement la fiabilité de la sortie structurée, mais ce n'est pas une garantie d'exactitude. Comprendre les limitations vous aide à concevoir votre pipeline avec des solutions de repli appropriées plutôt qu'à faire confiance au Guard sans condition.

Les boucles reask ne convergent pas toujours

Quand un modèle échoue de façon constante sur un validateur spécifique, ajouter davantage de relances reask n'aide pas - cela coûte simplement plus de crédits d'API pour le même résultat. Certains modes d'échec sont systématiques : le modèle ne comprend vraiment pas une contrainte, ou la contrainte est trop stricte pour être satisfaite de façon fiable avec l'entrée donnée. Auditez vos taux d'échec de validateurs et traitez les validateurs à fort taux d'échec comme des signaux pour revoir la définition de la contrainte ou le prompt.

JSON Schema ne capture pas les erreurs sémantiques

Un schéma peut confirmer que `sentiment` est l'un de `["positive", "neutral", "negative"]` mais ne peut pas vérifier que le sentiment attribué est réellement correct pour le texte d'entrée. JSON Schema et les validateurs appliquent des contrats structurels et syntaxiques - ils ne remplacent ni la revue humaine ni les contrôles qualité aval pour l'exactitude du contenu. Utilisez Guardrails pour imposer le format et la structure de la sortie, et appliquez des métriques d'évaluation séparées pour la justesse du contenu.

Surcoût de latence et de coût

Chaque tentative reask est un appel d'API LLM supplémentaire au coût plein en tokens. Pour un Guard configuré avec `num_reasks=3`, une extraction dans le pire des cas peut déclencher quatre appels LLM avant d'échouer. Dans les pipelines à haut débit, ce surcoût est significatif. Profilez le taux de reask de votre Guard en staging avant de déployer en production, et réglez `num_reasks=0` pour les champs non critiques où les actions on_fail `filter` ou `noop` sont des alternatives acceptables à la relance.