Konfiguriranje varoval v Pythonu
Na tej strani
Lekcija je bila ponovno napisana 3. novembra 2026. Prejšnja različica je konfigurirala varovala z uporabo izmišljenega slovarja (
enabled), neobstoječih kategorij (hate,violence,unpredictable), trdila, da nenavedene kategorije ohranjajo „privzete pragove”, in testiralae.status_code == 3201, čeprav je3201koda napake v telesu odgovora, ne HTTP status. Konfiguracija zdaj sledi uradnemu formatu, koda pa je bila preverjena glede na tipe SDKmistralairazličice 3.7.0. Viri: Moderation & Guardrailing · mistralai Python SDK.
Od teorije do kode
Zdaj razumeš, kako delujejo varovala. V tej lekciji jih boš natančno konfiguriral: izbral svoje kategorije, določil pragove in obravnaval blokade v svoji kodi Python.
Začni z nameščenim SDK Mistral (varovala zahtevajo različico 2 ali novejšo) in ključem API, naloženim iz okolja, namesto da bi bil zapisan neposredno v kodi.
pip install "mistralai>=2"
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Parameter guardrails v podrobnostih
Parameter guardrails je seznam. Vsak element združuje možnost block_on_error s konfiguracijo moderation_llm_v2, ki sama vsebuje pragove, možnost ignore_other_categories in dejanje:
from mistralai.client.models import GuardrailConfigTypedDict
GUARDRAILS: list[GuardrailConfigTypedDict] = [
{
# Blokiraj, če sama evalvacija ne uspe
"block_on_error": True,
"moderation_llm_v2": {
# Pragovi na kategorijo, od 0 do 1 (1 onemogoči kategorijo)
"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,
# Dejanje ob kršitvi praga
"action": "block",
},
}
]
Privzeti model za moderacijo je mistral-moderation-2603; opcijski ključ model_name ti omogoča določitev drugega.
Anotacija list[GuardrailConfigTypedDict] ni obvezna, vendar jo je vredno uporabiti: SDK opisuje vsak dovoljeni ključ, zato bo preverjevalnik tipov, kot sta pyright ali mypy, opozoril na napačno črkovano kategorijo (violence namesto violence_and_threats), česar sam API ne bi zaznal.
custom_category_thresholds
To je srce konfiguracije. Vsaka kategorija dobi prag med 0 in 1, ki se primerja z oceno, ki jo klasifikator dodeli pozivu. Nižji kot je prag, bolj filter blokira, vendar s tveganjem zavrnitve legitimnih zahtevkov. Prag 1 izrecno onemogoči kategorijo. Mistral ne objavlja priporočene mreže vrednosti: te moraš umeriti na lastnih primerih (lekcija 7).
Vrednosti imajo smisel le v kontekstu tvoje aplikacije. Chatbot, dostopen javnosti, zaklene občutljive kategorije pri najnižjih nastavitvah, medtem ko mora interno orodje za zdravstvene delavce dovoliti zdravstvena vprašanja, hkrati pa ostati strogo pri osebnih podatkih.
# Javni chatbot: zelo nizki pragovi
public_thresholds = {
"sexual": 0.1,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.1,
"criminal": 0.1,
"selfharm": 0.1,
}
# Interno medicinsko orodje: health onemogočen, PII še vedno nadzorovan
medical_thresholds = {
"sexual": 0.2,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.3,
"health": 1, # onemogoči kategorijo: zdravstvena vprašanja so glavna funkcija orodja
"pii": 0.1,
}
Kategorije, ki jih ne navedeš
Kaj se zgodi s kategorijami, ki manjkajo v custom_category_thresholds? Dokumentacija tega ne navaja izrecno, vendar je njen primer blokiranja zgovoren: nenavedene kategorije se tam pojavijo s pragom 1.0, zabeležene, a neučinkovite. Ne zanašaj se na privzeti prag: naštej vsako kategorijo, ki mora biti sposobna blokirati.
Možnost ignore_other_categories nadzira le, kaj se ovrednoti in vrne. Ko je nastavljena na False, se v rezultatu pojavijo vse ovrednotene kategorije; ko je True, se ovrednotijo le tiste, ki si jih navedel.
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, # ovrednoti le ti dve kategoriji
"action": "block",
},
}
]
Opozorilo: s to konfiguracijo bi poskus preboja zaščite (jailbreak) ali zahtevek za osebne podatke šel skozi brez nadzora. Seznam omeji le iz specifičnega razloga.
Celoten primer: chatbot z varovali
Tukaj je minimalna funkcija: pošlje sporočilo s popolno konfiguracijo in blokado pretvori v berljiv odgovor za uporabnika.
from mistralai.client import errors
def chat_securise(message_utilisateur: str) -> str:
"""Pošlje sporočilo, zaščiteno z varovali."""
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 "Oprostite, tega zahtevka ni mogoče obdelati."
raise
contenu = response.choices[0].message.content
return contenu if isinstance(contenu, str) else ""
print(chat_securise("Explain machine learning to me"))
Dve opombi. message.content je lahko niz ali seznam delov, odvisno od modela, zato je potreben preverjek isinstance. In odgovor iz chat.complete() v SDK 3.7.0 ne razkriva ocen varoval: za njihovo beleženje uporabi API Conversations, katerega odgovor jih nosi v guardrails.
Čista obravnava napak blokiranja
Razlikovati moraš med dvema vrstama napak, ki zahtevata različno sporočilo in različno opozorilo: blokada zaradi pravil o vsebini, ki vrne HTTP status 403, in napaka pri evalvaciji moderacije z omogočenim block_on_error, ki jo telo odgovora signalizira s kodo 3201. Obe prispeteta kot errors.SDKError, katerega body vsebuje JSON, ki ga vrne API:
import json
from typing import Any
from mistralai.client import errors
def chat_avec_gestion_erreurs(message_utilisateur: str) -> dict[str, Any]:
"""Chat, ki razlikuje med blokadami zaradi pravil in napakami moderacije."""
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": "Storitev moderacije ni na voljo. Zahtevek je preventivno blokiran.",
}
if e.status_code == 403:
decisions = corps["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
return {
"status": "blocked",
"content": "Vaše sporočilo je bilo blokirano zaradi naše varnostne politike.",
"categories": [nom for nom, d in decisions.items() if d["violated"]],
}
raise
return {"status": "ok", "content": response.choices[0].message.content}
Najprej preveri kodo 3201, ker dokumentacija ne določa HTTP statusa za to napako. Kršene kategorije prihajajo iz decisions, kjer vsak vnos poda threshold, score in violated: to je tisto, kar boš beležil, da pojasniš blokado.
Najboljše prakse konfiguracije
Začni restriktivno, nato popuščaj. Nizki pragovi ob zagonu ti pomagajo odkriti lažno pozitivne rezultate, medtem ko je obseg še obvladljiv, in vsako povečanje temelji na opaženih primerih, ne na intuiciji:
# Faza 1: zagon (zelo restriktivno)
phase1 = {"hate_and_discrimination": 0.1, "violence_and_threats": 0.1, "criminal": 0.1}
# Faza 2: po analizi lažno pozitivnih rezultatov
phase2 = {"hate_and_discrimination": 0.15, "violence_and_threats": 0.25, "criminal": 0.1}
# Faza 3: stabilna proizvodnja
phase3 = {"hate_and_discrimination": 0.2, "violence_and_threats": 0.3, "criminal": 0.15}
Te vrednosti ilustrirajo pristop; tvoje bodo izhajale iz tvojih lastnih meritev. V proizvodnji ohrani block_on_error nastavljen na True: njegova privzeta vrednost v SDK je False, in napaka pri moderaciji bi potem prepustila nepreverjeno vsebino skozi. Končno, dokumentacija opozarja, da se model za moderacijo razvija: politike, ki temeljijo na ocenah, bodo morda zahtevale ponovno umerjanje.
Ključne ugotovitve
guardrailsje seznam objektov{"block_on_error": ..., "moderation_llm_v2": {...}}- Znotraj
moderation_llm_v2:custom_category_thresholds,ignore_other_categories,actionin opcijskomodel_name - Pragovi od
0do1; nižje je strožje;1onemogoči kategorijo. Naštej vsako kategorijo, ki mora blokirati - Blokada sproži
errors.SDKErrorsstatus_code == 403; napaka zblock_on_errornosi kodo3201v telesu - V proizvodnji ohrani
block_on_error=True, saj je privzetoFalse