Konfigurieren von Guardrails in Python — KI-Moderation und Sicherheit mit Mistral

Lektion am 3. November 2026 überarbeitet. Die vorherige Version konfigurierter Guardrails verwendete ein erfundenes Wörterbuch (enabled), nicht existierende Kategorien (hate, violence, unpredictable), behauptete, dass nicht aufgeführte Kategorien „Standard-Schwellenwerte” beibehalten, und testete e.status_code == 3201, obwohl 3201 ein Fehlercode im Antwortkörper und kein HTTP-Status ist. Die Konfiguration folgt nun dem offiziellen Format, und der Code wurde gegen die Typen des mistralai SDK 3.7.0 verifiziert. Quellen: Moderation & Guardrailing · mistralai Python SDK.

Von der Theorie zum Code

Sie verstehen nun, wie Guardrails funktionieren. In dieser Lektion konfigurieren Sie sie präzise: Wählen Sie Ihre Kategorien aus, definieren Sie Ihre Schwellenwerte und behandeln Sie Blockaden in Ihrem Python-Code.

Beginnen Sie mit dem Mistral SDK installiert (Guardrails erfordern Version 2 oder höher) und einem API-Schlüssel, der aus der Umgebung geladen wird, anstatt hartcodiert zu sein.

pip install "mistralai>=2"

import os

from mistralai.client import Mistral

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

Der Guardrails-Parameter im Detail

Der guardrails-Parameter ist eine Liste. Jeder Eintrag paart die Option block_on_error mit einer moderation_llm_v2-Konfiguration, die ihrerseits Schwellenwerte, die Option ignore_other_categories und die Aktion enthält:

from mistralai.client.models import GuardrailConfigTypedDict

GUARDRAILS: list[GuardrailConfigTypedDict] = [
    {
        # Blockieren, wenn die Bewertung selbst fehlschlägt
        "block_on_error": True,
        "moderation_llm_v2": {
            # Schwellenwerte pro Kategorie, von 0 bis 1 (1 deaktiviert die Kategorie)
            "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,
            # Aktion bei Überschreitung des Schwellenwerts
            "action": "block",
        },
    }
]

Das Standard-Moderationsmodell ist mistral-moderation-2603; der optionale Schlüssel model_name ermöglicht es, ein anderes Modell anzugeben.

Die Annotation list[GuardrailConfigTypedDict] ist nicht erforderlich, aber empfehlenswert: Das SDK beschreibt alle erlaubten Schlüssel, sodass ein Typ-Checker wie pyright oder mypy einen falsch geschriebenen Kategorienamen (z. B. violence statt violence_and_threats) markiert, den die API selbst nicht erfassen würde.

custom_category_thresholds

Dies ist das Herzstück der Konfiguration. Jeder Kategorie wird ein Schwellenwert zwischen 0 und 1 zugewiesen, der mit dem Score verglichen wird, den der Klassifizierer dem Prompt zuordnet. Je niedriger der Schwellenwert, desto strenger filtert er, mit dem Risiko, legitime Anfragen abzulehnen. Ein Schwellenwert von 1 deaktiviert die Kategorie explizit. Mistral veröffentlicht kein empfohlenes Wertgitter: Sie müssen diese an Ihren eigenen Beispielen kalibrieren (Lektion 7).

Die Werte machen nur im Kontext Ihrer Anwendung Sinn. Ein öffentlich zugänglicher Chatbot sperrt sensible Kategorien bei den niedrigsten Einstellungen, während ein internes Werkzeug für medizinisches Fachpersonal medizinische Fragen zulassen muss, aber bei personenbezogenen Daten streng bleiben sollte.

# Öffentlicher Chatbot: sehr niedrige Schwellenwerte
public_thresholds = {
    "sexual": 0.1,
    "hate_and_discrimination": 0.1,
    "violence_and_threats": 0.1,
    "criminal": 0.1,
    "selfharm": 0.1,
}

# Internes medizinisches Werkzeug: Gesundheit deaktiviert, PII weiterhin überwacht
medical_thresholds = {
    "sexual": 0.2,
    "hate_and_discrimination": 0.1,
    "violence_and_threats": 0.3,
    "health": 1,   # Kategorie deaktivieren: medizinische Fragen sind die Kernfunktion des Werkzeugs
    "pii": 0.1,
}

Kategorien, die Sie nicht auflisten

Was passiert mit Kategorien, die in custom_category_thresholds fehlen? Die Dokumentation gibt dies nicht explizit an, aber das Blockierungsbeispiel ist aufschlussreich: Nicht aufgeführte Kategorien erscheinen dort mit einem Schwellenwert von 1.0, sind notiert, aber wirkungslos. Verlassen Sie sich nicht auf einen Standard-Schwellenwert: Listen Sie jede Kategorie auf, die blockieren soll.

Die Option ignore_other_categories steuert nur, was bewertet und zurückgegeben wird. Wenn auf False gesetzt, erscheinen alle bewerteten Kategorien im Ergebnis; wenn auf True, werden nur die von Ihnen aufgeführten bewertet.

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,  # bewertet nur diese beiden Kategorien
            "action": "block",
        },
    }
]

Warnung: Mit dieser Konfiguration würden ein Jailbreak-Versuch oder eine Anfrage nach personenbezogenen Daten unkontrolliert passieren. Beschränken Sie die Liste nur aus einem spezifischen Grund.

Vollständiges Beispiel: Chatbot mit Guardrails

Hier ist eine minimale Funktion: Sie sendet die Nachricht mit der vollständigen Konfiguration und verwandelt eine Blockade in eine lesbare Antwort für den Benutzer.

from mistralai.client import errors


def chat_securise(message_utilisateur: str) -> str:
    """Sendet eine Nachricht, die durch Guardrails geschützt ist."""
    try:
        response = client.chat.complete(
            model="mistral-large-latest",
            messages=[
                {"role": "system", "content": "Sie sind ein professioneller Assistent."},
                {"role": "user", "content": message_utilisateur},
            ],
            guardrails=GUARDRAILS,
        )
    except errors.SDKError as e:
        if e.status_code == 403:
            return "Entschuldigung, diese Anfrage kann nicht verarbeitet werden."
        raise

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


print(chat_securise("Erklären Sie mir maschinelles Lernen"))

Zwei Anmerkungen. message.content kann je nach Modell ein String oder eine Liste von Teilen sein, daher die isinstance-Prüfung. Und die Antwort von chat.complete() stellt in SDK 3.7.0 keine Guardrail-Scores bereit: Um diese zu protokollieren, verwenden Sie die Conversations API, deren Antwort sie in guardrails enthält.

Sauberer Umgang mit Blockierungsfehlern

Sie müssen zwei Fehler unterscheiden, die weder dieselbe Nachricht noch dieselbe Warnung erfordern: eine Inhaltsrichtlinien-Blockade, die den HTTP-Status 403 zurückgibt, und einen Fehler bei der Moderationsbewertung mit aktiviertem block_on_error, der im Antwortkörper mit dem Code 3201 signalisiert. Beide kommen als errors.SDKError, dessen body das von der API zurückgegebene JSON enthält:

import json
from typing import Any

from mistralai.client import errors


def chat_avec_gestion_erreurs(message_utilisateur: str) -> dict[str, Any]:
    """Chat, der Richtlinien-Blockaden von Moderationsfehlern unterscheidet."""
    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": "Moderationsservice nicht verfügbar. Anfrage vorsorglich blockiert.",
            }
        if e.status_code == 403:
            decisions = corps["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
            return {
                "status": "blocked",
                "content": "Ihre Nachricht wurde von unserer Sicherheitsrichtlinie blockiert.",
                "categories": [nom for nom, d in decisions.items() if d["violated"]],
            }
        raise

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

Prüfen Sie zuerst den Code 3201, da die Dokumentation den HTTP-Status für diesen Fehler nicht spezifiziert. Verstoßene Kategorien stammen aus decisions, wo jeder Eintrag threshold, score und violated liefert: Dies ist das, was Sie protokollieren, um eine Blockade zu erklären.

Best Practices für die Konfiguration

Beginnen Sie restriktiv und lockern Sie dann auf. Niedrige Schwellenwerte bei der Inbetriebnahme helfen Ihnen, falsch-positive Ergebnisse zu entdecken, während das Volumen noch beherrschbar ist, und jede Erhöhung wird auf Basis beobachteter Fälle und nicht auf Intuition entschieden:

# Phase 1: Inbetriebnahme (sehr restriktiv)
phase1 = {"hate_and_discrimination": 0.1, "violence_and_threats": 0.1, "criminal": 0.1}

# Phase 2: Nach Analyse falsch-positiver Ergebnisse
phase2 = {"hate_and_discrimination": 0.15, "violence_and_threats": 0.25, "criminal": 0.1}

# Phase 3: Stabile Produktion
phase3 = {"hate_and_discrimination": 0.2, "violence_and_threats": 0.3, "criminal": 0.15}

Diese Werte illustrieren den Ansatz; Ihre werden aus Ihren eigenen Messungen stammen. Halten Sie block_on_error in der Produktion auf True: Der Standardwert im SDK ist False, und ein Moderationsfehler würde dann unüberprüften Inhalt durchlassen. Schließlich warnt die Dokumentation, dass sich das Moderationsmodell entwickelt: Richtlinien, die auf Scores basieren, können eine Neukalibrierung erfordern.

Kernaussagen

guardrails ist eine Liste von Objekten {"block_on_error": ..., "moderation_llm_v2": {...}}
Innerhalb von moderation_llm_v2: custom_category_thresholds, ignore_other_categories, action und optional model_name
Schwellenwerte von 0 bis 1; niedriger ist strenger; 1 deaktiviert eine Kategorie. Listen Sie jede Kategorie auf, die blockieren soll
Eine Blockade wirft errors.SDKError mit status_code == 403 auf; ein Fehler mit block_on_error enthält den Code 3201 im Körper
Halten Sie block_on_error=True in der Produktion, da der Standardwert False ist