Configurer les garde-fous en Python
Na ovoj stranici
Leçon réécrite le 3 novembre 2026. La version précédente configurait les garde-fous via un dictionnaire inventé (
enabled), utilisait des catégories inexistantes (hate,violence,unpredictable), affirmait que les catégories non listées conservaient des « seuils par défaut » et testaite.status_code == 3201, alors que3201est un code d’erreur dans le corps de la réponse, pas un statut HTTP. La configuration suit désormais le format officiel et le code a été vérifié contre les types du SDKmistralai3.7.0. Sources : Moderation & Guardrailing · mistralai Python SDK.
De la théorie au code
Tu comprends maintenant comment fonctionnent les garde-fous. Dans cette leçon, tu vas les configurer avec précision : sélectionner tes catégories, définir tes seuils et gérer les blocages dans ton code Python.
Commence par installer le SDK Mistral (les garde-fous nécessitent la version 2 ou ultérieure) et charge ta clé API depuis l’environnement plutôt que de la coder en dur.
pip install "mistralai>=2"
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Le paramètre guardrails en détail
Le paramètre guardrails est une liste. Chaque élément associe l’option block_on_error à une configuration moderation_llm_v2, laquelle contient elle-même les seuils, l’option ignore_other_categories et l’action :
from mistralai.client.models import GuardrailConfigTypedDict
GUARDRAILS: list[GuardrailConfigTypedDict] = [
{
# Bloquer si l'évaluation elle-même échoue
"block_on_error": True,
"moderation_llm_v2": {
# Seuils par catégorie, de 0 à 1 (1 désactive la catégorie)
"custom_category_thresholds": {
"sexual": 0.2,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.3,
"dangerous": 0.2,
"criminal": 0.1,
"selfharm": 0.1,
"health": 0.5,
"financial": 0.5,
"law": 0.5,
"pii": 0.2,
"jailbreaking": 0.1,
},
"ignore_other_categories": False,
# Action en cas de dépassement de seuil
"action": "block",
},
}
]
Le modèle de modération par défaut est mistral-moderation-2603 ; la clé optionnelle model_name te permet d’en spécifier un autre.
L’annotation list[GuardrailConfigTypedDict] n’est pas obligatoire, mais elle vaut la peine d’être utilisée : le SDK décrit chaque clé autorisée, ainsi un vérificateur de types comme pyright ou mypy signalera une catégorie mal orthographiée (violence au lieu de violence_and_threats) que l’API elle-même ne détecterait pas.
custom_category_thresholds
C’est le cœur de la configuration. Chaque catégorie reçoit un seuil entre 0 et 1, comparé au score attribué par le classifieur à la requête. Plus le seuil est bas, plus le filtre bloque, au risque de rejeter des requêtes légitimes. Un seuil de 1 désactive explicitement la catégorie. Mistral ne publie pas de grille de valeurs recommandées : tu dois les calibrer sur tes propres exemples (leçon 7).
Les valeurs n’ont de sens que dans le contexte de ton application. Un chatbot ouvert au public verrouille les catégories sensibles avec les réglages les plus stricts, tandis qu’un outil interne pour des professionnels de santé doit autoriser les questions médicales tout en restant rigoureux sur les données personnelles.
# Chatbot public : seuils très bas
public_thresholds = {
"sexual": 0.1,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.1,
"criminal": 0.1,
"selfharm": 0.1,
}
# Outil médical interne : santé désactivée, PII toujours surveillé
medical_thresholds = {
"sexual": 0.2,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.3,
"health": 1, # désactive la catégorie : les questions médicales sont la fonction centrale de l'outil
"pii": 0.1,
}
Catégories que tu ne listes pas
Que se passe-t-il pour les catégories absentes de custom_category_thresholds ? La documentation ne l’indique pas explicitement, mais son exemple de blocage est éloquent : les catégories non listées y apparaissent avec un seuil de 1.0, notées mais inefficaces. Ne compte pas sur un seuil par défaut : liste chaque catégorie susceptible de provoquer un blocage.
L’option ignore_other_categories contrôle uniquement ce qui est évalué et renvoyé. Lorsqu’elle est à False, toutes les catégories évaluées apparaissent dans le résultat ; lorsqu’elle est à True, seules celles que tu as listées sont évaluées.
TARGETED_GUARDRAILS: list[GuardrailConfigTypedDict] = [
{
"block_on_error": True,
"moderation_llm_v2": {
"custom_category_thresholds": {
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.2,
},
"ignore_other_categories": True, # évalue uniquement ces deux catégories
"action": "block",
},
}
]
Avertissement : avec cette configuration, une tentative de jailbreak ou une demande de données personnelles passerait sans contrôle. Restreins la liste uniquement pour une raison spécifique.
Exemple complet : chatbot avec garde-fous
Voici une fonction minimale : elle envoie le message avec la configuration complète et transforme un blocage en une réponse lisible pour l’utilisateur.
from mistralai.client import errors
def chat_securise(message_utilisateur: str) -> str:
"""Envoie un message protégé par des garde-fous."""
try:
response = client.chat.complete(
model="mistral-large-latest",
messages=[
{"role": "system", "content": "You are a professional assistant."},
{"role": "user", "content": message_utilisateur},
],
guardrails=GUARDRAILS,
)
except errors.SDKError as e:
if e.status_code == 403:
return "Désolé, cette requête ne peut pas être traitée."
raise
contenu = response.choices[0].message.content
return contenu if isinstance(contenu, str) else ""
print(chat_securise("Explain machine learning to me"))
Deux remarques. message.content peut être une chaîne ou une liste de parties selon le modèle, d’où la vérification isinstance. Et la réponse de chat.complete() n’expose pas les scores des garde-fous dans le SDK 3.7.0 : pour les journaliser, utilise l’API Conversations, dont la réponse les porte dans guardrails.
Gérer proprement les erreurs de blocage
Tu dois distinguer deux échecs qui n’appellent ni le même message ni la même alerte : un blocage pour politique de contenu, qui renvoie le statut HTTP 403, et un échec de l’évaluation de modération avec block_on_error activé, que le corps de la réponse signale par le code 3201. Les deux arrivent sous forme de errors.SDKError, dont l’attribut body contient le JSON renvoyé par l’API :
import json
from typing import Any
from mistralai.client import errors
def chat_avec_gestion_erreurs(message_utilisateur: str) -> dict[str, Any]:
"""Chat qui distingue les blocages politiques des échecs de modération."""
try:
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": message_utilisateur}],
guardrails=GUARDRAILS,
)
except errors.SDKError as e:
try:
corps = json.loads(e.body)
except json.JSONDecodeError:
raise e
if corps.get("code") == 3201:
return {
"status": "error",
"content": "Service de modération indisponible. Requête bloquée par précaution.",
}
if e.status_code == 403:
decisions = corps["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
return {
"status": "blocked",
"content": "Votre message a été bloqué par notre politique de sécurité.",
"categories": [nom for nom, d in decisions.items() if d["violated"]],
}
raise
return {"status": "ok", "content": response.choices[0].message.content}
Vérifie le code 3201 en premier, car la documentation ne spécifie pas le statut HTTP pour cette erreur. Les catégories violées proviennent de decisions, où chaque entrée donne threshold, score et violated : c’est ce que tu journaliseras pour expliquer un blocage.
Bonnes pratiques de configuration
Commence de manière restrictive, puis assouplis. Des seuils bas au lancement t’aident à découvrir les faux positifs tant que le volume reste gérable, et chaque augmentation se décide sur la base de cas observés plutôt que sur l’intuition :
# Phase 1 : lancement (très restrictif)
phase1 = {"hate_and_discrimination": 0.1, "violence_and_threats": 0.1, "criminal": 0.1}
# Phase 2 : après analyse des faux positifs
phase2 = {"hate_and_discrimination": 0.15, "violence_and_threats": 0.25, "criminal": 0.1}
# Phase 3 : production stable
phase3 = {"hate_and_discrimination": 0.2, "violence_and_threats": 0.3, "criminal": 0.15}
Ces valeurs illustrent l’approche ; les tiennes viendront de tes propres mesures. Garde block_on_error défini sur True en production : sa valeur par défaut dans le SDK est False, et un échec de modération laisserait alors passer du contenu non vérifié. Enfin, la documentation prévient que le modèle de modération évolue : les politiques basées sur les scores peuvent nécessiter un recalibrage.
Ključne točke
guardrailsest une liste d’objets{"block_on_error": ..., "moderation_llm_v2": {...}}- Dans
moderation_llm_v2:custom_category_thresholds,ignore_other_categories,actionet optionnellementmodel_name - Seuils de
0à1; plus bas est plus strict ;1désactive une catégorie. Liste chaque catégorie devant bloquer - Un blocage lève
errors.SDKErroravecstatus_code == 403; un échec avecblock_on_errorporte le code3201dans le corps - Garde
block_on_error=Trueen production, car la valeur par défaut estFalse