Vlastní ochranné mechanismy: Blokování před modelem
Na této stránce
Lekce přepsána 3. listopadu 2026. Předchozí verze popisovala fiktivní parametr
guardrails(slovník s klíčemenabled), neexistující kategorie (hate,violence), chybějící metoduconversation.send()v SDK a imaginární odpovědi ve formátu JSON. Oficiální formát je seznam konfiguracímoderation_llm_v2a níže uvedené odpovědi odpovídají dokumentaci. Kód byl ověřen proti typům SDKmistralaiverze 3.7.0. Zdroje: Moderation & Guardrailing · mistralai Python SDK.
Princip vlastních ochranných mechanismů
Vlastní ochranné mechanismy (Custom Guardrails) od Mistralu fungují jako filtr vstupů: analyzují prompt uživatele dříve, než se dostane k generačnímu modelu. Pokud obsah překročí jakýkoli vámi nastavený práh, je požadavek zablokován chybou HTTP 403. Model problematický prompt nikdy neuvidí.
Měj od začátku na paměti dvě omezení. Zaprvé, ochranné mechanismy moderují pouze vstup; nekontrolují to, co model vygeneruje. To je úkolem Moderation API (lekce 5). Zadruhé, nahrazují práci, kterou bys jinak musel naprogramovat sám: volání Moderation API, porovnávání skóre s vašimi prahy a odmítnutí požadavku.
Jak to funguje
Když přidáš do požadavku ochranné mechanismy, tok na straně Mistralu vypadá takto:
- Tvoje aplikace odešle požadavek s parametrem
guardrails. - Klasifikátor
mistral-moderation-2603ohodnotí prompt v každé kategorii. - Pokud skóre překročí svůj práh, API vrátí chybu
403a model není zavolán. - V opačném případě model zpracuje požadavek běžným způsobem.
- Odpověď obsahuje pole
guardrailss vyhodnocenými skóre.
Flow: prompt → [mistral-moderation-2603] → score > threshold? → 403 (blocked)
→ else → [LLM] → response + scores
Rozhodnutí závisí na skóre porovnaném s prahem, který nastavíš ty, kategorie po kategorii, v rozmezí od 0 do 1. Nízký práh blokuje více obsahu; práh 1 kategorii explicitně deaktivuje.
Formát parametru guardrails
Parametr je seznam. Každý prvek je objekt obsahující konfiguraci moderation_llm_v2 a vedle ní možnost block_on_error:
guardrails = [
{
"block_on_error": True, # blokovat, pokud selže samotná moderace
"moderation_llm_v2": {
"custom_category_thresholds": {
"jailbreaking": 0.3,
"criminal": 0.2,
},
"ignore_other_categories": False,
"action": "block",
},
}
]
| Klíč | Umístění | Role |
|---|---|---|
custom_category_thresholds | uvnitř moderation_llm_v2 | Prah od 0 do 1 pro každou kategorii; 1 kategorii deaktivuje |
ignore_other_categories | uvnitř moderation_llm_v2 | True: vyhodnocují se pouze uvedené kategorie |
action | uvnitř moderation_llm_v2 | "block" pro odmítnutí požadavku při překročení prahu |
model_name | uvnitř moderation_llm_v2, volitelné | Moderovací model jiný než výchozí mistral-moderation-2603 |
block_on_error | vedle moderation_llm_v2 | True: požadavek je zablokován, pokud vyhodnocení selže |
Do seznamu můžeš umístit více objektů: požadavek je zablokován, jakmile kterýkoli z nich spustí blokaci. Každý objekt obsahuje pouze jednu konfiguraci moderation_llm_v2. Starší konfigurace, moderation_llm_v1, stále existuje v SDK s kategoriemi z deprecated modelu mistral-moderation-2411 (zastaralý k 31. březnu 2026): nepoužívej ji pro nové projekty.
Jedenáct kategorií
Klíče v custom_category_thresholds jsou pevně dané; jiný klíč, jako violence nebo hate, nic neznamená:
| Klíč | Co detekuje |
|---|---|
sexual | Explicitní sexuální obsah |
hate_and_discrimination | Nenávist nebo diskriminace na základě chráněných charakteristik |
violence_and_threats | Popisovaná, oslavovaná nebo hrozící fyzická násilí |
dangerous | Extrémně nebezpečné chování |
criminal | Nelegální aktivity |
selfharm | Sebepoškozování, sebevražda, poruchy příjmu potravy |
health | Žádosti o podrobné nebo personalizované lékařské rady |
financial | Žádosti o podrobné nebo personalizované finanční rady |
law | Žádosti o podrobné nebo personalizované právní rady |
pii | Vyžadování nebo sdílení osobních údajů |
jailbreaking | Pokusy o obejití pravidel modelu |
Lekce 6 se ke každé z nich vrátí a probere výběr prahů.
Tři úrovně aplikace
Stejný parametr je přijímán na třech místech. Tvá volba určuje, kde žije tvá bezpečnostní politika a kdo ji může zapomenout aplikovat.
Úroveň 1: Požadavek Chat Completions
Parametr guardrails předáš ve volání chat.complete(). Každý požadavek nese svá vlastní pravidla: praktické pro experimentování, ale rizikové ve velkém měřítku, protože jediné volání bez tohoto parametru projde nekontrolovaně.
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "What is the distance from the Earth to the Moon?"}],
guardrails=[
{
"block_on_error": True,
"moderation_llm_v2": {
"custom_category_thresholds": {"sexual": 0.1, "selfharm": 0.1},
"ignore_other_categories": False,
"action": "block",
},
}
],
)
print(response.choices[0].message.content)
Případ použití: Prototypování, jednorázová volání, ladění prahů.
Úroveň 2: Konverzace
Při použití Conversations API předáš guardrails při startu, v client.beta.conversations.start():
conversation = client.beta.conversations.start(
model="mistral-large-latest",
inputs="Hello, can you help me prepare for an interview?",
guardrails=[
{
"block_on_error": True,
"moderation_llm_v2": {
"custom_category_thresholds": {
"sexual": 0.2,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.3,
"selfharm": 0.1,
},
"action": "block",
},
}
],
)
for entree in conversation.outputs:
if entree.type == "message.output":
print(entree.content)
Následné zprávy se odesílají pomocí client.beta.conversations.append(conversation_id=conversation.conversation_id, inputs=...). Tato metoda v SDK 3.7.0 parametr guardrails nepřijímá a dokumentace nespecifikuje, zda se ochranné mechanismy ze startu aplikují na následující kola konverzace. Pro zaručenou ochranu v každém kole připoj ochranné mechanismy k agentovi.
Případ použití: Jednorázová konverzace bez agenta nebo přepsání ochranných mechanismů agenta pro konkrétní požadavek.
Úroveň 3: Agent
Ochranné mechanismy předané do client.beta.agents.create() se stanou součástí definice agenta. Podle dokumentace všechny konverzace využívající tohoto agenta je zdědí, aniž by bylo nutné je opakovat. Požadavek na konverzaci je však může přepsat předáním vlastních guardrails.
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Secure Assistant",
instructions="You are a professional customer service assistant.",
guardrails=[
{
"block_on_error": True,
"moderation_llm_v2": {
"custom_category_thresholds": {
"sexual": 0.1,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.2,
"criminal": 0.1,
"selfharm": 0.1,
"jailbreaking": 0.3,
},
"ignore_other_categories": False,
"action": "block",
},
}
],
)
conversation = client.beta.conversations.start(agent_id=agent.id, inputs="Hello!")
Případ použití: Produkce, když stejný asistent volá více týmů nebo služeb.
Co ochranné mechanismy vracejí
Když požadavek projde, odpověď API obsahuje vedle standardních polí také pole guardrails: seznam s jedním výsledkem pro každý ochranný mechanismus. Zde je toto pole z příkladu v dokumentaci:
{
"guardrails": [
{
"moderation_llm_v2": {
"action": "pass",
"categories": {
"sexual": { "score": 0.03, "violated": false },
"selfharm": { "score": 0.05, "violated": false },
"violence_and_threats": { "score": 0.0, "violated": false },
"hate_and_discrimination": { "score": 0.0, "violated": false }
}
}
}
]
}
Pokud je ignore_other_categories nastaveno na True, objeví se v tomto výsledku pouze kategorie uvedené ve vašich prazích. V Python SDK odpověď konverzace toto pole zpřístupňuje (conversation.guardrails). Odpověď z chat.complete() však v SDK 3.7.0 nemá pro toto pole vyhrazené místo: zde se ztrácí. Pokud chceš logovat skóre – a je užitečné vědět, zda jsou tvé prahy příliš volné nebo příliš přísné – použij konverzace nebo čti surovou HTTP odpověď.
Když je práh překročen, API vrátí chybu 403, jejíž tělo podrobně popisuje rozhodnutí kategorie po kategorii:
{
"error": { "message": "Content blocked by guardrail", "status": 403 },
"guardrails": {
"results": {
"moderation_llm_v2": {
"model_name": "mistral-moderation-2603",
"decisions": {
"sexual": { "threshold": 0.1, "score": 0.3, "violated": true },
"selfharm": { "threshold": 0.1, "score": 0.05, "violated": false }
},
"violated": true,
"action": "block"
}
}
}
}
SDK poté vyhodí errors.SDKError, kde status_code je 403 a body obsahuje tento JSON:
import json
from mistralai.client import errors
try:
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": user_message}],
guardrails=guardrails,
)
except errors.SDKError as e:
if e.status_code != 403:
raise
decisions = json.loads(e.body)["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
violated = [name for name, d in decisions.items() if d["violated"]]
print(f"Request blocked: {violated}")
Tento payload ti umožňuje vysvětlit blokaci během odvolání: která kategorie, jaké skóre, jaký práh.
Nakonec tu je degradovaný případ. Pokud samotné vyhodnocení selže a block_on_error je True, je požadavek odmítnut s kódem chyby 3201 a zprávou Request blocked due to error in guardrail evaluation and block_on_error is set to True. Jedná se o režim fail-safe: v případě pochybností blokuj. Pokud je block_on_error nastaveno na False (což je jeho výchozí hodnota v SDK), požadavek by prošel nekontrolovaně.
Výběr správné úrovně
| Kritérium | Chat Completions | Konverzace | Agent |
|---|---|---|---|
| Kde jsou ochranné mechanismy deklarovány | V každém volání | Při startu (start) | Při vytvoření agenta |
| Dědičnost | Žádná | Nedokumentováno pro následující kola | Všechny konverzace agenta |
| Přepsatelnost | — | — | Ano, požadavkem na konverzaci |
| Případ použití | Testy, ladění prahů | Jednorázová konverzace | Produkce |
V praxi si vylaď prahy na požadavcích Chat Completions pomocí reálných případů a jakmile kód opustí tvůj stroj, přesuň politiku na agenta: nedojde už k žádným zapomenutým voláním.
Klíčové poznatky
- Ochranné mechanismy blokují prompty před modelem pomocí chyby
403; nekontrolují výstup - Parametr je seznam objektů
{"block_on_error": ..., "moderation_llm_v2": {...}}, nikoli slovník senabled - Jedenáct kategorií s pevnými názvy (
hate_and_discrimination,violence_and_threats, …), každá s prahem od 0 do 1;1deaktivuje - Tři úrovně:
chat.complete(),conversations.start(),agents.create(); agenti předávají své ochranné mechanismy všem svým konverzacím block_on_error=Truezajišťuje chování fail-safe (chyba3201)