Benutzerdefinierte Guardrails: Blockieren vor dem Modell

Lektion am 3. November 2026 überarbeitet. Die vorherige Version beschrieb einen fiktiven guardrails-Parameter (ein Dictionary mit enabled), nicht existierende Kategorien (hate, violence), eine fehlende conversation.send()-Methode im SDK und imaginäre JSON-Antworten. Das offizielle Format ist eine Liste von moderation_llm_v2-Konfigurationen, und die untenstehenden Antworten entsprechen der Dokumentation. Der Code wurde gegen die mistralai-SDK-Typen-Version 3.7.0 verifiziert. Quellen: Moderation & Guardrailing · mistralai Python SDK.

Das Prinzip der benutzerdefinierten Guardrails

Die benutzerdefinierten Guardrails von Mistral fungieren als Eingabefilter: Sie analysieren den Benutzer-Prompt, bevor er das Generierungsmodell erreicht. Wenn der Inhalt einen von Ihnen festgelegten Schwellenwert überschreitet, wird die Anfrage mit einem HTTP-Fehler 403 blockiert. Das Modell sieht den problematischen Prompt nie.

Halten Sie von Anfang an zwei Einschränkungen im Kopf. Erstens moderieren Guardrails nur die Eingabe; sie prüfen nicht, was das Modell generiert. Das ist die Aufgabe der Moderations-API (Lektion 5). Zweitens ersetzen sie Arbeit, die Sie sonst selbst programmieren müssten: Aufruf der Moderations-API, Vergleich der Scores gegen Ihre Schwellenwerte und Ablehnung der Anfrage.

Funktionsweise

Wenn Sie Guardrails einer Anfrage hinzufügen, verläuft der Vorgang auf der Seite von Mistral wie folgt:

1. Ihre Anwendung sendet die Anfrage mit dem guardrails-Parameter.
2. Der Klassifizierer mistral-moderation-2603 bewertet den Prompt in jeder Kategorie.
3. Wenn ein Score seinen Schwellenwert überschreitet, gibt die API einen 403-Fehler zurück und das Modell wird nicht aufgerufen.
4. Sonst verarbeitet das Modell die Anfrage normal.
5. Die Antwort enthält ein guardrails-Feld mit den ausgewerteten Scores.

Flow: prompt → [mistral-moderation-2603] → score > threshold? → 403 (blockiert)
                                           → else             → [LLM] → response + scores

Die Entscheidung basiert auf einem Score, der mit einem von Ihnen festgelegten Schwellenwert pro Kategorie verglichen wird (zwischen 0 und 1). Ein niedriger Schwellenwert blockiert mehr Inhalte; ein Schwellenwert von 1 deaktiviert die Kategorie explizit.

Format des guardrails-Parameters

Der Parameter ist eine Liste. Jedes Element ist ein Objekt, das eine moderation_llm_v2-Konfiguration und daneben die Option block_on_error enthält:

guardrails = [
    {
        "block_on_error": True,          # blockieren, wenn die Moderation selbst fehlschlägt
        "moderation_llm_v2": {
            "custom_category_thresholds": {
                "jailbreaking": 0.3,
                "criminal": 0.2,
            },
            "ignore_other_categories": False,
            "action": "block",
        },
    }
]

Sie können mehrere Objekte in die Liste aufnehmen: Die Anfrage wird blockiert, sobald eines davon auslöst. Jedes Objekt enthält nur eine moderation_llm_v2-Konfiguration. Eine ältere Konfiguration, moderation_llm_v1, existiert zwar noch im SDK mit Kategorien aus dem veralteten Modell mistral-moderation-2411 (veraltet am 31. März 2026): Nutzen Sie sie für neue Projekte nicht.

Die elf Kategorien

Die Schlüssel in custom_category_thresholds sind fest; ein anderer Schlüssel, wie violence oder hate, entspricht nichts:

Lektion 6 geht auf jede dieser Kategorien ein und diskutiert die Auswahl der Schwellenwerte.

Die drei Ebenen der Anwendung

Der gleiche Parameter wird an drei Stellen akzeptiert. Ihre Wahl bestimmt, wo Ihre Sicherheitsrichtlinie lebt und wer sie möglicherweise vergisst.

Ebene 1: Eine Chat-Completions-Anfrage

Sie übergeben guardrails im Aufruf von chat.complete(). Jede Anfrage trägt ihre eigenen Regeln: praktisch für die Exploration, aber bei großem Umfang riskant, da ein einzelner Aufruf ohne den Parameter unkontrolliert durchrutscht.

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)

Einsatzgebiet: Prototyping, Einmalaufrufe, Feinabstimmung von Schwellenwerten.

Ebene 2: Ein Gespräch

Mit der Conversations-API übergeben Sie guardrails beim Start in 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)

Nachfolgende Nachrichten werden mit client.beta.conversations.append(conversation_id=conversation.conversation_id, inputs=...) gesendet. Diese Methode akzeptiert in SDK 3.7.0 keinen guardrails-Parameter, und die Dokumentation gibt nicht an, ob die Start-Guardrails auf nachfolgende Runden anwendbar sind. Für garantierten Schutz bei jeder Runde hängen Sie Guardrails an ein Agent an.

Einsatzgebiet: Einmaliges Gespräch ohne Agent oder Überschreiben der Agenten-Guardrails für eine spezifische Anfrage.

Ebene 3: Ein Agent

Guardrails, die an client.beta.agents.create() übergeben werden, werden Teil der Agenten-Definition. Laut Dokumentation erben alle Gespräche, die diesen Agenten verwenden, diese ohne sie wiederholen zu müssen. Eine Gesprächsanfrage kann sie jedoch überschreiben, indem sie eigene guardrails übergeben.

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!")

Einsatzgebiet: Produktion, wenn mehrere Teams oder Dienste denselben Assistenten aufrufen.

Was Guardrails zurückgeben

Wenn die Anfrage durchgeht, enthält die API-Antwort neben Standardfeldern ein guardrails-Feld: eine Liste mit einem Ergebnis pro Guardrail. Hier ist dieses Feld aus dem Dokumentationsbeispiel:

{
  "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 }
        }
      }
    }
  ]
}

Wenn ignore_other_categories auf True gesetzt ist, erscheinen in diesem Ergebnis nur die Kategorien, die in Ihren Schwellenwerten aufgeführt sind. Im Python-SDK stellt eine Gesprächsantwort dieses Feld (conversation.guardrails) bereit. Die Antwort von chat.complete() hat jedoch in SDK 3.7.0 kein dafür vorgesehenes Feld: Sie geht dort verloren. Wenn Sie Scores protokollieren möchten – und es ist nützlich zu wissen, ob Ihre Schwellenwerte zu locker oder zu eng sind – verwenden Sie Gespräche oder lesen Sie die rohe HTTP-Antwort.

Wenn ein Schwellenwert überschritten wird, gibt die API einen 403-Fehler zurück, dessen Body die Entscheidung kategorienspezifisch detailliert:

{
  "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"
      }
    }
  }
}

Das SDK wirft dann errors.SDKError, wobei status_code 403 ist und body dieses JSON enthält:

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}")

Dieser Payload ermöglicht es Ihnen, eine Blockierung während eines Widerspruchs zu erklären: welche Kategorie, welcher Score, welcher Schwellenwert.

Schließlich gibt es den degradierten Fall. Wenn die Auswertung selbst fehlschlägt und block_on_error auf True gesetzt ist, wird die Anfrage mit Fehlercode 3201 abgelehnt und die Meldung lautet Request blocked due to error in guardrail evaluation and block_on_error is set to True. Dies ist der fail-safe-Modus: Wenn Zweifel bestehen, wird blockiert. Bei block_on_error auf False (der Standardwert im SDK) würde die Anfrage unkontrolliert durchgehen.

Die richtige Ebene wählen

In der Praxis stimmen Sie Ihre Schwellenwerte auf Chat-Completions-Anfragen mit echten Fällen ab und verschieben die Richtlinie dann so schnell wie möglich in einen Agenten, sobald der Code Ihre Maschine verlässt: Es werden keine vergessenen Aufrufe mehr geben.

Kernaussagen

• Guardrails blockieren Prompts vor dem Modell über einen 403-Fehler; sie prüfen nicht die Ausgabe
• Der Parameter ist eine Liste von Objekten {"block_on_error": ..., "moderation_llm_v2": {...}}, kein Dictionary mit enabled
• Elf Kategorien mit festen Namen (hate_and_discrimination, violence_and_threats, …), jede mit einem Schwellenwert von 0 bis 1; 1 deaktiviert
• Drei Ebenen: chat.complete(), conversations.start(), agents.create(); Agenten übergeben ihre Guardrails an alle ihre Gespräche
• block_on_error=True sorgt für fail-safe-Verhalten (Fehler 3201)