Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Guardrails configureren in Python

Les 3 van 12 Bijgewerkt op 3 november 2026 Ontwikkelaar
Op deze pagina
  1. Van theorie naar code
  2. De parameter guardrails in detail
  3. Volledig voorbeeld: chatbot met guardrails
  4. Blokkeerfouten correct afhandelen
  5. Best practices voor configuratie
  6. Belangrijkste punten

Les herschreven op 3 november 2026. De vorige versie configureerde guardrails met een verzonnen dictionary (enabled), niet-bestaande categorieën (hate, violence, unpredictable), beweerde dat niet-opgesomde categorieën “standaard drempelwaarden” hanteerden, en testte e.status_code == 3201, terwijl 3201 een foutcode in de response body is en geen HTTP-statuscode. De configuratie volgt nu het officiële formaat en de code is geverifieerd tegen de types van de mistralai SDK 3.7.0. Bronnen: Moderation & Guardrailing · mistralai Python SDK.

Van theorie naar code

U begrijpt nu hoe guardrails werken. In deze les configureert u ze nauwkeurig: selecteer uw categorieën, definieer uw drempelwaarden en handel blokkades af in uw Python-code.

Begin met de geïnstalleerde Mistral SDK (guardrails vereisen versie 2 of later) en een API-sleutel die vanuit de omgeving wordt geladen in plaats van hardgecodeerd.

pip install "mistralai>=2"
import os

from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

De parameter guardrails in detail

De parameter guardrails is een lijst. Elk item koppelt de optie block_on_error aan een configuratie moderation_llm_v2, die op zijn beurt drempelwaarden, de optie ignore_other_categories en de actie bevat:

from mistralai.client.models import GuardrailConfigTypedDict

GUARDRAILS: list[GuardrailConfigTypedDict] = [
    {
        # Blokkeer als de evaluatie zelf mislukt
        "block_on_error": True,
        "moderation_llm_v2": {
            # Drempelwaarden per categorie, van 0 tot 1 (1 schakelt de categorie uit)
            "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,
            # Actie bij overschrijding van de drempelwaarde
            "action": "block",
        },
    }
]

Het standaard moderatiemodel is mistral-moderation-2603; met de optionele sleutel model_name kunt u een ander model specificeren.

De annotatie list[GuardrailConfigTypedDict] is niet verplicht, maar wel aan te raden: de SDK beschrijft elke toegestane sleutel, zodat een typechecker zoals pyright of mypy een verkeerd gespelde categorie (violence in plaats van violence_and_threats) signaleert die de API zelf niet zou opvangen.

custom_category_thresholds

Dit is de kern van de configuratie. Elke categorie krijgt een drempelwaarde tussen 0 en 1, die wordt vergeleken met de score die de classifier aan de prompt toekent. Hoe lager de drempelwaarde, hoe strenger het filter blokkeert, met het risico legitieme verzoeken af te wijzen. Een drempelwaarde van 1 schakelt de categorie expliciet uit. Mistral publiceert geen aanbevolen waardetabel: u moet deze kalibreren op basis van uw eigen voorbeelden (les 7).

Waarden zijn alleen zinvol in de context van uw applicatie. Een publieke chatbot zet gevoelige categorieën op de laagste stand, terwijl een interne tool voor zorgprofessionals medische vragen moet toestaan maar streng blijft op persoonsgegevens.

# Publieke chatbot: zeer lage drempelwaarden
public_thresholds = {
    "sexual": 0.1,
    "hate_and_discrimination": 0.1,
    "violence_and_threats": 0.1,
    "criminal": 0.1,
    "selfharm": 0.1,
}

# Interne medische tool: health uitgeschakeld, PII blijft bewaakt
medical_thresholds = {
    "sexual": 0.2,
    "hate_and_discrimination": 0.1,
    "violence_and_threats": 0.3,
    "health": 1,   # schakelt categorie uit: medische vragen zijn de kernfunctie van de tool
    "pii": 0.1,
}

Categorieën die u niet opneemt

Wat gebeurt er met categorieën die ontbreken in custom_category_thresholds? De documentatie vermeldt dit niet expliciet, maar het blokkeervoorbeeld is veelzeggend: niet-opgesomde categorieën verschijnen daar met een drempelwaarde van 1.0, genoteerd maar ineffectief. Vertrouw niet op een standaarddrempel: som elke categorie op die moet kunnen blokkeren.

De optie ignore_other_categories bepaalt alleen wat wordt geëvalueerd en teruggegeven. Bij False verschijnen alle geëvalueerde categorieën in het resultaat; bij True worden alleen de door u opgesomde categorieën geëvalueerd.

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,  # evalueert alleen deze twee categorieën
            "action": "block",
        },
    }
]

Waarschuwing: met deze configuratie zou een jailbreak-poging of een verzoek om persoonsgegevens ongecontroleerd passeren. Beperk de lijst alleen om een specifieke reden.

Volledig voorbeeld: chatbot met guardrails

Hier is een minimale functie: deze verzendt het bericht met de volledige configuratie en zet een blokkade om in een leesbaar antwoord voor de gebruiker.

from mistralai.client import errors


def chat_securise(message_utilisateur: str) -> str:
    """Verzendt een bericht beschermd door guardrails."""
    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 "Sorry, dit verzoek kan niet worden verwerkt."
        raise

    contenu = response.choices[0].message.content
    return contenu if isinstance(contenu, str) else ""


print(chat_securise("Explain machine learning to me"))

Twee opmerkingen. message.content kan een string of een lijst van onderdelen zijn, afhankelijk van het model, vandaar de isinstance-controle. En de response van chat.complete() geeft geen guardrail-scores weer in SDK 3.7.0: om deze te loggen, gebruikt u de Conversations API, waarvan de response ze in guardrails bevat.

Blokkeerfouten correct afhandelen

U moet twee soorten fouten onderscheiden die om een ander bericht en een andere alert vragen: een blokkade vanwege inhoudsbeleid, die HTTP-status 403 retourneert, en een mislukte moderatie-evaluatie met ingeschakelde block_on_error, die door de response body wordt gesignaleerd met code 3201. Beide komen binnen als errors.SDKError, waarvan body de JSON bevat die door de API is teruggegeven:

import json
from typing import Any

from mistralai.client import errors


def chat_avec_gestion_erreurs(message_utilisateur: str) -> dict[str, Any]:
    """Chat die beleidsblokkades onderscheidt van moderatiefouten."""
    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": "Moderatiedienst niet beschikbaar. Verzoek geblokkeerd als voorzorgsmaatregel.",
            }
        if e.status_code == 403:
            decisions = corps["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
            return {
                "status": "blocked",
                "content": "Uw bericht is geblokkeerd door ons beveiligingsbeleid.",
                "categories": [nom for nom, d in decisions.items() if d["violated"]],
            }
        raise

    return {"status": "ok", "content": response.choices[0].message.content}

Controleer eerst code 3201, omdat de documentatie de HTTP-status voor deze fout niet specificeert. Overtreden categorieën komen uit decisions, waar elke entry threshold, score en violated geeft: dit is wat u logt om een blokkade uit te leggen.

Best practices voor configuratie

Begin restrictief en versoepel daarna. Lage drempelwaarden bij de lancering helpen u false positives te ontdekken terwijl het volume nog beheersbaar is, en elke verhoging wordt beslist op basis van waargenomen gevallen in plaats van intuïtie:

# Fase 1: lancering (zeer restrictief)
phase1 = {"hate_and_discrimination": 0.1, "violence_and_threats": 0.1, "criminal": 0.1}

# Fase 2: na analyse van false positives
phase2 = {"hate_and_discrimination": 0.15, "violence_and_threats": 0.25, "criminal": 0.1}

# Fase 3: stabiele productie
phase3 = {"hate_and_discrimination": 0.2, "violence_and_threats": 0.3, "criminal": 0.15}

Deze waarden illustreren de aanpak; de uwe komen voort uit uw eigen metingen. Houd block_on_error ingesteld op True in productie: de standaardwaarde in de SDK is False, en een moderatiefout zou dan ongeverifieerde inhoud doorlaten. Tot slot waarschuwt de documentatie dat het moderatiemodel evolueert: beleid gebaseerd op scores kan herkalibratie vereisen.

Belangrijkste punten

  • guardrails is een lijst van objecten {"block_on_error": ..., "moderation_llm_v2": {...}}
  • Binnen moderation_llm_v2: custom_category_thresholds, ignore_other_categories, action en optioneel model_name
  • Drempelwaarden van 0 tot 1; lager is strenger; 1 schakelt een categorie uit. Som elke categorie op die moet blokkeren
  • Een blokkade raise-t errors.SDKError met status_code == 403; een fout met block_on_error bevat code 3201 in de body
  • Houd block_on_error=True in productie, omdat de standaardwaarde False is