Custom Guardrails: Block Before the Model
Tällä sivulla
Leçon réécrite le 3 novembre 2026. La version précédente décrivait un paramètre
guardrailsfictif (un dictionnaire avecenabled), des catégories inexistantes (hate,violence), une méthodeconversation.send()manquante dans le SDK et des réponses JSON imaginaires. Le format officiel est une liste de configurationsmoderation_llm_v2, et les réponses ci-dessous correspondent à la documentation. Le code a été vérifié avec les types du SDKmistralaiversion 3.7.0. Sources : Moderation & Guardrailing · mistralai Python SDK.
Le principe des Custom Guardrails
Les Custom Guardrails de Mistral agissent comme un filtre d’entrée : ils analysent l’invite (prompt) de l’utilisateur avant qu’elle n’atteigne le modèle de génération. Si le contenu dépasse l’un des seuils que tu as définis, la requête est bloquée par une erreur HTTP 403. Le modèle ne voit jamais l’invite problématique.
Garde dès le départ deux limitations en tête. Premièrement, les guardrails modèrent uniquement l’entrée ; ils ne vérifient pas ce que le modèle génère. C’est le rôle de l’API de Modération (Leçon 5). Deuxièmement, ils remplacent un travail que tu devrais autrement coder toi-même : appeler l’API de Modération, comparer les scores à tes seuils et rejeter la requête.
Comment ça marche
Lorsque tu ajoutes des guardrails à une requête, le flux côté Mistral est le suivant :
- Ton application envoie la requête avec le paramètre
guardrails. - Le classifieur
mistral-moderation-2603attribue un score à l’invite dans chaque catégorie. - Si un score dépasse son seuil, l’API renvoie une erreur
403et le modèle n’est pas appelé. - Sinon, le modèle traite la requête normalement.
- La réponse inclut un champ
guardrailscontenant les scores évalués.
Flow: prompt → [mistral-moderation-2603] → score > threshold? → 403 (blocked)
→ else → [LLM] → response + scores
La décision repose sur un score comparé à un seuil que tu définis, catégorie par catégorie, entre 0 et 1. Un seuil bas bloque plus de contenu ; un seuil de 1 désactive explicitement la catégorie.
Le format du paramètre guardrails
Le paramètre est une liste. Chaque élément est un objet contenant une configuration moderation_llm_v2 et, à côté, l’option block_on_error :
guardrails = [
{
"block_on_error": True, # block if moderation itself fails
"moderation_llm_v2": {
"custom_category_thresholds": {
"jailbreaking": 0.3,
"criminal": 0.2,
},
"ignore_other_categories": False,
"action": "block",
},
}
]
| Clé | Emplacement | Rôle |
|---|---|---|
custom_category_thresholds | dans moderation_llm_v2 | Seuil de 0 à 1 par catégorie ; 1 désactive la catégorie |
ignore_other_categories | dans moderation_llm_v2 | True : seules les catégories listées sont évaluées |
action | dans moderation_llm_v2 | "block" pour rejeter la requête si un seuil est dépassé |
model_name | dans moderation_llm_v2, optionnel | Modèle de modération autre que le défaut mistral-moderation-2603 |
block_on_error | à côté de moderation_llm_v2 | True : la requête est bloquée si l’évaluation échoue |
Tu peux placer plusieurs objets dans la liste : la requête est bloquée dès que l’un d’eux se déclenche. Chaque objet contient une seule configuration moderation_llm_v2. Une ancienne configuration, moderation_llm_v1, existe toujours dans le SDK avec des catégories du modèle obsolète mistral-moderation-2411 (déprécié le 31 mars 2026) : ne l’utilise pas pour de nouveaux projets.
Les onze catégories
Les clés dans custom_category_thresholds sont fixes ; une autre clé, telle que violence ou hate, ne correspond à rien :
| Clé | Ce qu’elle détecte |
|---|---|
sexual | Contenu sexuel explicite |
hate_and_discrimination | Haine ou discrimination basée sur des caractéristiques protégées |
violence_and_threats | Violence physique décrite, glorifiée ou menacée |
dangerous | Comportements extrêmement dangereux |
criminal | Activités illégales |
selfharm | Automutilation, suicide, troubles alimentaires |
health | Demandes de conseils médicaux détaillés ou personnalisés |
financial | Demandes de conseils financiers détaillés ou personnalisés |
law | Demandes de conseils juridiques détaillés ou personnalisés |
pii | Données personnelles demandées ou partagées |
jailbreaking | Tentatives de contournement des règles du modèle |
La Leçon 6 revient sur chacune d’elles et discute du choix des seuils.
Les trois niveaux d’application
Le même paramètre est accepté à trois endroits. Ton choix détermine où réside ta politique de sécurité et qui pourrait oublier de l’appliquer.
Niveau 1 : Une requête Chat Completions
Tu passes guardrails dans l’appel chat.complete(). Chaque requête porte ses propres règles : pratique pour l’exploration, mais risqué à grande échelle, car un seul appel sans le paramètre passe inaperçu.
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "What is the distance from the Earth to the Moon?"}],
guardrails=[
{
"block_on_error": True,
"moderation_llm_v2": {
"custom_category_thresholds": {"sexual": 0.1, "selfharm": 0.1},
"ignore_other_categories": False,
"action": "block",
},
}
],
)
print(response.choices[0].message.content)
Cas d’usage : Prototypage, appels ponctuels, ajustement des seuils.
Niveau 2 : Une Conversation
Avec l’API Conversations, tu passes guardrails au démarrage, dans client.beta.conversations.start() :
conversation = client.beta.conversations.start(
model="mistral-large-latest",
inputs="Hello, can you help me prepare for an interview?",
guardrails=[
{
"block_on_error": True,
"moderation_llm_v2": {
"custom_category_thresholds": {
"sexual": 0.2,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.3,
"selfharm": 0.1,
},
"action": "block",
},
}
],
)
for entree in conversation.outputs:
if entree.type == "message.output":
print(entree.content)
Les messages suivants sont envoyés avec client.beta.conversations.append(conversation_id=conversation.conversation_id, inputs=...). Cette méthode n’accepte pas de paramètre guardrails dans le SDK 3.7.0, et la documentation ne précise pas si les guardrails de démarrage s’appliquent aux tours suivants. Pour une protection garantie à chaque tour, attache les guardrails à un agent.
Cas d’usage : Conversation ponctuelle sans agent, ou remplacement des guardrails d’un agent pour une requête spécifique.
Niveau 3 : Un Agent
Les guardrails passés à client.beta.agents.create() deviennent partie intégrante de la définition de l’agent. Selon la documentation, toutes les conversations utilisant cet agent les héritent sans avoir besoin de les répéter. Cependant, une requête de conversation peut les remplacer en passant ses propres guardrails.
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Secure Assistant",
instructions="You are a professional customer service assistant.",
guardrails=[
{
"block_on_error": True,
"moderation_llm_v2": {
"custom_category_thresholds": {
"sexual": 0.1,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.2,
"criminal": 0.1,
"selfharm": 0.1,
"jailbreaking": 0.3,
},
"ignore_other_categories": False,
"action": "block",
},
}
],
)
conversation = client.beta.conversations.start(agent_id=agent.id, inputs="Hello!")
Cas d’usage : Production, lorsque plusieurs équipes ou services appellent le même assistant.
Ce que renvoient les Guardrails
Lorsque la requête passe, la réponse de l’API inclut, à côté des champs standards, un champ guardrails : une liste avec un résultat par guardrail. Voici ce champ issu de l’exemple de la documentation :
{
"guardrails": [
{
"moderation_llm_v2": {
"action": "pass",
"categories": {
"sexual": { "score": 0.03, "violated": false },
"selfharm": { "score": 0.05, "violated": false },
"violence_and_threats": { "score": 0.0, "violated": false },
"hate_and_discrimination": { "score": 0.0, "violated": false }
}
}
}
]
}
Avec ignore_other_categories défini sur True, seules les catégories listées dans tes seuils apparaissent dans ce résultat. Dans le SDK Python, une réponse de conversation expose ce champ (conversation.guardrails). La réponse de chat.complete(), en revanche, n’a pas de champ désigné pour cela dans le SDK 3.7.0 : elle y est perdue. Si tu veux journaliser les scores — et il est utile de savoir plus tard si tes seuils sont trop larges ou trop stricts — utilise les conversations ou lis la réponse HTTP brute.
Lorsqu’un seuil est dépassé, l’API renvoie une erreur 403 dont le corps détaille la décision, catégorie par catégorie :
{
"error": { "message": "Content blocked by guardrail", "status": 403 },
"guardrails": {
"results": {
"moderation_llm_v2": {
"model_name": "mistral-moderation-2603",
"decisions": {
"sexual": { "threshold": 0.1, "score": 0.3, "violated": true },
"selfharm": { "threshold": 0.1, "score": 0.05, "violated": false }
},
"violated": true,
"action": "block"
}
}
}
}
Le SDK lève alors errors.SDKError, où status_code est 403 et body contient ce JSON :
import json
from mistralai.client import errors
try:
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": user_message}],
guardrails=guardrails,
)
except errors.SDKError as e:
if e.status_code != 403:
raise
decisions = json.loads(e.body)["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
violated = [name for name, d in decisions.items() if d["violated"]]
print(f"Request blocked: {violated}")
Cette charge utile te permet d’expliquer un blocage lors d’un appel : quelle catégorie, quel score, quel seuil.
Enfin, il y a le cas dégradé. Si l’évaluation elle-même échoue et que block_on_error est True, la requête est refusée avec le code d’erreur 3201 et le message Request blocked due to error in guardrail evaluation and block_on_error is set to True. C’est le mode fail-safe : en cas de doute, on bloque. Avec block_on_error défini sur False (sa valeur par défaut dans le SDK), la requête passerait sans contrôle.
Choisir le bon niveau
| Critère | Chat Completions | Conversation | Agent |
|---|---|---|---|
| Où les guardrails sont déclarés | Dans chaque appel | Au démarrage (start) | À la création de l’agent |
| Héritage | Aucun | Non documenté pour les tours suivants | Toutes les conversations de l’agent |
| Remplaçable | — | — | Oui, par une requête de conversation |
| Cas d’usage | Tests, ajustement des seuils | Conversation ponctuelle | Production |
En pratique, ajuste tes seuils sur des requêtes Chat Completions en utilisant des cas réels, puis déplace la politique vers un agent dès que le code quitte ta machine : il n’y aura plus d’appels oubliés.
Keskeiset asiat
- Les guardrails bloquent les invites avant le modèle via une erreur
403; ils ne vérifient pas la sortie - Le paramètre est une liste d’objets
{"block_on_error": ..., "moderation_llm_v2": {...}}, pas un dictionnaire avecenabled - Onze catégories aux noms fixes (
hate_and_discrimination,violence_and_threats, …), chacune avec un seuil de 0 à 1 ;1désactive - Trois niveaux :
chat.complete(),conversations.start(),agents.create(); les agents transmettent leurs guardrails à toutes leurs conversations block_on_error=Trueassure un comportement fail-safe (erreur3201)