Vlastné ochranné mechanizmy: Blokovanie pred modelom
Na tejto strane
Lekcia prepísaná 3. novembra 2026. Predchádzajúca verzia popisovala fiktívny parameter
guardrails(slovník s kľúčomenabled), neexistujúce kategórie (hate,violence), chýbajúcu metóduconversation.send()v SDK a imaginárne JSON odpovede. Oficiálny formát je zoznam konfiguráciímoderation_llm_v2a nižšie uvedené odpovede zodpovedajú dokumentácii. Kód bol overený oproti typom SDKmistralaiverzie 3.7.0. Zdroje: Moderation & Guardrailing · mistralai Python SDK.
Princíp vlastných ochranných mechanizmov
Vlastné ochranné mechanizmy (Custom Guardrails) od Mistralu fungujú ako filter vstupov: analyzujú prompt používateľa skôr, než sa dostane k generačnému modelu. Ak obsah prekročí akýkoľvek vami nastavený prah, požiadavka je zablokovaná chybou HTTP 403. Model sa s problematickým promptom nikdy nestretne.
Hneď na začiatku maj na pamäti dve obmedzenia. Po prvé, ochranné mechanizmy moderujú iba vstup; nekontrolujú to, čo model vygeneruje. To je úlohou Moderation API (lekcia 5). Po druhé, nahrádzajú prácu, ktorú by si inak musel naprogramovať sám: volanie Moderation API, porovnávanie skóre s tvojimi prahmi a odmietnutie požiadavky.
Ako to funguje
Keď do požiadavky pridáš ochranné mechanizmy, tok na strane Mistralu prebieha takto:
- Tvoja aplikácia odošle požiadavku s parametrom
guardrails. - Klasifikátor
mistral-moderation-2603ohodnotí prompt v každej kategórii. - Ak skóre prekročí svoj prah, API vráti chybu
403a model sa nevyvolá. - Inak model spracuje požiadavku bežným spôsobom.
- Odpoveď obsahuje pole
guardrailss vyhodnotenými skóre.
Flow: prompt → [mistral-moderation-2603] → score > threshold? → 403 (blocked)
→ else → [LLM] → response + scores
Rozhodnutie závisí od skóre porovnaného s prahom, ktorý nastavíš ty, kategóriu po kategórii, v rozmedzí od 0 do 1. Nízky prah blokuje viac obsahu; prah 1 kategóriu explicitne vypne.
Formát parametra guardrails
Parameter je zoznam. Každý prvok je objekt obsahujúci konfiguráciu moderation_llm_v2 a vedľa nej voľbu block_on_error:
guardrails = [
{
"block_on_error": True, # blokovať, ak samotná moderácia zlyhá
"moderation_llm_v2": {
"custom_category_thresholds": {
"jailbreaking": 0.3,
"criminal": 0.2,
},
"ignore_other_categories": False,
"action": "block",
},
}
]
| Kľúč | Umiestnenie | Úloha |
|---|---|---|
custom_category_thresholds | vnútri moderation_llm_v2 | Prah od 0 do 1 pre každú kategóriu; 1 kategóriu vypne |
ignore_other_categories | vnútri moderation_llm_v2 | True: vyhodnotia sa iba uvedené kategórie |
action | vnútri moderation_llm_v2 | "block" na odmietnutie požiadavky pri prekročení prahu |
model_name | vnútri moderation_llm_v2, voliteľné | Model na moderáciu iný ako predvolený mistral-moderation-2603 |
block_on_error | vedľa moderation_llm_v2 | True: požiadavka je zablokovaná, ak vyhodnotenie zlyhá |
Do zoznamu môžeš vložiť viacero objektov: požiadavka je zablokovaná hneď, ako ktorýkoľvek z nich spustí blokovanie. Každý objekt obsahuje iba jednu konfiguráciu moderation_llm_v2. Staršia konfigurácia, moderation_llm_v1, stále existuje v SDK s kategóriami zo zastaraného modelu mistral-moderation-2411 (zastaraný od 31. marca 2026): nepoužívaj ju pre nové projekty.
Jedenásť kategórií
Kľúče v custom_category_thresholds sú pevné; iný kľúč, ako napríklad violence alebo hate, ničomu nezodpovedá:
| Kľúč | Čo detekuje |
|---|---|
sexual | Explicitný sexuálny obsah |
hate_and_discrimination | Nenávisť alebo diskriminácia na základe chránených charakteristík |
violence_and_threats | Opísané, oslavované alebo hroziace fyzické násilie |
dangerous | Extrémne nebezpečné správanie |
criminal | Nelegálne aktivity |
selfharm | Sebapoškodzovanie, samovražda, poruchy príjmu potravy |
health | Žiadosti o podrobné alebo personalizované lekárske rady |
financial | Žiadosti o podrobné alebo personalizované finančné rady |
law | Žiadosti o podrobné alebo personalizované právne rady |
pii | Vyžiadané alebo zdieľané osobné údaje |
jailbreaking | Pokusy obísť pravidlá modelu |
Lekcia 6 sa ku každej z nich vráti a diskutuje o výbere prahov.
Tri úrovne aplikácie
Ten istý parameter je akceptovaný na troch miestach. Tvoja voľba určuje, kde žije tvoja bezpečnostná politika a kto by ju mohol zabudnúť aplikovať.
Úroveň 1: Požiadavka Chat Completions
Parameter guardrails odovzdáš vo volaní chat.complete(). Každá požiadavka nesie vlastné pravidlá: praktické pre experimentovanie, ale rizikové vo veľkom meradle, keďže jediné volanie bez tohto parametra prejde 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)
Prípad použitia: Prototypovanie, jednorazové volania, ladenie prahov.
Úroveň 2: Konverzácia
Pri Conversations API odovzdáš guardrails pri štarte, 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é správy sa odosielajú pomocou client.beta.conversations.append(conversation_id=conversation.conversation_id, inputs=...). Táto metóda v SDK 3.7.0 parameter guardrails neprijíma a dokumentácia nešpecifikuje, či sa ochranné mechanizmy zo štartu aplikujú na následné kolá. Pre garantovanú ochranu v každom kole pripoj ochranné mechanizmy k agentovi.
Prípad použitia: Jednorazová konverzácia bez agenta alebo prepísanie ochranných mechanizmov agenta pre konkrétnu požiadavku.
Úroveň 3: Agent
Ochranné mechanizmy odovzdané do client.beta.agents.create() sa stanú súčasťou definície agenta. Podľa dokumentácie všetky konverzácie využívajúce tohto agenta ich zdedia bez potreby opakovať ich. Požiadavka na konverzáciu ich však môže prepísať odovzdaní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!")
Prípad použitia: Produkcia, keď viaceré tímy alebo služby volajú toho istého asistenta.
Čo vracajú ochranné mechanizmy
Keď požiadavka prejde, odpoveď API obsahuje popri štandardných poliach aj pole guardrails: zoznam s jedným výsledkom pre každý ochranný mechanizmus. Tu je toto pole z príkladu v dokumentácii:
{
"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 }
}
}
}
]
}
Pri nastavení ignore_other_categories na True sa v tomto výsledku objavia iba kategórie uvedené v tvojich prahoch. V Python SDK odpoveď konverzácie toto pole sprístupňuje (conversation.guardrails). Odpoveď z chat.complete() však v SDK 3.7.0 nemá vyhradené pole pre tieto údaje: tam sa stratia. Ak chceš logovať skóre – a je užitočné vedieť, či sú tvoje prahy príliš voľné alebo príliš prísne – používaj konverzácie alebo čítaj surovú HTTP odpoveď.
Keď je prah prekročený, API vráti chybu 403, ktorej telo podrobne opisuje rozhodnutie kategóriu po kategórii:
{
"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 následne 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 vysvetliť blokovanie počas odvolania: ktorá kategória, aké skóre, aký prah.
Nakoniec tu je degradovaný prípad. Ak samotné vyhodnotenie zlyhá a block_on_error je True, požiadavka je odmietnutá s chybovým kódom 3201 a správou Request blocked due to error in guardrail evaluation and block_on_error is set to True. Ide o režim fail-safe: v prípade pochybností blokuj. Pri nastavení block_on_error na False (jeho predvolená hodnota v SDK) by požiadavka prešla nekontrolovaná.
Výber správnej úrovne
| Kritérium | Chat Completions | Konverzácia | Agent |
|---|---|---|---|
| Kde sú deklarované ochranné mechanizmy | V každom volaní | Pri štarte (start) | Pri vytvorení agenta |
| Dedičnosť | Žiadna | Nedokumentované pre následné kolá | Všetky konverzácie agenta |
| Prepísateľnosť | — | — | Áno, požiadavkou na konverzáciu |
| Prípad použitia | Testy, ladenie prahov | Jednorazová konverzácia | Produkcia |
V praxi si prahy vylaď na požiadavkách Chat Completions pomocou reálnych prípadov a potom presuň politiku na agenta hneď, ako kód opustí tvoj stroj: už nedôjde k žiadnym zabudnutým volaniam.
Kľúčové poznatky
- Ochranné mechanizmy blokujú prompty pred modelom pomocou chyby
403; nekontrolujú výstup - Parameter je zoznam objektov
{"block_on_error": ..., "moderation_llm_v2": {...}}, nie slovník senabled - Jedenásť kategórií s pevnými názvami (
hate_and_discrimination,violence_and_threats, …), každá s prahom od 0 do 1;1ju vypne - Tri úrovne:
chat.complete(),conversations.start(),agents.create(); agenti odovzdávajú svoje ochranné mechanizmy všetkým svojim konverzáciám block_on_error=Truezabezpečuje správanie fail-safe (chyba3201)