Konfigurace ochranných mechanismů v Pythonu
Na této stránce
Lekce přepsána 3. listopadu 2026. Předchozí verze konfigurovala ochranné mechanismy pomocí vymyšleného slovníku (
enabled), neexistujících kategorií (hate,violence,unpredictable), tvrdila, že neuvedené kategorie zachovávají „výchozí prahové hodnoty“, a testovalae.status_code == 3201, přestože3201je kód chyby v těle odpovědi, nikoliv HTTP stavový kód. Konfigurace nyní následuje oficiální formát a kód byl ověřen proti typům SDKmistralaiverze 3.7.0. Zdroje: Moderation & Guardrailing · mistralai Python SDK.
Od teorie ke kódu
Nyní rozumíš tomu, jak ochranné mechanismy fungují. V této lekci je přesně nakonfiguruješ: vybereš kategorie, definuješ prahové hodnoty a zpracuješ blokování ve svém Python kódu.
Začni s nainstalovaným Mistral SDK (ochranné mechanismy vyžadují verzi 2 nebo novější) a klíčem API načteným z prostředí, nikoliv natvrdo zakódovaným v kódu.
pip install "mistralai>=2"
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Parametr guardrails do detailu
Parametr guardrails je seznam. Každá položka spojuje možnost block_on_error s konfigurací moderation_llm_v2, která sama obsahuje prahové hodnoty, možnost ignore_other_categories a akci:
from mistralai.client.models import GuardrailConfigTypedDict
GUARDRAILS: list[GuardrailConfigTypedDict] = [
{
# Blokovat, pokud selže samotné vyhodnocení
"block_on_error": True,
"moderation_llm_v2": {
# Prahové hodnoty pro každou kategorii od 0 do 1 (1 kategorii 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,
# Akce při překročení prahu
"action": "block",
},
}
]
Výchozí model moderace je mistral-moderation-2603; volitelný klíč model_name ti umožňuje určit jiný.
Anotace list[GuardrailConfigTypedDict] není povinná, ale stojí za to ji použít: SDK popisuje každý povolený klíč, takže kontrola typů jako pyright nebo mypy upozorní na překlep v kategorii (violence místo violence_and_threats), který by samotné API neodhalilo.
custom_category_thresholds
Toto je srdce konfigurace. Každá kategorie dostane prahovou hodnotu mezi 0 a 1, která se porovná se skóre, které klasifikátor přiřadí promptu. Čím nižší prahová hodnota, tím více filtr blokuje, což s sebou nese riziko odmítnutí legitimních požadavků. Prahová hodnota 1 kategorii explicitně vypne. Mistral nezveřejňuje doporučenou matici hodnot: musíš je kalibrovat na vlastních příkladech (lekce 7).
Hodnoty dávají smysl pouze v kontextu tvé aplikace. Chatbot určený pro veřejnost uzamkne citlivé kategorie na nejnižší nastavení, zatímco interní nástroj pro zdravotnické pracovníky musí umožnit lékařské dotazy, ale zůstat přísný u osobních údajů.
# Veřejný chatbot: velmi nízké prahy
public_thresholds = {
"sexual": 0.1,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.1,
"criminal": 0.1,
"selfharm": 0.1,
}
# Interní lékařský nástroj: health vypnuto, PII stále monitorováno
medical_thresholds = {
"sexual": 0.2,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.3,
"health": 1, # vypne kategorii: lékařské dotazy jsou hlavní funkcí nástroje
"pii": 0.1,
}
Kategorie, které neuvedeš
Co se stane s kategoriemi chybějícími v custom_category_thresholds? Dokumentace to explicitně neuvádí, ale její příklad blokování je vypovídající: neuvedené kategorie se tam objevují s prahovou hodnotou 1.0, jsou zaznamenány, ale neúčinné. Nespoléhej na výchozí prahovou hodnotu: uveď každou kategorii, která má být schopna blokovat.
Možnost ignore_other_categories ovládá pouze to, co je vyhodnoceno a vráceno. Když je nastavena na False, všechny vyhodnocené kategorie se objeví ve výsledku; když je True, vyhodnotí se pouze ty, které jsi uvedl.
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í pouze tyto dvě kategorie
"action": "block",
},
}
]
Upozornění: s touto konfigurací by pokus o jailbreak nebo žádost o osobní údaje prošly bez kontroly. Seznam omez pouze z konkrétního důvodu.
Kompletní příklad: chatbot s ochrannými mechanismy
Zde je minimální funkce: odešle zprávu s úplnou konfigurací a změní blokování na čitelnou odpověď pro uživatele.
from mistralai.client import errors
def chat_securise(message_utilisateur: str) -> str:
"""Odešle zprávu chráněnou ochrannými mechanismy."""
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 "Omlouváme se, tento požadavek nelze zpracovat."
raise
contenu = response.choices[0].message.content
return contenu if isinstance(contenu, str) else ""
print(chat_securise("Explain machine learning to me"))
Dvě poznámky. message.content může být řetězec nebo seznam částí v závislosti na modelu, proto je zde kontrola isinstance. A odpověď z chat.complete() v SDK 3.7.0 nezveřejňuje skóre ochranných mechanismů: pro jejich logování použij Conversations API, jehož odpověď je nese v guardrails.
Čisté zpracování chyb blokování
Musíš rozlišit dvě selhání, která vyžadují odlišnou zprávu i odlišné upozornění: blokování zásadami obsahu, které vrací HTTP stavový kód 403, a selhání vyhodnocení moderace s povoleným block_on_error, které tělo odpovědi signalizuje kódem 3201. Oba případy přicházejí jako errors.SDKError, jehož body obsahuje JSON vrácený API:
import json
from typing import Any
from mistralai.client import errors
def chat_avec_gestion_erreurs(message_utilisateur: str) -> dict[str, Any]:
"""Chat, který rozlišuje blokování zásadami od selhání moderace."""
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 moderace není dostupná. Požadavek byl preventivně zablokován.",
}
if e.status_code == 403:
decisions = corps["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
return {
"status": "blocked",
"content": "Vaše zpráva byla zablokována našimi bezpečnostními zásadami.",
"categories": [nom for nom, d in decisions.items() if d["violated"]],
}
raise
return {"status": "ok", "content": response.choices[0].message.content}
Nejprve zkontroluj kód 3201, protože dokumentace neurčuje HTTP stav pro tuto chybu. Porušené kategorie pocházejí z decisions, kde každá položka uvádí threshold, score a violated: to je to, co budeš logovat, abys vysvětlil blokování.
Osvědčené postupy konfigurace
Začni restriktivně a poté uvolňuj. Nízké prahy při spuštění ti pomohou odhalit falešně pozitivní výsledky, dokud je objem stále zvládnutelný, a každé zvýšení se rozhoduje na základě pozorovaných případů, nikoliv intuice:
# Fáze 1: spuštění (velmi restriktivní)
phase1 = {"hate_and_discrimination": 0.1, "violence_and_threats": 0.1, "criminal": 0.1}
# Fáze 2: po analýze falešně pozitivních výsledků
phase2 = {"hate_and_discrimination": 0.15, "violence_and_threats": 0.25, "criminal": 0.1}
# Fáze 3: stabilní produkce
phase3 = {"hate_and_discrimination": 0.2, "violence_and_threats": 0.3, "criminal": 0.15}
Tyto hodnoty ilustrují přístup; ty tvé vyplynou z tvých vlastních měření. V produkci ponech block_on_error nastaveno na True: jeho výchozí hodnota v SDK je False a selhání moderace by pak propustilo neověřený obsah. Nakonec dokumentace varuje, že model moderace se vyvíjí: zásady založené na skóre mohou vyžadovat rekalibraci.
Klíčové poznatky
guardrailsje seznam objektů{"block_on_error": ..., "moderation_llm_v2": {...}}- Uvnitř
moderation_llm_v2:custom_category_thresholds,ignore_other_categories,actiona volitelněmodel_name - Prahové hodnoty od
0do1; nižší znamená přísnější;1kategorii vypne. Uveď každou kategorii, která má blokovat - Blokování vyvolá
errors.SDKErrorsstatus_code == 403; selhání sblock_on_errornese v těle kód3201 - V produkci udržuj
block_on_error=True, protože výchozí hodnota jeFalse