Custom Guardrails: Bloker før modellen
På denne side
Lektion omskrevet den 3. november 2026. Den tidligere version beskrev en fiktiv
guardrails-parameter (en ordbog medenabled), ikke-eksisterende kategorier (hate,violence), en manglendeconversation.send()-metode i SDK’en og imaginære JSON-svar. Det officielle format er en liste medmoderation_llm_v2-konfigurationer, og svarerne nedenfor matcher dokumentationen. Koden er verificeret modmistralaiSDK-types version 3.7.0. Kilder: Moderation & Guardrailing · mistralai Python SDK.
Princippet bag Custom Guardrails
Mistrals Custom Guardrails fungerer som et input-filter: de analyserer brugerens prompt, før den når generationsmodellen. Hvis indholdet overskrider en tærskel, du har defineret, bliver anmodningen blokeret med en HTTP 403-fejl. Modellen ser aldrig den problematiske prompt.
Husk på to begrænsninger fra starten. For det første modererer guardrails kun input; de tjekker ikke, hvad modellen genererer. Det er Moderation API’ens rolle (Lektion 5). For det andet erstatter de arbejde, du ellers skulle kode selv: at kalde Moderation API’en, sammenligne scorer med dine tærskler og afvise anmodningen.
Sådan fungerer det
Når du tilføjer guardrails til en anmodning, er flowet på Mistrals side som følger:
- Din applikation sender anmodningen med parameteren
guardrails. - Klassificeren
mistral-moderation-2603scorer prompten i hver kategori. - Hvis en score overskrider sin tærskel, returnerer API’en en
403-fejl, og modellen kaldes ikke. - Ellers behandler modellen anmodningen normalt.
- Svaret indeholder et felt
guardrailsmed de evaluerede scorer.
Flow: prompt → [mistral-moderation-2603] → score > tærskel? → 403 (blokeret)
→ ellers → [LLM] → svar + scorer
Beslutningen baseres på en score sammenlignet med en tærskel, som du sætter kategori for kategori mellem 0 og 1. En lav tærskel blokerer mere indhold; en tærskel på 1 deaktiverer eksplicit kategorien.
Formatet for parameteren guardrails
Parameteren er en liste. Hvert element er et objekt, der indeholder en moderation_llm_v2-konfiguration og ved siden af den indstillingen block_on_error:
guardrails = [
{
"block_on_error": True, # bloker hvis selve moderationen fejler
"moderation_llm_v2": {
"custom_category_thresholds": {
"jailbreaking": 0.3,
"criminal": 0.2,
},
"ignore_other_categories": False,
"action": "block",
},
}
]
| Nøgle | Placering | Rolle |
|---|---|---|
custom_category_thresholds | inde i moderation_llm_v2 | Tærskel fra 0 til 1 per kategori; 1 deaktiverer kategorien |
ignore_other_categories | inde i moderation_llm_v2 | True: kun listede kategorier evalueres |
action | inde i moderation_llm_v2 | "block" for at afvise anmodningen, hvis en tærskel overskrides |
model_name | inde i moderation_llm_v2, valgfri | Moderationsmodel anden end standarden mistral-moderation-2603 |
block_on_error | ved siden af moderation_llm_v2 | True: anmodningen blokeres, hvis evalueringen fejler |
Du kan placere flere objekter i listen: anmodningen blokeres, så snart én af dem udløses. Hvert objekt indeholder kun én moderation_llm_v2-konfiguration. En ældre konfiguration, moderation_llm_v1, findes stadig i SDK’en med kategorier fra den forældede model mistral-moderation-2411 (forældet 31. marts 2026): brug den ikke til nye projekter.
De elleve kategorier
Nøglerne i custom_category_thresholds er fastlåste; en anden nøgle, såsom violence eller hate, svarer til ingenting:
| Nøgle | Hvad den registrerer |
|---|---|
sexual | Eksplicit seksuelt indhold |
hate_and_discrimination | Had eller diskrimination baseret på beskyttede egenskaber |
violence_and_threats | Beskrevet, herliggjort eller truet fysisk vold |
dangerous | Ekstremt farlige adfærdsmønstre |
criminal | Ulovlige aktiviteter |
selfharm | Selvskade, selvmord, spiseforstyrrelser |
health | Anmodninger om detaljeret eller personlig lægelig rådgivning |
financial | Anmodninger om detaljeret eller personlig finansiel rådgivning |
law | Anmodninger om detaljeret eller personlig juridisk rådgivning |
pii | Personlige data, der anmodes om eller deles |
jailbreaking | Forsøg på at omgå modellens regler |
Lektion 6 gennemgår hver af disse og diskuterer valget af tærskler.
De tre anvendelsesniveauer
Den samme parameter accepteres tre steder. Dit valg bestemmer, hvor din sikkerhedspolitik lever, og hvem der måske glemmer at anvende den.
Niveau 1: En Chat Completions-anmodning
Du sender guardrails i kaldet chat.complete(). Hver anmodning bærer sine egne regler: praktisk til udforskning, men risikabelt i stor skala, da et enkelt kald uden parameteren slipper igennem ukontrolleret.
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)
Anvendelsestilfælde: Prototyping, engangskald, finjustering af tærskler.
Niveau 2: En samtale
Med Conversations API’en sender du guardrails ved opstart i 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)
Efterfølgende beskeder sendes med client.beta.conversations.append(conversation_id=conversation.conversation_id, inputs=...). Denne metode accepterer ikke en guardrails-parameter i SDK 3.7.0, og dokumentationen specificerer ikke, om guardrails fra opstart gælder for efterfølgende ture. For garanteret beskyttelse ved hver tur skal du knytte guardrails til en agent.
Anvendelsestilfælde: Engangssamtale uden en agent, eller overskrivelse af en agents guardrails til en specifik anmodning.
Niveau 3: En agent
Guardrails sendt til client.beta.agents.create() bliver en del af agentens definition. Ifølge dokumentationen arver alle samtaler, der bruger denne agent, dem uden behov for at gentage dem. En samtaleanmodning kan dog overskrive dem ved at sende sine egne guardrails.
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!")
Anvendelsestilfælde: Produktion, når flere hold eller tjenester kalder den samme assistent.
Hvad guardrails returnerer
Når anmodningen består, inkluderer API-svaret – ud over standardfelter – et felt guardrails: en liste med ét resultat per guardrail. Her er dette felt fra dokumentationseksemplet:
{
"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 }
}
}
}
]
}
Med ignore_other_categories sat til True vises kun de kategorier, der er listet i dine tærskler, i dette resultat. I Python SDK’en eksponerer et samtale-svar dette felt (conversation.guardrails). Svaret fra chat.complete() har derimod intet dedikeret felt til det i SDK 3.7.0: det går tabt her. Hvis du vil logge scorer – og det er nyttigt senere at vide, om dine tærskler er for løse eller for stramme – så brug samtaler eller læs det rå HTTP-svar.
Når en tærskel overskrides, returnerer API’en en 403-fejl, hvis body detaljerer beslutningen kategori for kategori:
{
"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"
}
}
}
}
SDK’en rejser derefter errors.SDKError, hvor status_code er 403, og body indeholder denne JSON:
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}")
Denne payload giver dig mulighed for at forklare en blokering under en appel: hvilken kategori, hvilken score, hvilken tærskel.
Endelig er der det degraderede tilfælde. Hvis selve evalueringen fejler, og block_on_error er True, afvises anmodningen med fejlkode 3201 og beskeden Request blocked due to error in guardrail evaluation and block_on_error is set to True. Dette er fail-safe-tilstand: ved tvivl, bloker. Med block_on_error sat til False (dens standardværdi i SDK’en), ville anmodningen passere ukontrolleret.
Valg af det rigtige niveau
| Kriterium | Chat Completions | Samtale | Agent |
|---|---|---|---|
| Hvor guardrails erklæres | I hvert kald | Ved opstart (start) | Ved oprettelse af agent |
| Arv | Ingen | Udokumenteret for efterfølgende ture | Alle agent-samtaler |
| Kan overskrives | — | — | Ja, via en samtaleanmodning |
| Anvendelsestilfælde | Test, finjustering af tærskler | Engangssamtale | Produktion |
I praksis finjusterer du dine tærskler på Chat Completions-anmodninger ved hjælp af rigtige tilfælde og flytter derefter politikken til en agent, så snart koden forlader din maskine: så vil der ikke være flere glemte kald.
Vigtige pointer
- Guardrails blokerer prompts før modellen via en
403-fejl; de tjekker ikke output - Parameteren er en liste med objekter
{"block_on_error": ..., "moderation_llm_v2": {...}}, ikke en ordbog medenabled - Elleve kategorier med faste navne (
hate_and_discrimination,violence_and_threats, …), hver med en tærskel fra 0 til 1;1deaktiverer - Tre niveauer:
chat.complete(),conversations.start(),agents.create(); agenter giver deres guardrails videre til alle deres samtaler block_on_error=Truesikrer fail-safe-adfærd (fejl3201)