Guide

Guardrails AI : vérifier ce que le modèle a répondu

Guardrails AI vérifie les réponses d'un modèle de langage : validators, actions en cas d'échec, coût des relances, schémas Pydantic et mise en production.

L'équipe CodeWorlds13 min de lecture ·

Pratique Python dans des leçons interactives avec un éditeur de code.

Crée un compte gratuit→
Dans cet article10

Un modèle de langage répond par du texte, alors que votre application a besoin de quelque chose de précis : la bonne structure, aucune donnée personnelle, un contenu qui reste dans des limites acceptées. L'écart entre ces deux choses est l'endroit où naissent les problèmes.

Guardrails AI comble cet écart. C'est une bibliothèque qui enveloppe l'appel au modèle dans une couche vérifiant le résultat, avec la possibilité de le corriger ou de demander au modèle un nouvel essai.

Sa construction diffère des outils qui pilotent le déroulement d'une conversation, présentés dans l'article sur NeMo Guardrails. Là, vous aviez une couche intermédiaire qui menait un dialogue ; ici, vous avez une bibliothèque branchée sur un appel précis et centrée sur son résultat.

Guards et validators

Le concept de base est le guard, c'est-à-dire un ensemble de vérifications placé au-dessus d'un appel au modèle. Vous assemblez les vérifications à partir de briques prêtes à l'emploi ou vous écrivez les vôtres.

Python
from guardrails import Guard
from guardrails.hub import DetectPII, ToxicLanguage

guard = Guard().use(
    DetectPII(pii_entities=["EMAIL_ADDRESS", "PHONE_NUMBER"], on_fail="fix"),
    ToxicLanguage(threshold=0.8, on_fail="exception"),
)

result = guard(
    model.chat.completions.create,
    model="gpt-4o",
    messages=[{"role": "user", "content": question}],
)

Le catalogue de validators prêts à l'emploi couvre des choses qui demandent des semaines à implémenter soi-même : détection de données personnelles, mesure de la toxicité, correspondance de motifs, détection de mentions de concurrents, restriction du périmètre thématique et détection de tentatives de contournement des instructions.

La valeur de ce catalogue tient au fait que chaque validator est un paquet distinct, installé à la demande. Vous n'importez pas de modèles de détection de toxicité dans un projet qui ne vérifie que la structure des réponses.

La manière de les installer a changé en 2026, ce qu'il vaut mieux savoir avant de copier un ancien exemple. Les validators sont désormais des paquets ordinaires sur l'index public PyPI, nommés avec le préfixe guardrails-ai-, tandis que l'ancien registre privé piloté par sa propre commande, ainsi que les serveurs sur lesquels certains validators exécutaient leurs modèles à distance, ont été arrêtés le 6 août 2026. Les modèles tournent donc en local ou sur un endpoint que vous hébergez vous-même, et l'ancien chemin d'import est resté quelque temps sous forme de couche de compatibilité.

Notez cependant que les validators diffèrent par leur coût de plusieurs ordres de grandeur. Une vérification de motif est gratuite, tandis que la détection de données personnelles ou la mesure de toxicité fait tourner son propre modèle, ce qui ajoute du temps et des ressources.

Les actions en cas d'échec

C'est la partie la plus intéressante de la construction, et celle où les décisions délibérées paient, car le coût en découle.

La première option est d'ignorer et d'enregistrer le fait dans un journal. C'est utile pendant le déploiement, quand vous voulez voir à quelle fréquence une vérification se serait déclenchée avant qu'elle ne commence à bloquer quoi que ce soit.

La deuxième est de corriger de façon déterministe. Une adresse e-mail détectée est masquée, un texte trop long est tronqué. C'est peu coûteux et prévisible, à condition que la correction puisse se faire mécaniquement.

La troisième est de filtrer le fragment fautif en gardant le reste.

La quatrième est de refuser avec une réponse préparée à la place de ce que le modèle a dit.

La cinquième, la plus intéressante et la plus coûteuse, est de demander au modèle un nouvel essai avec une explication de ce qui n'allait pas. Le modèle reçoit sa propre réponse accompagnée du message du validator et en génère une nouvelle.

Cette dernière mérite un traitement à part, car son coût est sous-estimé.

Le coût de la relance

Le mécanisme de relance paraît élégant et a un prix qu'il faut calculer avant de l'activer largement.

En cas d'échec, vous payez une génération complète, puis une autre. Si le deuxième essai échoue aussi, vous payez une troisième fois. Quand dix pour cent des réponses nécessitent une correction, la facture augmente d'une douzaine de pour cent environ ; à cinquante pour cent, elle double presque.

Le temps s'y ajoute. Une relance signifie la latence complète d'un autre appel : une réponse qui prenait deux secondes en prend quatre avec une correction.

La conclusion pratique comporte deux volets. D'abord, fixez une limite du nombre d'essais et décidez ce qui se passe une fois qu'elle est épuisée, car le comportement par défaut est rarement celui que vous voulez en production. Ensuite, considérez un nombre élevé de relances comme un signal plutôt que comme un état normal.

Si le modèle rate régulièrement la forme de réponse requise, la solution la moins chère est de corriger les instructions ou d'utiliser l'imposition de structure côté API, plutôt que de générer deux fois une réponse.

Ce dernier point mérite d'être souligné, car il a changé ces dernières années. Les modèles acceptent maintenant un schéma de réponse et l'imposent pendant la génération, si bien que valider la structure après coup est devenu en grande partie redondant. La valeur de cette bibliothèque s'est déplacée vers les vérifications qu'un modèle n'effectuera pas lui-même : données personnelles, périmètre thématique et règles métier.

Structure de réponse et schémas

Historiquement, la bibliothèque s'appuyait sur son propre format de description de structure, écrit sous forme de balisage. Cela fonctionne toujours et on le retrouve dans des documents plus anciens.

La voie la plus pratique aujourd'hui est de décrire la structure attendue avec un modèle de données ordinaire que vous avez déjà dans le projet.

Python
from pydantic import BaseModel, Field

class Ticket(BaseModel):
    category: str = Field(description="one of: complaint, question, outage")
    urgency: int = Field(ge=1, le=5)
    summary: str

guard = Guard.for_pydantic(Ticket)

L'avantage est évident : la même description sert à la validation, à la complétion dans l'éditeur et à la vérification de types dans le reste de l'application, donc il n'y a pas deux endroits qui doivent rester en accord.

La réserve de la section précédente s'applique ici aussi. Si votre fournisseur de modèle prend en charge l'imposition de structure, utilisez-la et laissez à la bibliothèque les vérifications qu'un modèle ne fera pas : plages de valeurs, règles métier et dépendances entre champs.

Vérifier l'entrée, pas seulement la sortie

Le nom et la plupart des documents attirent l'attention sur la réponse du modèle, alors qu'un guard peut aussi couvrir ce qui lui parvient. C'est souvent plus important et moins coûteux.

La vérification de l'entrée attrape trois choses. La première, ce sont les données qui ne devraient pas quitter votre infrastructure : un utilisateur colle un extrait de contrat contenant des noms, ou une clé d'accès, pour demander ce qui ne va pas. L'attraper avant l'envoi est le seul moment où réagir est possible.

La deuxième, ce sont les tentatives de contournement des instructions. Les attraper à l'entrée coûte une fraction de ce que coûte générer une réponse puis la vérifier, puisque le modèle n'est jamais appelé.

La troisième, ce sont les questions hors périmètre. Un refus émis avant l'appel au modèle est gratuit, alors qu'un refus après la génération d'une réponse coûte un appel complet et autant de temps qu'une réponse donnée.

Il en découle une règle à adopter : déplacez les vérifications le plus tôt possible. Chacune de celles qui peuvent s'exécuter à l'entrée économise un appel au modèle au lieu de simplement ajouter de la sécurité.

Les exceptions sont les vérifications qui, par nature, portent sur le résultat : structure de la réponse, données personnelles générées par le modèle, accord avec des faits tirés de la documentation. Celles-là ne peuvent pas être déplacées plus tôt et le coût y est inévitable.

Validators personnalisés

Le catalogue couvre les cas généraux, et les règles métier sont par définition spécifiques : tôt ou tard, vous écrirez votre propre validator.

Python
from guardrails.validators import Validator, register_validator, PassResult, FailResult

@register_validator(name="in-price-list", data_type="string")
class InPriceList(Validator):
    def validate(self, value, metadata):
        if value not in metadata["available_plans"]:
            return FailResult(
                error_message=f"Plan {value} does not exist in the price list.",
                fix_value=metadata["available_plans"][0],
            )
        return PassResult()

Trois points méritent d'être soignés quand vous écrivez votre propre vérification.

Le premier est le message d'erreur. Avec l'action de relance, ce message parvient au modèle comme consigne : une phrase qui dit clairement ce qui ne va pas et ce que vous attendez augmente davantage les chances d'un deuxième essai correct que n'importe quelle modification de l'instruction système.

Le deuxième est la valeur de repli. Si une valeur correcte peut être fournie mécaniquement, fournissez-la, car une correction déterministe est gratuite alors que la relance coûte un appel complet.

Le troisième est la vitesse. Un validator exécuté sur chaque réponse devrait se terminer en quelques millisecondes. Une vérification qui interroge une base de données ou un service externe ajoute de la latence à chaque réponse : pensez donc à mettre en cache les données dont elle dépend.

Guardrails AI face aux alternatives

OptionPoint fortPoint faibleÀ choisir quand
Guardrails AICatalogue de validators prêts à l'emploi, se branche sur un appel existantLa relance coûte un appel completVérifier des résultats pour des données et des règles
NeMo GuardrailsContrôle du déroulement de la conversationDéploiement plus lourd, un langage à partUn assistant qui mène un dialogue avec l'utilisateur
Imposition de structure par l'APIAucun coût supplémentaire, forme garantieStructure uniquement, pas de règles de contenuUne réponse avec un schéma fixe
Vos propres vérifications dans le codeContrôle total, aucune dépendanceVous écrivez chaque règle vous-mêmeQuelques règles métier précises

Considérez d'abord la troisième ligne, car pour la seule structure de réponse elle résout le problème sans rien ajouter. La bibliothèque commence à être rentable là où les vérifications dépassent la forme : données personnelles, sujet de la conversation et conformité aux règles de l'organisation.

Le choix entre la première et la deuxième ligne dépend de ce que vous contrôlez. Le résultat d'un seul appel, c'est la première ligne. Le déroulement d'une conversation entière, c'est la deuxième.

Rappelez-vous aussi que les bibliothèques orientées vers les résultats typés, comme celle présentée dans l'article sur Pydantic AI, résolvent une partie de ce problème incidemment, sans couche de validation distincte.

Pratique du déploiement

Quelques points qui, en production, séparent une solution qui marche d'une solution qui génère des coûts et du bruit.

Commencez en mode observation. Activez les validators avec une action limitée à la journalisation et passez deux semaines à collecter des données sur la fréquence de déclenchement de chacun. Ce chiffre surprend généralement dans les deux sens : certaines vérifications ne se déclenchent jamais, d'autres bloqueraient une réponse sur dix.

Activez-les ensuite un par un, en commençant par les moins coûteux. Les vérifications par motif coûtent peu, donc elles peuvent tourner à chaque appel. Celles qui font tourner leur propre modèle méritent d'être limitées aux cas où elles sont vraiment nécessaires.

Enregistrez les cas où la validation s'est déclenchée. C'est le seul moyen de distinguer un blocage justifié d'une fausse alerte, et avec cette classe d'outils les fausses alertes abîment davantage un produit que le fait de laisser passer du contenu.

Prévoyez aussi le comportement en cas de panne de la couche de validation elle-même. Un validator qui utilise un modèle peut cesser de répondre, et deux comportements ont alors du sens : laisser passer le trafic sans vérification ou refuser le service. Le choix dépend de ce qui est le pire dans votre cas, et le comportement par défaut mérite d'être vérifié plutôt que supposé.

Une dernière question concerne les réponses en streaming. La validation a par nature besoin du résultat entier, donc une réponse vérifiée après génération ne peut pas s'afficher progressivement à l'écran. C'est un vrai compromis : soit l'utilisateur voit le texte dès le premier mot et le reçoit sans vérification, soit il attend le tout et reçoit un résultat vérifié. Sur les réponses courtes, la différence passe inaperçue ; sur les longues, elle décide de la sensation que donne le produit, et elle mérite d'être tranchée délibérément plutôt que découverte après le lancement.

Erreurs fréquentes

La première est de valider la structure après coup alors que le modèle peut l'imposer pendant la génération. C'est une couche en plus qui résout un problème qui n'existe plus.

La deuxième est de relancer sans limite d'essais. Chaque essai est un appel complet au modèle : une boucle sur un cas difficile peut donc coûter un multiple d'une réponse ordinaire.

La troisième est d'activer tous les validators d'un coup en production. Sans période d'observation, vous ne savez pas lesquels se déclencheront et lesquels ne feront qu'ajouter de la latence.

La quatrième est de traiter un nombre élevé de corrections comme normal. C'est le signe que les instructions ou le schéma doivent être corrigés, pas que la couche de validation fonctionne bien.

La cinquième est d'utiliser sans nécessité des vérifications à base de modèle à chaque appel. Elles coûtent plusieurs fois plus cher que les vérifications par motif et méritent d'être exécutées de façon sélective.

La sixième est de ne pas enregistrer les cas où les vérifications se sont déclenchées. Sans cela, vous ne pouvez pas distinguer un blocage justifié d'une fausse alerte, et c'est la seule mesure de l'efficacité.

La septième est de ne contrôler que les réponses, alors qu'une partie des règles peut s'appliquer à l'entrée. Un refus émis avant l'appel au modèle est gratuit, alors qu'un refus émis après la génération coûte un appel complet.

FAQ

En quoi est-ce différent de NeMo Guardrails ?

Par sa forme. Cette bibliothèque se branche sur un appel précis au modèle et vérifie son résultat. NeMo Guardrails est une couche intermédiaire qui pilote toute une conversation. La première est plus légère à déployer, la seconde donne le contrôle sur le dialogue.

Combien coûte une relance du modèle ?

Un appel complet à chaque fois. Quand dix pour cent des réponses nécessitent une correction, la facture augmente d'une douzaine de pour cent environ, et le temps de réponse double dans ces cas. Fixez une limite d'essais et voyez dans un nombre élevé de corrections un signal pour changer les instructions.

En ai-je besoin quand le modèle impose la structure ?

Pour la seule structure, généralement non. La valeur de cette bibliothèque tient aux vérifications qu'un modèle ne fera pas : détection de données personnelles, restriction du périmètre thématique et règles métier propres à votre contexte.

Quels validators sont disponibles ?

Le catalogue couvre la détection de données personnelles, la mesure de la toxicité, la correspondance de motifs, la détection de mentions de concurrents, la restriction du périmètre thématique et la détection de tentatives de contournement des instructions. Chacun est un paquet distinct, installé à la demande.

Comment démarrer en sécurité ?

En mode observation : activez les validators avec une action limitée à la journalisation et passez deux semaines à collecter des données sur la fréquence de déclenchement de chacun. Activez ensuite seulement le blocage, en commençant par les vérifications les moins coûteuses et les plus précises.

La documentation se trouve sur le site du projet, et le catalogue de validators dans une section distincte.

À lire aussi