Configureerige kaitsepiiranguid Pythonis
Sellel lehel
Õppetund kirjutati 3. novembril 2026 ümber. Eelmises versioonis konfigureeriti kaitsepiiranguid väljamõeldud sõnastiku (
enabled) ja olematute kategooriate (hate,violence,unpredictable) abil, väideti, et loetlemata kategooriad säilitavad „vaikimisi lävendid“, ning testiti tingimuste.status_code == 3201, kuigi3201on vastuse keha veakood, mitte HTTP olekukood. Konfiguratsioon järgib nüüd ametlikku formaati ja kood on kontrollitudmistralaiSDK 3.7.0 tüüpide vastu. Allikad: Moderation & Guardrailing · mistralai Python SDK.
Teooriast koodini
Sa mõistad nüüd, kuidas kaitsepiirangud toimivad. Selles õppetunnis konfigureerid need täpselt: valid oma kategooriad, määrad lävendid ja käsitled blokeeringuid oma Pythoni koodis.
Alusta Mistrali SDK installimisest (kaitsepiirangud nõuavad versiooni 2 või uuemat) ja API võtme laadimisest keskkonnamuutujatest, mitte selle otsekoodistamisest.
pip install "mistralai>=2"
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Parameeter guardrails lähemalt
Parameeter guardrails on loend. Iga element ühendab valiku block_on_error konfiguratsiooniga moderation_llm_v2, mis omakorda sisaldab lävendeid, valikut ignore_other_categories ja tegevust:
from mistralai.client.models import GuardrailConfigTypedDict
GUARDRAILS: list[GuardrailConfigTypedDict] = [
{
# Blokeeri, kui hindamine ise ebaõnnestub
"block_on_error": True,
"moderation_llm_v2": {
# Lävennid kategooria kohta, vahemikus 0 kuni 1 (1 keelab kategooria)
"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,
# Tegevus lävendi ületamisel
"action": "block",
},
}
]
Vaikimisi moderatsioonimudel on mistral-moderation-2603; valikuline võti model_name võimaldab määrata mõne muu.
Annotatsioon list[GuardrailConfigTypedDict] ei ole kohustuslik, kuid selle kasutamine on soovitatav: SDK kirjeldab iga lubatud võtit, nii et tüübikontrollija nagu pyright või mypy tuvastab valesti kirjutatud kategooria (violence asemel violence_and_threats), mida API ise ei pruugi märgata.
custom_category_thresholds
See on konfiguratsiooni süda. Iga kategooria saab lävendi vahemikus 0 kuni 1, mida võrreldakse klassifikaatori poolt sisendile omistatud skooriga. Mida madalam on lävend, seda rohkem filter blokeerib, riskides tagasi lükata õiguspäraseid päringuid. Lävend 1 keelab kategooria sõnaselgelt. Mistral ei avalda soovitatud väärtuste tabelit: pead need kalibreerima oma näidete põhjal (õppetund 7).
Väärtustel on mõtet ainult sinu rakenduse kontekstis. Avalikkusele suunatud vestlusrobot lukustab tundlikud kategooriad madalaimate seadetega, samas kui tervishoiutöötajatele mõeldud sisetööriist peab lubama meditsiinilisi küsimusi, jäädes samal ajal isikuandmete osas rangeks.
# Avalik vestlusrobot: väga madalad lävendid
public_thresholds = {
"sexual": 0.1,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.1,
"criminal": 0.1,
"selfharm": 0.1,
}
# Sisene meditsiinitööriist: tervis keelatud, PII-d jälgitakse endiselt
medical_thresholds = {
"sexual": 0.2,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.3,
"health": 1, # keelab kategooria: meditsiinilised küsimused on tööriista põhifunktsioon
"pii": 0.1,
}
Kategooriad, mida sa ei loetle
Mis juhtub kategooriatega, mida custom_category_thresholds ei sisalda? Dokumentatsioon ei ütle seda sõnaselgelt, kuid selle blokeerimise näide on kõnekas: loetlemata kategooriad ilmuvad seal lävendiga 1.0, märgitud, kuid mitteefektiivsena. Ära tugine vaikimisi lävendile: loetle iga kategooria, mis peaks suutma blokeerida.
Valik ignore_other_categories kontrollib ainult seda, mida hinnatakse ja tagastatakse. Kui see on määratud väärtusele False, ilmuvad tulemusse kõik hinnatud kategooriad; kui True, hinnatakse ainult neid, mida sa loetlesid.
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, # hindab ainult neid kahte kategooriat
"action": "block",
},
}
]
Hoiatus: selle konfiguratsiooniga pääseksid näiteks jailbreak’i katsed või isikuandmete päringud kontrollimatult läbi. Piira loendit ainult kindlal põhjusel.
Täielik näide: vestlusrobot kaitsepiirangutega
Siin on minimaalne funktsioon: see saadab sõnumi koos täieliku konfiguratsiooniga ja muudab blokeeringu kasutajale loetavaks vastuseks.
from mistralai.client import errors
def chat_securise(message_utilisateur: str) -> str:
"""Saadab kaitsepiirangutega kaitstud sõnumi."""
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 "Vabandust, seda päringut ei saa töödelda."
raise
contenu = response.choices[0].message.content
return contenu if isinstance(contenu, str) else ""
print(chat_securise("Selgita mulle masinõpet"))
Kaks märkust. message.content võib olenevalt mudelist olla kas sõne või osade loend, seega on vajalik kontroll isinstance. Ja vastus funktsioonilt chat.complete() ei avalda SDK 3.7.0 versioonis kaitsepiirangute skoore: nende logimiseks kasuta Conversations API-t, mille vastus kannab neid väljal guardrails.
Käsitle blokeerimisvigu korrektselt
Pead eristama kahte ebaõnnestumist, mis nõuavad nii erinevat sõnumit kui ka erinevat hoiatust: sisupoliitika blokeering, mis tagastab HTTP olekukoodi 403, ja moderatsiooni hindamise ebaõnnestumine lubatud block_on_error korral, millele vastuse keha viitab koodiga 3201. Mõlemad jõuavad kohale kui errors.SDKError, mille body sisaldab API tagastatud JSON-i:
import json
from typing import Any
from mistralai.client import errors
def chat_avec_gestion_erreurs(message_utilisateur: str) -> dict[str, Any]:
"""Vestlus, mis eristab poliitikablokeeringuid moderatsiooni ebaõnnestumistest."""
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": "Moderatsiooniteenus pole saadaval. Päring blokeeriti ettevaatusabinõuna.",
}
if e.status_code == 403:
decisions = corps["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
return {
"status": "blocked",
"content": "Sinu sõnum blokeeriti meie turvapoliitika poolt.",
"categories": [nom for nom, d in decisions.items() if d["violated"]],
}
raise
return {"status": "ok", "content": response.choices[0].message.content}
Kontrolli esmalt koodi 3201, kuna dokumentatsioon ei täpsusta selle vea HTTP olekut. Rikutud kategooriad pärinevad decisions-ist, kus iga kirje annab threshold, score ja violated: seda kasutad blokeeringu selgitamiseks logimisel.
Konfiguratsiooni parimad tavad
Alusta rangelt ja lõdvesta seejärel. Madalad lävendid käivitamisel aitavad tuvastada valepositiivseid tulemusi seni, kuni maht on veel hallatav, ja iga suurendamine otsustatakse vaadeldud juhtumite, mitte intuitsiooni põhjal:
# 1. etapp: käivitamine (väga range)
phase1 = {"hate_and_discrimination": 0.1, "violence_and_threats": 0.1, "criminal": 0.1}
# 2. etapp: pärast valepositiivsete tulemuste analüüsi
phase2 = {"hate_and_discrimination": 0.15, "violence_and_threats": 0.25, "criminal": 0.1}
# 3. etapp: stabiilne tootmine
phase3 = {"hate_and_discrimination": 0.2, "violence_and_threats": 0.3, "criminal": 0.15}
Need väärtused illustreerivad lähenemist; sinu omad tulenevad sinu enda mõõtmistest. Hoia tootmises block_on_error väärtusel True: selle vaikimisi väärtus SDK-s on False ja moderatsiooni ebaõnnestumine laseks siis kontrollimata sisu läbi. Lõpuks hoiatab dokumentatsioon, et moderatsioonimudel areneb: skooridel põhinevad poliitikad võivad vajada ümberkalibreerimist.
Peamised punktid
guardrailson loend objektidest{"block_on_error": ..., "moderation_llm_v2": {...}}- sees
moderation_llm_v2:custom_category_thresholds,ignore_other_categories,actionja valikuliseltmodel_name - Lävennid vahemikus
0kuni1; madalam tähendab rangemat;1keelab kategooria. Loetle iga kategooria, mis peaks blokeerima - Blokeering tõstab
errors.SDKErrorkoosstatus_code == 403; ebaõnnestumine koosblock_on_errorkannab kehas koodi3201 - Hoia tootmises
block_on_error=True, kuna vaikimisi on seeFalse