Mistral's Moderation API
Op deze pagina
Bijgewerkt op 3 november 2026. Het voorbeeldantwoord bevatte eerder niet-bestaande sleutels (
hate,violence,unpredictable); het weerspiegelt nu de elf categorieën vanmistral-moderation-2603. De uiteindelijke pipeline gebruikte eerder een verzonnen guardrail-formaat (enabled) en detecteerde blokkades door te zoeken naar “403” in de foutmelding: deze volgt nu het officiële formaat en controleerte.status_code. De presentatie van het model houdt zich aan het officiële gegevensblad, en de les introduceert Shieldstral 1.0, het moderatiemodel dat sinds augustus 2026 in openbare preview is. Code geverifieerd tegenmistralaiSDK-types versie 3.7.0. Bronnen: Moderation & Guardrailing · Mistral Moderation 2 · Shieldstral 1.0.
Content classificeren na generatie
Guardrails filteren input-prompts. Maar wat te doen met content die gegenereerd is door het model? Een onschuldige prompt kan een problematisch antwoord opleveren: een vraag van een middelbare scholier over de Tweede Wereldoorlog kan resulteren in een beschrijving die u niet zonder voorbehoud wilt weergeven. Dat is de rol van de Moderation API: content achteraf analyseren en risicoscores per categorie toekennen.
De Moderation API is uw tweede verdedigingslinie; deze vult guardrails aan om een complete beveiligingsarchitectuur te creëren, met één groot verschil: deze blokkeert niets op eigen houtje, maar informeert u.
Het Mistral Moderation 2-model
Het toegewijde moderatiemodel heet mistral-moderation-2603 (Mistral Moderation 2, versie maart 2026). Het is een gespecialiseerde classifier, onderscheiden van generatiemodellen: het schrijft geen tekst, het kent scores toe. Het officiële gegevensblad benadrukt een contextvenster van 128.000 tokens, detectie van jailbreaks en sterke prestaties op complexe meertalige content, inclusief lange conversaties. Het vervangt mistral-moderation-2411, dat op 31 maart 2026 is verouderd.
Het scoort elke tekst over 11 categorieën, met een score van 0,0 tot 1,0 per categorie. Het accepteert twee inputmodi, platte tekst of conversationeel, en de keuze tussen beide beïnvloedt de resultaatkwaliteit meer dan u wellicht verwacht.
Sinds 4 augustus 2026 bestaat er een tweede moderatiemodel in openbare preview: Shieldstral 1.0. Dit werkt anders: compact (3,8 miljard parameters) en multimodaal, classificeert het tekst en afbeeldingen op basis van beleidsvragen geformuleerd in natuurlijke taal, met een ja-of-nee-antwoord. De gewichten zijn gepubliceerd onder de Apache 2.0-licentie, wat self-hosting mogelijk maakt. Zolang het in preview blijft, is mistral-moderation-2603 het productiemodel, en het is degene die wordt gebruikt voor guardrails.
Het /v1/moderations-eindpunt
De modus voor platte tekst is het eenvoudigst: u stuurt een of meer teksten ter classificatie, zonder extra context.
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Eenvoudige tekst modereren
response = client.classifiers.moderate(
model="mistral-moderation-2603",
inputs=["Text to analyze for moderation"]
)
# Resultaten openen
for result in response.results:
print(f"Categories: {result.categories}")
print(f"Scores: {result.category_scores}")
Om complete uitwisselingen te modereren, zowel prompt als antwoord samen, biedt de conversationele modus de classifier wat hem ontbrak: de rode draad van het gesprek.
# Een complete conversatie modereren
response = client.classifiers.moderate_chat(
model="mistral-moderation-2603",
inputs=[
[
{"role": "user", "content": "How do I treat a headache?"},
{"role": "assistant", "content": "Take 1g of paracetamol..."}
]
]
)
# De classifier evalueert de volledige context
for result in response.results:
print(f"Health score: {(result.category_scores or {}).get('health', 0)}")
De conversationele modus, die het eindpunt /v1/chat/moderations aanroept, is wat Mistral aanbeveelt voor een uitwisseling: het model is getraind om de laatste beurt van het gesprek te classificeren in het licht van de voorgaande. Om het antwoord van uw assistent te modereren, plaatst u dit als laatste. De lijst van lijsten in het voorbeeld maakt het mogelijk om meerdere conversaties tegelijk te verzenden; een eenvoudige lijst met berichten volstaat voor een enkele conversatie. Dezelfde tekst kan zo een andere score ontvangen, afhankelijk van of deze een legitieme of kwaadaardige vraag beantwoordt: een dosering die wordt genoemd als antwoord op een informatieverzoek heeft niet dezelfde status als dezelfde dosering die wordt binnengesmokkeld in een uitwisseling over riskante zelfmedicatie.
Responsstructuur
Voor elke geanalyseerde tekst bevat het antwoord twee parallelle blokken: categories, booleans berekend met drempels ingesteld door Mistral op basis van zijn interne testset, en category_scores, de ruwe scores van 0,0 tot 1,0. Het onderstaande voorbeeld is illustratief, met afgeronde waarden; sommige documentatievoorbeelden tonen nog steeds de negen categorieën van het oude model, waar dangerous_and_criminal_content zowel dangerous als criminal combineerde. U zult de laatstgenoemden gebruiken, omdat ze u in staat stellen uw eigen grenzen te stellen.
{
"id": "mod-abc123",
"model": "mistral-moderation-2603",
"results": [
{
"categories": {
"sexual": false,
"hate_and_discrimination": false,
"violence_and_threats": false,
"dangerous": false,
"criminal": false,
"selfharm": false,
"health": true,
"financial": false,
"law": false,
"pii": false,
"jailbreaking": false
},
"category_scores": {
"sexual": 0.01,
"hate_and_discrimination": 0.02,
"violence_and_threats": 0.03,
"dangerous": 0.02,
"criminal": 0.01,
"selfharm": 0.01,
"health": 0.72,
"financial": 0.05,
"law": 0.08,
"pii": 0.02,
"jailbreaking": 0.01
}
}
]
}
In dit voorbeeld is alleen health gemarkeerd als true, met 0,72. Een op consumenten gerichte assistent zou dit zien als een blokkeersignaal; een tool bedoeld voor apothekers zou het zonder aarzelen doorlaten. Dezelfde score, twee tegenovergestelde beslissingen, en dat is precies waarom u met scores werkt in plaats van met booleans.
Meerdere teksten in batch modereren
De API accepteert meerdere teksten in één verzoek, wat alles verandert voor batchverwerking: het retroactief analyseren van een conversatiegeschiedenis of een commentaardatabase wordt een redelijke operatie wat het aantal calls betreft.
# Meerdere teksten modereren in één verzoek
texts = [
"First text to analyze",
"Second text to analyze",
"Third text to analyze"
]
response = client.classifiers.moderate(
model="mistral-moderation-2603",
inputs=texts
)
# Elke tekst heeft zijn eigen resultaat
for i, result in enumerate(response.results):
scores = result.category_scores or {}
max_cat = max(scores, key=lambda c: scores[c])
max_score = scores[max_cat]
print(f"Text {i+1}: max score = {max_score:.2f} ({max_cat})")
Guardrails vs Moderation API: wanneer wat te gebruiken
| Aspect | Aangepaste Guardrails | Moderation API |
|---|---|---|
| Timing | VOOR generatie | NA generatie |
| Actie | Blokkeert automatisch (403) | Geeft scores terug (u beslist) |
| Controle | Uw drempels per categorie, toegepast door Mistral | Ruwe scores, vrije logica |
| Call | Parameter van het generatieverzoek | Aparte call naar /v1/moderations |
| Use case | Gevaarlijke prompts filteren | Antwoorden classificeren |
Voorbeeld: complete pipeline
De onderstaande pipeline toont de opeenvolging van de twee mechanismen. Generatie wordt beschermd door een guardrail gericht op jailbreaking; het antwoord wordt vervolgens geclassificeerd samen met de vraag die het heeft voortgebracht, en een aangepaste beslissing treedt in werking zodra een score hoger is dan 0,5. Merk op dat de twee stappen verschillende statussen retourneren—blocked_input en blocked_output—zodat uw logs duidelijk aangeven waar het verzoek is gestopt.
from mistralai.client import errors
from mistralai.client.models import GuardrailConfigTypedDict
GUARDRAIL_JAILBREAK: list[GuardrailConfigTypedDict] = [
{
"block_on_error": True,
"moderation_llm_v2": {
"custom_category_thresholds": {"jailbreaking": 0.1},
"action": "block",
},
}
]
def secure_pipeline(user_message: str) -> dict:
"""Pipeline met guardrails (input) en moderatie (output)."""
# Stap 1: genereren met guardrails
try:
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": user_message}],
guardrails=GUARDRAIL_JAILBREAK,
)
except errors.SDKError as e:
if e.status_code == 403:
return {"status": "blocked_input", "content": None}
raise
generated = response.choices[0].message.content
if not isinstance(generated, str):
return {"status": "error", "content": None}
# Stap 2: de output modereren, in de context van de vraag
moderation = client.classifiers.moderate_chat(
model="mistral-moderation-2603",
inputs=[
{"role": "user", "content": user_message},
{"role": "assistant", "content": generated},
],
)
scores = moderation.results[0].category_scores or {}
if max(scores.values(), default=0.0) > 0.5:
return {"status": "blocked_output", "scores": scores}
return {"status": "ok", "content": generated, "scores": scores}
Belangrijkste punten
- De Moderation API gebruikt het
mistral-moderation-2603-model om content te classificeren - Twee modi beschikbaar: platte tekst en conversationeel
- Scores lopen van 0,0 tot 1,0—u definieert uw eigen beslissingsdrempels
- De conversationele modus is nauwkeuriger omdat deze rekening houdt met de context
- Combineer guardrails (input) + moderatie (output) voor verdediging in de diepte