Konfigurácia ochranných mechanizmov v Pythone
Na tejto strane
Lekcia prepísaná 3. novembra 2026. Predchádzajúca verzia konfigurovala ochranné mechanizmy pomocou vymysleného slovníka (
enabled), neexistujúcich kategórií (hate,violence,unpredictable), tvrdila, že neuvedené kategórie si zachovávajú „predvolené prahové hodnoty“, a testovalae.status_code == 3201, hoci3201je kód chyby v tele odpovede, nie HTTP stavový kód. Konfigurácia teraz nasleduje oficiálny formát a kód bol overený oproti typom SDKmistralaiverzie 3.7.0. Zdroje: Moderácia a ochranné mechanizmy · Python SDK pre mistralai.
Od teórie ku kódu
Teraz už chápeš, ako fungujú ochranné mechanizmy. V tejto lekcii ich presne nakonfiguruješ: vyberieš kategórie, definuješ prahové hodnoty a ošetríš blokovania vo svojom Pythone.
Začni s nainštalovaným Mistral SDK (ochranné mechanizmy vyžadujú verziu 2 alebo novšiu) a API kľúčom načítaným z prostredia, nie hardcoded v kóde.
pip install "mistralai>=2"
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Parameter guardrails v detailoch
Parameter guardrails je zoznam. Každá položka spája možnosť block_on_error s konfiguráciou moderation_llm_v2, ktorá sama obsahuje prahové hodnoty, možnosť ignore_other_categories a akciu:
from mistralai.client.models import GuardrailConfigTypedDict
GUARDRAILS: list[GuardrailConfigTypedDict] = [
{
# Blokovať, ak samotné vyhodnotenie zlyhá
"block_on_error": True,
"moderation_llm_v2": {
# Prahové hodnoty pre kategórie, od 0 do 1 (1 kategóriu vypne)
"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,
# Akcia pri prekročení prahu
"action": "block",
},
}
]
Predvolený model moderácie je mistral-moderation-2603; voliteľný kľúč model_name ti umožňuje špecifikovať iný.
Anotácia list[GuardrailConfigTypedDict] nie je povinná, ale oplatí sa ju použiť: SDK popisuje každý povolený kľúč, takže kontrola typov ako pyright alebo mypy upozorní na preklep v kategórii (violence namiesto violence_and_threats), ktorý by samotné API neodhalilo.
custom_category_thresholds
Toto je srdce konfigurácie. Každá kategória dostane prahovú hodnotu medzi 0 a 1, ktorá sa porovná so skóre prideleným klasifikátorom promptu. Čím nižšia prahová hodnota, tým viac filter blokuje, čo so sebou nesie riziko zamietnutia legitímnych požiadaviek. Prahová hodnota 1 kategóriu explicitne vypne. Mistral nezverejňuje odporúčanú mriežku hodnôt: tieto hodnoty musíš kalibrovať na vlastných príkladoch (lekcia 7).
Hodnoty dávajú zmysel len v kontexte tvojej aplikácie. Verejne dostupný chatbot uzamkne citlivé kategórie na najnižšie nastavenia, zatiaľ čo interný nástroj pre zdravotníckych pracovníkov musí povoľovať lekárske otázky, pričom zostáva prísny na osobné údaje.
# Verejný chatbot: veľmi nízke prahy
public_thresholds = {
"sexual": 0.1,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.1,
"criminal": 0.1,
"selfharm": 0.1,
}
# Interný lekársky nástroj: health vypnuté, PII stále monitorované
medical_thresholds = {
"sexual": 0.2,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.3,
"health": 1, # vypne kategóriu: lekárske otázky sú hlavnou funkciou nástroja
"pii": 0.1,
}
Kategórie, ktoré neuvedieš
Čo sa stane s kategóriami chýbajúcimi v custom_category_thresholds? Dokumentácia to explicitne neuvádza, ale jej príklad blokovania je výrečný: neuvedené kategórie sa tam objavujú s prahovou hodnotou 1.0, zaznamenané, ale neúčinné. Nespoliehaj sa na predvolenú prahovú hodnotu: uveď každú kategóriu, ktorá má mať schopnosť blokovať.
Možnosť ignore_other_categories riadi len to, čo sa vyhodnotí a vráti. Ak je nastavená na False, vo výsledku sa objavia všetky vyhodnotené kategórie; ak je True, vyhodnotia sa len tie, ktoré si uviedol.
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, # vyhodnotí len tieto dve kategórie
"action": "block",
},
}
]
Upozornenie: s touto konfiguráciou by pokus o jailbreak alebo požiadavka na osobné údaje prešli bez kontroly. Zoznam obmedzuj len z konkrétneho dôvodu.
Kompletný príklad: chatbot s ochrannými mechanizmami
Tu je minimálna funkcia: odošle správu s úplnou konfiguráciou a zmení blokovanie na čitateľnú odpoveď pre používateľa.
from mistralai.client import errors
def chat_securise(message_utilisateur: str) -> str:
"""Odošle správu chránenú ochrannými mechanizmami."""
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 "Prepáč, túto požiadavku nie je možné spracovať."
raise
contenu = response.choices[0].message.content
return contenu if isinstance(contenu, str) else ""
print(chat_securise("Explain machine learning to me"))
Dve poznámky. message.content môže byť reťazec alebo zoznam častí v závislosti od modelu, preto je potrebná kontrola isinstance. A odpoveď z chat.complete() v SDK 3.7.0 nezverejňuje skóre ochranných mechanizmov: na ich logovanie použij Conversations API, ktorého odpoveď ich nesie v poli guardrails.
Čisté ošetrenie chýb pri blokovaní
Musíš rozlíšiť dva typy zlyhaní, ktoré si vyžadujú odlišnú správu aj odlišné upozornenie: blokovanie podľa pravidiel obsahu, ktoré vráti HTTP stavový kód 403, a zlyhanie vyhodnotenia moderácie so zapnutým block_on_error, ktoré telo odpovede signalizuje kódom 3201. Obe prichádzajú ako errors.SDKError, ktorého body obsahuje JSON vrátený API:
import json
from typing import Any
from mistralai.client import errors
def chat_avec_gestion_erreurs(message_utilisateur: str) -> dict[str, Any]:
"""Chat, ktorý rozlišuje medzi blokovaním podľa pravidiel a zlyhaním moderácie."""
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": "Služba moderácie nie je dostupná. Požiadavka bola preventívne zablokovaná.",
}
if e.status_code == 403:
decisions = corps["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
return {
"status": "blocked",
"content": "Tvoja správa bola zablokovaná našou bezpečnostnou politikou.",
"categories": [nom for nom, d in decisions.items() if d["violated"]],
}
raise
return {"status": "ok", "content": response.choices[0].message.content}
Najprv skontroluj kód 3201, pretože dokumentácia nešpecifikuje HTTP stav pre túto chybu. Porušené kategórie pochádzajú z decisions, kde každá položka poskytuje threshold, score a violated: toto je to, čo budeš logovať, aby si vysvetlil blokovanie.
Najlepšie postupy konfigurácie
Začni prísne a potom uvoľňuj. Nízke prahy pri spustení ti pomôžu odhaliť falošne pozitívne výsledky, keď je objem ešte zvládnuteľný, a každé zvýšenie sa rozhoduje na základe pozorovaných prípadov, nie intuície:
# Fáza 1: spustenie (veľmi prísne)
phase1 = {"hate_and_discrimination": 0.1, "violence_and_threats": 0.1, "criminal": 0.1}
# Fáza 2: po analýze falošne pozitívnych výsledkov
phase2 = {"hate_and_discrimination": 0.15, "violence_and_threats": 0.25, "criminal": 0.1}
# Fáza 3: stabilná produkcia
phase3 = {"hate_and_discrimination": 0.2, "violence_and_threats": 0.3, "criminal": 0.15}
Tieto hodnoty ilustrujú prístup; tvoje vyplynú z tvojich vlastných meraní. V produkcii nechaj block_on_error nastavené na True: jeho predvolená hodnota v SDK je False a zlyhanie moderácie by potom prepustilo neoverený obsah. Nakoniec, dokumentácia varuje, že model moderácie sa vyvíja: politiky založené na skóre môžu vyžadovať recalibráciu.
Kľúčové poznatky
guardrailsje zoznam objektov{"block_on_error": ..., "moderation_llm_v2": {...}}- Vnútri
moderation_llm_v2:custom_category_thresholds,ignore_other_categories,actiona voliteľnemodel_name - Prahové hodnoty od
0do1; nižšia znamená prísnejšie;1kategóriu vypne. Uveď každú kategóriu, ktorá má blokovať - Blokovanie vyvolá
errors.SDKErrorsstatus_code == 403; zlyhanie sblock_on_errornesie v tele kód3201 - V produkcii udržuj
block_on_error=True, pretože predvolená hodnota jeFalse