Salt la conținutul principal
Română— Alege o limbă
Meniu

Garde-fous personnalisés : bloquer avant le modèle

Lecția 2 din 12 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Le principe des garde-fous personnalisés
  2. Fonctionnement
  3. Format du paramètre guardrails
  4. Les onze catégories
  5. Les trois niveaux d’application
  6. Ce que renvoient les garde-fous
  7. Choisir le bon niveau
  8. Puncte cheie

Leçon réécrite le 3 novembre 2026. La version précédente décrivait un paramètre guardrails fictif (un dictionnaire avec enabled), des catégories inexistantes (hate, violence), une méthode conversation.send() manquante dans le SDK et des réponses JSON imaginaires. Le format officiel est une liste de configurations moderation_llm_v2, et les réponses ci-dessous correspondent à la documentation. Le code a été vérifié par rapport aux types du SDK mistralai version 3.7.0. Sources : Moderation & Guardrailing · mistralai Python SDK.

Le principe des garde-fous personnalisés

Les garde-fous personnalisés (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 vous avez définis, la requête est bloquée par une erreur HTTP 403. Le modèle ne voit jamais l’invite problématique.

Gardez deux limitations à l’esprit dès le départ. Premièrement, les garde-fous 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 vous devriez autrement coder vous-même : appeler l’API de Modération, comparer les scores à vos seuils et rejeter la requête.

Fonctionnement

Lorsque vous ajoutez des garde-fous à une requête, le flux côté Mistral est le suivant :

  1. Votre application envoie la requête avec le paramètre guardrails.
  2. Le classifieur mistral-moderation-2603 attribue un score à l’invite dans chaque catégorie.
  3. Si un score dépasse son seuil, l’API renvoie une erreur 403 et le modèle n’est pas appelé.
  4. Sinon, le modèle traite la requête normalement.
  5. La réponse inclut un champ guardrails contenant 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 vous définissez, 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.

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,          # bloquer si la modération elle-même échoue
        "moderation_llm_v2": {
            "custom_category_thresholds": {
                "jailbreaking": 0.3,
                "criminal": 0.2,
            },
            "ignore_other_categories": False,
            "action": "block",
        },
    }
]
CléEmplacementRôle
custom_category_thresholdsdans moderation_llm_v2Seuil de 0 à 1 par catégorie ; 1 désactive la catégorie
ignore_other_categoriesdans moderation_llm_v2True : seules les catégories listées sont évaluées
actiondans moderation_llm_v2"block" pour rejeter la requête si un seuil est dépassé
model_namedans moderation_llm_v2, optionnelModèle de modération autre que le défaut mistral-moderation-2603
block_on_errorà côté de moderation_llm_v2True : la requête est bloquée si l’évaluation échoue

Vous pouvez 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 les catégories du modèle obsolète mistral-moderation-2411 (obsolète depuis le 31 mars 2026) : ne l’utilisez 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
sexualContenu sexuel explicite
hate_and_discriminationHaine ou discrimination basée sur des caractéristiques protégées
violence_and_threatsViolence physique décrite, glorifiée ou menacée
dangerousComportements extrêmement dangereux
criminalActivités illégales
selfharmAutomutilation, suicide, troubles alimentaires
healthDemandes de conseils médicaux détaillés ou personnalisés
financialDemandes de conseils financiers détaillés ou personnalisés
lawDemandes de conseils juridiques détaillés ou personnalisés
piiDonnées personnelles demandées ou partagées
jailbreakingTentatives 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. Votre choix détermine où réside votre politique de sécurité et qui pourrait oublier de l’appliquer.

Niveau 1 : Une requête Chat Completions

Vous passez 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, vous passez 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 garde-fous du démarrage s’appliquent aux tours suivants. Pour une protection garantie à chaque tour, attachez les garde-fous à un agent.

Cas d’usage : Conversation ponctuelle sans agent, ou remplacement des garde-fous d’un agent pour une requête spécifique.

Niveau 3 : Un agent

Les garde-fous 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 garde-fous

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 garde-fou. Voici ce champ tiré 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 vos 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 vous souhaitez journaliser les scores — et il est utile de savoir plus tard si vos seuils sont trop larges ou trop stricts — utilisez les conversations ou lisez 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 vous 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 (sécurité par défaut) : 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èreChat CompletionsConversationAgent
Où les garde-fous sont déclarésDans chaque appelAu démarrage (start)À la création de l’agent
HéritageAucunNon documenté pour les tours suivantsToutes les conversations de l’agent
Remplaçable——Oui, par une requête de conversation
Cas d’usageTests, ajustement des seuilsConversation ponctuelleProduction

En pratique, ajustez vos seuils sur des requêtes Chat Completions en utilisant des cas réels, puis déplacez la politique vers un agent dès que le code quitte votre machine : il n’y aura plus d’appels oubliés.

Puncte cheie

  • Les garde-fous 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": {...}}, et non un dictionnaire avec enabled
  • Onze catégories aux noms fixes (hate_and_discrimination, violence_and_threats, …), chacune avec un seuil de 0 à 1 ; 1 désactive
  • Trois niveaux : chat.complete(), conversations.start(), agents.create() ; les agents transmettent leurs garde-fous à toutes leurs conversations
  • block_on_error=True assure un comportement fail-safe (erreur 3201)