Custom Guardrails: Blokkeren voordat het model reageert
Op deze pagina
Les herschreven op 3 november 2026. De vorige versie beschreef een fictieve
guardrails-parameter (een dictionary metenabled), niet-bestaande categorieën (hate,violence), een ontbrekendeconversation.send()-methode in de SDK en denkbeeldige JSON-responses. Het officiële formaat is een lijst vanmoderation_llm_v2-configuraties en de onderstaande responses komen overeen met de documentatie. De code is geverifieerd tegen demistralaiSDK-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:
- Uw applicatie verzendt het verzoek met de parameter
guardrails. - De classifier
mistral-moderation-2603geeft de prompt een score voor elke categorie. - Als een score de drempel overschrijdt, retourneert de API een
403-fout en wordt het model niet aangeroepen. - Anders verwerkt het model het verzoek normaal.
- De response bevat een veld
guardrailsmet 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",
},
}
]
| Sleutel | Locatie | Rol |
|---|---|---|
custom_category_thresholds | binnen moderation_llm_v2 | Drempel van 0 tot 1 per categorie; 1 schakelt de categorie uit |
ignore_other_categories | binnen moderation_llm_v2 | True: alleen vermelde categorieën worden geëvalueerd |
action | binnen moderation_llm_v2 | "block" om het verzoek te weigeren als een drempel wordt overschreden |
model_name | binnen moderation_llm_v2, optioneel | Moderatiemodel anders dan de standaard mistral-moderation-2603 |
block_on_error | naast moderation_llm_v2 | True: 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:
| Sleutel | Wat het detecteert |
|---|---|
sexual | Expliciete seksuele inhoud |
hate_and_discrimination | Haat of discriminatie op basis van beschermde kenmerken |
violence_and_threats | Beschreven, verheerlijkte of bedreigde fysieke geweld |
dangerous | Extreem gevaarlijk gedrag |
criminal | Illegale activiteiten |
selfharm | Zelfbeschadiging, zelfmoord, eetstoornissen |
health | Verzoeken om gedetailleerd of gepersonaliseerd medisch advies |
financial | Verzoeken om gedetailleerd of gepersonaliseerd financieel advies |
law | Verzoeken om gedetailleerd of gepersonaliseerd juridisch advies |
pii | Persoonsgegevens die worden gevraagd of gedeeld |
jailbreaking | Pogingen 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
| Criterium | Chat Completions | Conversatie | Agent |
|---|---|---|---|
| Waar guardrails worden gedeclareerd | In elke call | Bij start (start) | Bij creatie agent |
| Overerving | Geen | Niet gedocumenteerd voor volgende beurten | Alle agent-conversaties |
| Overschrijfbaar | — | — | Ja, door een conversatieverzoek |
| Use case | Tests, drempels afstemmen | Eenmalige conversatie | Productie |
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 metenabled - Elf categorieën met vaste namen (
hate_and_discrimination,violence_and_threats, …), elk met een drempel van 0 tot 1;1schakelt uit - Drie niveaus:
chat.complete(),conversations.start(),agents.create(); agents geven hun guardrails door aan al hun conversaties block_on_error=Truezorgt voor fail-safe gedrag (fout3201)