Konfigurera skyddsräcken i Python
På denna sida
Lektionen omskriven den 3 november 2026. Den tidigare versionen konfigurerade skyddsräcken med en påhittad ordbok (
enabled), kategorier som inte finns (hate,violence,unpredictable), påstod att olistade kategorier behöll “standardtrösklar” och testadee.status_code == 3201, trots att3201är en felkod i svarsbodyn, inte en HTTP-statuskod. Konfigurationen följer nu det officiella formatet, och koden har verifierats mot typerna imistralaiSDK 3.7.0. Källor: Moderation & Guardrailing · mistralai Python SDK.
Från teori till kod
Du förstår nu hur skyddsräcken fungerar. I denna lektion ska du konfigurera dem exakt: välj dina kategorier, definiera dina tröskelvärden och hantera blockeringar i din Python-kod.
Börja med att installera Mistral SDK (skyddsräcken kräver version 2 eller senare) och ladda en API-nyckel från miljövariabler istället för att hardkoda den.
pip install "mistralai>=2"
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Parametern guardrails i detalj
Parametern guardrails är en lista. Varje objekt parar ihop alternativet block_on_error med en konfiguration för moderation_llm_v2, som i sin tur innehåller tröskelvärden, alternativet ignore_other_categories och åtgärden:
from mistralai.client.models import GuardrailConfigTypedDict
GUARDRAILS: list[GuardrailConfigTypedDict] = [
{
# Blockera om själva utvärderingen misslyckas
"block_on_error": True,
"moderation_llm_v2": {
# Tröskelvärden per kategori, från 0 till 1 (1 inaktiverar kategorin)
"custom_category_thresholds": {
"sexual": 0.2,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.3,
"dangerous": 0.2,
"criminal": 0.1,
"selfharm": 0.1,
"health": 0.5,
"financial": 0.5,
"law": 0.5,
"pii": 0.2,
"jailbreaking": 0.1,
},
"ignore_other_categories": False,
# Åtgärd vid överskridande av tröskelvärde
"action": "block",
},
}
]
Standardmodellen för moderering är mistral-moderation-2603; den valfria nyckeln model_name låter dig ange en annan.
Annotationen list[GuardrailConfigTypedDict] är inte obligatorisk, men det lönar sig att använda den: SDK:t beskriver varje tillåten nyckel, så en typkontroll som pyright eller mypy kommer att flagga en felstavad kategori (violence istället för violence_and_threats) som API:t i sig inte skulle upptäcka.
custom_category_thresholds
Detta är hjärtat i konfigurationen. Varje kategori får ett tröskelvärde mellan 0 och 1, som jämförs med den poäng klassificeraren tilldelar prompten. Ju lägre tröskelvärde, desto mer blockerar filtret, med risken att neka legitima förfrågningar. Ett tröskelvärde på 1 inaktiverar uttryckligen kategorin. Mistral publicerar inget rekommenderat rutnät med värden: du måste kalibrera dessa på dina egna exempel (lektion 7).
Värdena får bara mening i kontexten av din applikation. En chatbot mot allmänheten låser känsliga kategorier vid de lägsta inställningarna, medan ett internt verktyg för vårdpersonal måste tillåta medicinska frågor samtidigt som det är strikt med personuppgifter.
# Offentlig chatbot: mycket låga tröskelvärden
public_thresholds = {
"sexual": 0.1,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.1,
"criminal": 0.1,
"selfharm": 0.1,
}
# Internt medicinskt verktyg: health inaktiverat, PII övervakas fortfarande
medical_thresholds = {
"sexual": 0.2,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.3,
"health": 1, # inaktiverar kategorin: medicinska frågor är verktygets kärnfunktion
"pii": 0.1,
}
Kategorier du inte listar
Vad händer med kategorier som saknas i custom_category_thresholds? Dokumentationen anger det inte uttryckligen, men dess blockeringsexempel är talande: olistade kategorier dyker där upp med ett tröskelvärde på 1.0, noterade men ineffektiva. Lita inte på ett standardtröskelvärde: lista varje kategori som ska kunna blockera.
Alternativet ignore_other_categories styr endast vad som utvärderas och returneras. När det är satt till False visas alla utvärderade kategorier i resultatet; när det är True utvärderas endast de du listat.
TARGETED_GUARDRAILS: list[GuardrailConfigTypedDict] = [
{
"block_on_error": True,
"moderation_llm_v2": {
"custom_category_thresholds": {
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.2,
},
"ignore_other_categories": True, # utvärderar endast dessa två kategorier
"action": "block",
},
}
]
Varning: med denna konfiguration skulle ett jailbreak-försök eller en begäran om personuppgifter passera okontrollerat. Begränsa listan endast av en specifik anledning.
Komplett exempel: chatbot med skyddsräcken
Här är en minimal funktion: den skickar meddelandet med full konfiguration och omvandlar en blockering till ett läsbart svar för användaren.
from mistralai.client import errors
def chat_securise(message_utilisateur: str) -> str:
"""Skickar ett meddelande skyddat av skyddsräcken."""
try:
response = client.chat.complete(
model="mistral-large-latest",
messages=[
{"role": "system", "content": "You are a professional assistant."},
{"role": "user", "content": message_utilisateur},
],
guardrails=GUARDRAILS,
)
except errors.SDKError as e:
if e.status_code == 403:
return "Tyvärr, denna förfrågan kan inte behandlas."
raise
contenu = response.choices[0].message.content
return contenu if isinstance(contenu, str) else ""
print(chat_securise("Explain machine learning to me"))
Två noteringar. message.content kan vara en sträng eller en lista med delar beroende på modellen, därav kontrollen med isinstance. Och svaret från chat.complete() exponerar inte poäng för skyddsräcken i SDK 3.7.0: för att logga dem, använd Conversations API, vars svar bär dem i guardrails.
Hantera blockeringsfel snyggt
Du måste skilja på två typer av fel som kräver varken samma meddelande eller samma varning: en blockering enligt innehållspolicy, som returnerar HTTP-statuskod 403, och ett misslyckande i modereringsutvärderingen med block_on_error aktiverat, vilket svarsbodyn signalerar med koden 3201. Båda anländer som errors.SDKError, vars body innehåller JSON:en som returneras av API:t:
import json
from typing import Any
from mistralai.client import errors
def chat_avec_gestion_erreurs(message_utilisateur: str) -> dict[str, Any]:
"""Chatt som skiljer på policyblockeringar och modereringsfel."""
try:
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": message_utilisateur}],
guardrails=GUARDRAILS,
)
except errors.SDKError as e:
try:
corps = json.loads(e.body)
except json.JSONDecodeError:
raise e
if corps.get("code") == 3201:
return {
"status": "error",
"content": "Modereringstjänsten är inte tillgänglig. Förfrågan blockerad som en försiktighetsåtgärd.",
}
if e.status_code == 403:
decisions = corps["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
return {
"status": "blocked",
"content": "Ditt meddelande blockerades av vår säkerhetspolicy.",
"categories": [nom for nom, d in decisions.items() if d["violated"]],
}
raise
return {"status": "ok", "content": response.choices[0].message.content}
Kontrollera kod 3201 först, eftersom dokumentationen inte specificerar HTTP-statusen för detta fel. Kränkta kategorier kommer från decisions, där varje post ger threshold, score och violated: detta är vad du kommer att logga för att förklara en blockering.
Bästa praxis för konfiguration
Börja restriktivt och lätta sedan upp. Låga tröskelvärden vid lanseringen hjälper dig att upptäcka falska positiva träffar medan volymen fortfarande är hanterbar, och varje ökning beslutas baserat på observerade fall snarare än intuition:
# Fas 1: lansering (mycket restriktiv)
phase1 = {"hate_and_discrimination": 0.1, "violence_and_threats": 0.1, "criminal": 0.1}
# Fas 2: efter analys av falska positiva träffar
phase2 = {"hate_and_discrimination": 0.15, "violence_and_threats": 0.25, "criminal": 0.1}
# Fas 3: stabil produktion
phase3 = {"hate_and_discrimination": 0.2, "violence_and_threats": 0.3, "criminal": 0.15}
Dessa värden illustrerar tillvägagångssättet; dina kommer från dina egna mätningar. Behåll block_on_error satt till True i produktion: dess standardvärde i SDK:t är False, och ett misslyckande i modereringen skulle då låta overifierat innehåll passera. Slutligen varnar dokumentationen för att modereringsmodellen utvecklas: policyer baserade på poäng kan kräva omkalibrering.
Viktiga punkter
guardrailsär en lista med objekt{"block_on_error": ..., "moderation_llm_v2": {...}}- Inuti
moderation_llm_v2:custom_category_thresholds,ignore_other_categories,actionoch valfrittmodel_name - Tröskelvärden från
0till1; lägre är striktare;1inaktiverar en kategori. Lista varje kategori som ska blockera - En blockering höjer
errors.SDKErrormedstatus_code == 403; ett misslyckande medblock_on_errorbär koden3201i bodyn - Behåll
block_on_error=Truei produktion, eftersom standardvärdet ärFalse