Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Custom Guardrails: Blokkeren voordat het model reageert

Les 2 van 12 Bijgewerkt op 3 november 2026 Ontwikkelaar
Op deze pagina
  1. Het principe van Custom Guardrails
  2. Hoe het werkt
  3. Het formaat van de parameter guardrails
  4. De elf categorieën
  5. De drie toepassingsniveaus
  6. Wat Guardrails retourneren
  7. Het juiste niveau kiezen
  8. Belangrijkste punten

Les herschreven op 3 november 2026. De vorige versie beschreef een fictieve guardrails-parameter (een dictionary met enabled), niet-bestaande categorieën (hate, violence), een ontbrekende conversation.send()-methode in de SDK en denkbeeldige JSON-responses. Het officiële formaat is een lijst van moderation_llm_v2-configuraties en de onderstaande responses komen overeen met de documentatie. De code is geverifieerd tegen de mistralai SDK-types versie 3.7.0. Bronnen: Moderation & Guardrailing · mistralai Python SDK.

Het principe van Custom Guardrails

Custom Guardrails van Mistral fungeren als een invoerfilter: ze analyseren de prompt van de gebruiker voordat deze het generatiemodel bereikt. Als de inhoud een door u ingestelde drempelwaarde overschrijdt, wordt het verzoek geblokkeerd met een HTTP 403-fout. Het model ziet de problematische prompt nooit.

Houd vanaf het begin rekening met twee beperkingen. Ten eerste modereren guardrails alleen de invoer; ze controleren niet wat het model genereert. Dat is de taak van de Moderation API (Les 5). Ten tweede vervangen ze werk dat u anders zelf zou moeten coderen: de Moderation API aanroepen, scores vergelijken met uw drempels en het verzoek weigeren.

Hoe het werkt

Wanneer u guardrails aan een verzoek toevoegt, verloopt het proces aan de kant van Mistral als volgt:

  1. Uw applicatie verzendt het verzoek met de parameter guardrails.
  2. De classifier mistral-moderation-2603 geeft de prompt een score voor elke categorie.
  3. Als een score de drempel overschrijdt, retourneert de API een 403-fout en wordt het model niet aangeroepen.
  4. Anders verwerkt het model het verzoek normaal.
  5. De response bevat een veld guardrails met de geëvalueerde scores.
Flow: prompt → [mistral-moderation-2603] → score > drempel? → 403 (geblokkeerd)
                                           → anders         → [LLM] → response + scores

De beslissing is gebaseerd op een score die wordt vergeleken met een drempel die u per categorie instelt, tussen 0 en 1. Een lage drempel blokkeert meer inhoud; een drempel van 1 schakelt de categorie expliciet uit.

Het formaat van de parameter guardrails

De parameter is een lijst. Elk element is een object dat een moderation_llm_v2-configuratie bevat en, daarnaast, de optie block_on_error:

guardrails = [
    {
        "block_on_error": True,          # blokkeren als moderatie zelf faalt
        "moderation_llm_v2": {
            "custom_category_thresholds": {
                "jailbreaking": 0.3,
                "criminal": 0.2,
            },
            "ignore_other_categories": False,
            "action": "block",
        },
    }
]
SleutelLocatieRol
custom_category_thresholdsbinnen moderation_llm_v2Drempel van 0 tot 1 per categorie; 1 schakelt de categorie uit
ignore_other_categoriesbinnen moderation_llm_v2True: alleen vermelde categorieën worden geëvalueerd
actionbinnen moderation_llm_v2"block" om het verzoek te weigeren als een drempel wordt overschreden
model_namebinnen moderation_llm_v2, optioneelModeratiemodel anders dan de standaard mistral-moderation-2603
block_on_errornaast moderation_llm_v2True: het verzoek wordt geblokkeerd als de evaluatie mislukt

U kunt meerdere objecten in de lijst plaatsen: het verzoek wordt geblokkeerd zodra een van deze objecten activeert. Elk object bevat slechts één moderation_llm_v2-configuratie. Een oudere configuratie, moderation_llm_v1, bestaat nog in de SDK met categorieën van het verouderde model `mistral-moderation-2411 (verouderd per 31 maart 2026): gebruik deze niet voor nieuwe projecten.

De elf categorieën

De sleutels in custom_category_thresholds zijn vast; een andere sleutel, zoals violence of hate, correspondeert met niets:

SleutelWat het detecteert
sexualExpliciete seksuele inhoud
hate_and_discriminationHaat of discriminatie op basis van beschermde kenmerken
violence_and_threatsBeschreven, verheerlijkte of bedreigde fysieke geweld
dangerousExtreem gevaarlijk gedrag
criminalIllegale activiteiten
selfharmZelfbeschadiging, zelfmoord, eetstoornissen
healthVerzoeken om gedetailleerd of gepersonaliseerd medisch advies
financialVerzoeken om gedetailleerd of gepersonaliseerd financieel advies
lawVerzoeken om gedetailleerd of gepersonaliseerd juridisch advies
piiPersoonsgegevens die worden gevraagd of gedeeld
jailbreakingPogingen om de regels van het model te omzeilen

Les 6 komt terug op elk van deze en bespreekt de selectie van drempelwaarden.

De drie toepassingsniveaus

Dezelfde parameter wordt op drie plaatsen geaccepteerd. Uw keuze bepaalt waar uw beveiligingsbeleid leeft en wie het zou kunnen vergeten toe te passen.

Niveau 1: Een Chat Completions-verzoek

U geeft guardrails door in de aanroep chat.complete(). Elk verzoek draagt zijn eigen regels: praktisch voor exploratie, maar riskant op schaal, omdat een enkele aanroep zonder de parameter ongecontroleerd doorgaat.

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)

Use case: Prototyping, eenmalige oproepen, afstemmen van drempels.

Niveau 2: Een Conversatie

Met de Conversations API geeft u guardrails door bij de 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)

Volgende berichten worden verzonden met client.beta.conversations.append(conversation_id=conversation.conversation_id, inputs=...). Deze methode accepteert geen parameter guardrails in SDK 3.7.0 en de documentatie specificeert niet of de start-guardrails van toepassing zijn op volgende beurten. Voor gegarandeerde bescherming bij elke beurt, koppelt u guardrails aan een agent.

Use case: Eenmalige conversatie zonder agent, of het overschrijven van de guardrails van een agent voor een specifiek verzoek.

Niveau 3: Een Agent

Guardrails die worden doorgegeven aan client.beta.agents.create() worden onderdeel van de definitie van de agent. Volgens de documentatie erven alle conversaties die deze agent gebruiken ze zonder ze te hoeven herhalen. Een conversatieverzoek kan ze echter overschrijven door zijn eigen guardrails door te geven.

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

Use case: Productie, wanneer meerdere teams of services dezelfde assistent aanroepen.

Wat Guardrails retourneren

Wanneer het verzoek slaagt, bevat de API-response, naast standaardvelden, een veld guardrails: een lijst met één resultaat per guardrail. Hier is dat veld uit het documentatievoorbeeld:

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

Met ignore_other_categories ingesteld op True verschijnen alleen de categorieën die in uw drempels staan vermeld in dit resultaat. In de Python SDK exposeert een conversatie-response dit veld (conversation.guardrails). De response van chat.complete() heeft echter geen aangewezen veld hiervoor in SDK 3.7.0: deze gaat daar verloren. Als u scores wilt loggen – en het is nuttig om later te weten of uw drempels te los of te streng zijn – gebruik dan conversaties of lees de ruwe HTTP-response.

Wanneer een drempel wordt overschreden, retourneert de API een 403-fout waarvan de body de beslissing per categorie detaljeert:

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

De SDK werpt vervolgens errors.SDKError, waarbij status_code 403 is en body deze JSON bevat:

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

Deze payload stelt u in staat een blokkade toe te lichten tijdens een beroep: welke categorie, welke score, welke drempel.

Tot slot is er het gedegradeerde geval. Als de evaluatie zelf mislukt en block_on_error is True, wordt het verzoek geweigerd met foutcode 3201 en het bericht Request blocked due to error in guardrail evaluation and block_on_error is set to True. Dit is de fail-safe modus: bij twijfel blokkeren. Met block_on_error ingesteld op False (de standaardwaarde in de SDK), zou het verzoek ongecontroleerd doorgaan.

Het juiste niveau kiezen

CriteriumChat CompletionsConversatieAgent
Waar guardrails worden gedeclareerdIn elke callBij start (start)Bij creatie agent
OverervingGeenNiet gedocumenteerd voor volgende beurtenAlle agent-conversaties
Overschrijfbaar——Ja, door een conversatieverzoek
Use caseTests, drempels afstemmenEenmalige conversatieProductie

In de praktijk stemt u uw drempels af op Chat Completions-verzoeken met echte cases, en verplaatst u het beleid naar een agent zodra de code uw machine verlaat: er zullen geen vergeten calls meer zijn.

Belangrijkste punten

  • Guardrails blokkeren prompts voordat het model reageert via een 403-fout; ze controleren geen output
  • De parameter is een lijst van objecten {"block_on_error": ..., "moderation_llm_v2": {...}}, geen dictionary met enabled
  • Elf categorieën met vaste namen (hate_and_discrimination, violence_and_threats, …), elk met een drempel van 0 tot 1; 1 schakelt uit
  • Drie niveaus: chat.complete(), conversations.start(), agents.create(); agents geven hun guardrails door aan al hun conversaties
  • block_on_error=True zorgt voor fail-safe gedrag (fout 3201)