Konfigurer guardrails i Python
På denne side
Lektionen er omskrevet den 3. november 2026. Den tidligere version konfigurerede guardrails ved hjælp af en opfundet ordbog (
enabled), ikke-eksisterende kategorier (hate,violence,unpredictable), påstod at ikke-listede kategorier beholdt “standardtærskler”, og testedee.status_code == 3201, selvom3201er en fejlkode i svar-brødteksten og ikke en HTTP-statuskode. Konfigurationen følger nu det officielle format, og koden er verificeret modmistralaiSDK 3.7.0-typerne. Kilder: Moderation & Guardrailing · mistralai Python SDK.
Fra teori til kode
Du forstår nu, hvordan guardrails fungerer. I denne lektion vil du konfigurere dem præcist: vælg dine kategorier, definer dine tærskler, og håndter blokeringer i din Python-kode.
Start med at have Mistral SDK installeret (guardrails kræver version 2 eller nyere) og en API-nøgle indlæst fra miljøvariabler i stedet for at være hardcodet.
pip install "mistralai>=2"
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Parameteren guardrails i detaljer
Parameteren guardrails er en liste. Hvert element parer indstillingen block_on_error med en konfiguration for moderation_llm_v2, som selv indeholder tærskler, indstillingen ignore_other_categories og handlingen:
from mistralai.client.models import GuardrailConfigTypedDict
GUARDRAILS: list[GuardrailConfigTypedDict] = [
{
# Bloker, hvis selve evalueringen fejler
"block_on_error": True,
"moderation_llm_v2": {
# Tærskler pr. kategori, fra 0 til 1 (1 deaktiverer kategorien)
"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,
# Handling ved overskridelse af tærskel
"action": "block",
},
}
]
Standardmodellen for moderation er mistral-moderation-2603; den valgfrie nøgle model_name lader dig specificere en anden.
Annotationen list[GuardrailConfigTypedDict] er ikke påkrævet, men det er værd at bruge den: SDK’en beskriver hver tilladt nøgle, så en typekontrollant som pyright eller mypy vil flagge en stavemåde-fejl i en kategori (violence i stedet for violence_and_threats), som API’et selv ikke ville fange.
custom_category_thresholds
Dette er hjertet i konfigurationen. Hver kategori får en tærskel mellem 0 og 1, som sammenlignes med den score, klassificeren tildeler prompten. Jo lavere tærsklen er, desto mere blokerer filteret, med risikoen for at afvise legitime forespørgsler. En tærskel på 1 deaktiverer eksplicit kategorien. Mistral offentliggør ikke et anbefalet værdigitter: du skal kalibrere disse på dine egne eksempler (lektion 7).
Værdier giver kun mening i konteksten af din applikation. En chatbot rettet mod offentligheden låser følsomme kategorier ved de laveste indstillinger, mens et internt værktøj for sundhedsfagligt personale skal tillade medicinske spørgsmål, mens det forbliver strengt omkring personlige data.
# Offentlig chatbot: meget lave tærskler
public_thresholds = {
"sexual": 0.1,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.1,
"criminal": 0.1,
"selfharm": 0.1,
}
# Internt medicinsk værktøj: health deaktiveret, PII overvåges stadig
medical_thresholds = {
"sexual": 0.2,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.3,
"health": 1, # deaktiverer kategori: medicinske spørgsmål er værktøjets kernefunktion
"pii": 0.1,
}
Kategorier, du ikke lister
Hvad sker der med kategorier, der mangler i custom_category_thresholds? Dokumentationen angiver det ikke eksplicit, men dens blokerings-eksempel er sigende: ikke-listede kategorier optræder der med en tærskel på 1.0, noteret men ineffektive. Stol ikke på en standardtærskel: list hver kategori, der skal kunne blokere.
Indstillingen ignore_other_categories styrer kun, hvad der evalueres og returneres. Når den er sat til False, vises alle evaluerede kategorier i resultatet; når den er True, evalueres kun de, du har listet.
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, # evaluerer kun disse to kategorier
"action": "block",
},
}
]
Advarsel: Med denne konfiguration ville et jailbreak-forsøg eller en anmodning om personlige data passere ukontrolleret. Begræns listen kun af en specifik årsag.
Komplet eksempel: chatbot med guardrails
Her er en minimal funktion: den sender beskeden med den fulde konfiguration og omdanner en blokering til et læsbart svar til brugeren.
from mistralai.client import errors
def chat_securise(message_utilisateur: str) -> str:
"""Sender en besked beskyttet af guardrails."""
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 "Beklager, denne anmodning kan ikke behandles."
raise
contenu = response.choices[0].message.content
return contenu if isinstance(contenu, str) else ""
print(chat_securise("Explain machine learning to me"))
To bemærkninger. message.content kan være en streng eller en liste over dele afhængigt af modellen, heraf isinstance-tjekket. Og svaret fra chat.complete() eksponerer ikke guardrail-scores i SDK 3.7.0: for at logge dem skal du bruge Conversations API, hvis svar bærer dem i guardrails.
Håndter blokeringsfejl rent
Du skal skelne mellem to fejltyper, der kræver hverken den samme besked eller den samme alarm: en blokering af indholdspolitik, som returnerer HTTP-status 403, og en fejl i moderationsevalueringen med block_on_error aktiveret, som svar-brødteksten signalerer med koden 3201. Begge ankommer som errors.SDKError, hvis body indeholder JSON’en returneret af API’et:
import json
from typing import Any
from mistralai.client import errors
def chat_avec_gestion_erreurs(message_utilisateur: str) -> dict[str, Any]:
"""Chat, der skelner mellem politik-blokeringer og moderationsfejl."""
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": "Moderationstjeneste utilgængelig. Anmodning blokeret som en forholdsregel.",
}
if e.status_code == 403:
decisions = corps["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
return {
"status": "blocked",
"content": "Din besked blev blokeret af vores sikkerhedspolitik.",
"categories": [nom for nom, d in decisions.items() if d["violated"]],
}
raise
return {"status": "ok", "content": response.choices[0].message.content}
Tjek kode 3201 først, fordi dokumentationen ikke specificerer HTTP-statussen for denne fejl. Overtrådte kategorier kommer fra decisions, hvor hver post giver threshold, score og violated: dette er det, du vil logge for at forklare en blokering.
Bedste praksis for konfiguration
Start restriktivt, og bliv derefter mere lempelig. Lave tærskler ved opstart hjælper dig med at opdage falske positiver, mens volumen stadig er håndterbar, og hver forhøjelse besluttes baseret på observerede tilfælde snarere end intuition:
# Fase 1: opstart (meget restriktiv)
phase1 = {"hate_and_discrimination": 0.1, "violence_and_threats": 0.1, "criminal": 0.1}
# Fase 2: efter analyse af falske positiver
phase2 = {"hate_and_discrimination": 0.15, "violence_and_threats": 0.25, "criminal": 0.1}
# Fase 3: stabil produktion
phase3 = {"hate_and_discrimination": 0.2, "violence_and_threats": 0.3, "criminal": 0.15}
Disse værdier illustrerer tilgangen; dine vil komme fra dine egne målinger. Hold block_on_error sat til True i produktion: dens standardværdi i SDK’en er False, og en moderationsfejl ville derefter lade ubekræftet indhold passere. Endelig advarer dokumentationen om, at moderationsmodellen udvikler sig: politikker baseret på scores kan kræve genkalibrering.
Vigtige pointer
guardrailser en liste af objekter{"block_on_error": ..., "moderation_llm_v2": {...}}- Indeni
moderation_llm_v2:custom_category_thresholds,ignore_other_categories,actionog valgfritmodel_name - Tærskler fra
0til1; lavere er strengere;1deaktiverer en kategori. List hver kategori, der skal blokere - En blokering udløser
errors.SDKErrormedstatus_code == 403; en fejl medblock_on_errorbærer kode3201i brødteksten - Hold
block_on_error=Truei produktion, da standarden erFalse