Egyéni védőkorlátok: Blokkolás a modell előtt
Ezen az oldalon
Lecke átírva: 2026. november 3. Az előző verzió egy kitalált
guardrailsparamétert (egyenabledkulcsot tartalmazó szótárat), nem létező kategóriákat (hate,violence), egy hiányzóconversation.send()metódust az SDK-ban és képzeletbeli JSON-válaszokat írt le. A hivatalos formátum egy lista, amelymoderation_llm_v2konfigurációkat tartalmaz, és az alábbi válaszok megfelelnek a dokumentációnak. A kódot ellenőriztük amistralaiSDK 3.7.0-s verziójának típusai alapján. Források: Moderation & Guardrailing · mistralai Python SDK.
Az egyéni védőkorlátok elve
A Mistral egyéni védőkorlátjai (Custom Guardrails) bemeneti szűrőként működnek: elemzik a felhasználó promptját, mielőtt az elérné a generáló modellt. Ha a tartalom meghaladja az általad beállított küszöbértékeket bármelyik kategóriában, a kérést egy HTTP 403 hibával blokkolják. A modell soha nem látja a problémás promptot.
Tartsd észben kezdettől fogva a két korlátozást. Először is, a védőkorlátok kizárólag a bemenetet moderálják; nem ellenőrzik, mit generál a modell. Ez a Moderációs API feladata (5. lecke). Másodszor, kiváltják azt a munkát, amit egyébként neked kellene kódolnod: a Moderációs API hívását, a pontszámok összehasonlítását a saját küszöbeiddel, és a kérés elutasítását.
Hogyan működik
Amikor védőkorlátokat adsz hozzá egy kéréshez, a folyamat a Mistral oldalán a következő:
- Az alkalmazásod elküldi a kérést a
guardrailsparaméterrel. - A osztályozó (
mistral-moderation-2603) kiértékeli a promptot minden kategóriában. - Ha egy pontszám meghaladja a küszöböt, az API egy
403hibát ad vissza, és a modellt nem hívják meg. - Ellenkező esetben a modell normálisan feldolgozza a kérést.
- A válasz tartalmaz egy
guardrailsmezőt, amely a kiértékelt pontszámokat tartalmazza.
Flow: prompt → [mistral-moderation-2603] → score > threshold? → 403 (blocked)
→ else → [LLM] → response + scores
A döntés egy pontszámon alapul, amelyet egy általam beállított küszöbértékkel hasonlítanak össze, kategóriánként, 0 és 1 között. Egy alacsony küszöb több tartalmat blokkol; az 1 értékű küszöb kifejezetten letiltja a kategóriát.
A guardrails paraméter formátuma
A paraméter egy lista. Minden elem egy objektum, amely egy moderation_llm_v2 konfigurációt és mellette a block_on_error opciót tartalmazza:
guardrails = [
{
"block_on_error": True, # blokkolás, ha maga a moderáció meghiúsul
"moderation_llm_v2": {
"custom_category_thresholds": {
"jailbreaking": 0.3,
"criminal": 0.2,
},
"ignore_other_categories": False,
"action": "block",
},
}
]
| Kulcs | Helye | Szerepe |
|---|---|---|
custom_category_thresholds | a moderation_llm_v2 belül | Küszöb 0 és 1 között kategóriánként; az 1 letiltja a kategóriát |
ignore_other_categories | a moderation_llm_v2 belül | True: csak a felsorolt kategóriákat értékeli ki |
action | a moderation_llm_v2 belül | "block" a kérés elutasításához, ha egy küszöböt túllépnek |
model_name | a moderation_llm_v2 belül, opcionális | Moderációs modell az alapértelmezett mistral-moderation-2603 helyett |
block_on_error | a moderation_llm_v2 mellett | True: a kérés blokkolva lesz, ha a kiértékelés meghiúsul |
Több objektumot is elhelyezhetsz a listában: a kérés blokkolva lesz, amint bármelyikük aktiválódik (triggerel). Minden objektum csak egyetlen moderation_llm_v2 konfigurációt tartalmaz. Létezik egy régebbi konfiguráció, a moderation_llm_v1 is az SDK-ban, amely a már elavult mistral-moderation-2411 modell kategóriáit használja (elavult: 2026. március 31.): új projektekhez ne használd.
A tizenegy kategória
A custom_category_thresholds kulcsai rögzítettek; egy másik kulcs, mint például a violence vagy a hate, semminek sem felel meg:
| Kulcs | Mit észlel |
|---|---|
sexual | Explicit szexuális tartalom |
hate_and_discrimination | Gyűlölet vagy diszkrimináció védett jellemzők alapján |
violence_and_threats | Leírt, dicsőített vagy fenyegető fizikai erőszak |
dangerous | Rendkívül veszélyes viselkedések |
criminal | Illegális tevékenységek |
selfharm | Önsértés, öngyilkosság, evészavarok |
health | Részletes vagy személyre szabott orvosi tanácsadás kérése |
financial | Részletes vagy személyre szabott pénzügyi tanácsadás kérése |
law | Részletes vagy személyre szabott jogi tanácsadás kérése |
pii | Személyes adatok kérése vagy megosztása |
jailbreaking | Kísérletek a modell szabályainak kijátszására |
A 6. lecke újra tárgyalja ezeket, és megvitatja a küszöbértékek kiválasztását.
Az alkalmazás három szintje
Ugyanez a paraméter három helyen is elfogadott. A választásod határozza meg, hol él a biztonsági politikád, és ki felejtheti el alkalmazni azt.
1. szint: Chat Completions kérés
A guardrails paramétert a chat.complete() hívásban adod meg. Minden kérés magában hordozza a saját szabályait: ez gyakorlati a felfedezéshez, de kockázatos nagy léptékben, mivel egyetlen hívás is átsiklik ellenőrizetlenül a paraméter nélkül.
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)
Használati eset: Prototípuskészítés, egyszeri hívások, küszöbértékek hangolása.
2. szint: Konverzáció
A Conversations API-val a guardrails paramétert indításkor adod meg a client.beta.conversations.start() hívásban:
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)
A későbbi üzeneteket a client.beta.conversations.append(conversation_id=conversation.conversation_id, inputs=...) metódussal küldöd el. Ez a metódus nem fogad el guardrails paramétert az SDK 3.7.0 verziójában, és a dokumentáció nem specifikálja, hogy az indításkor beállított védőkorlátok vonatkoznak-e a későbbi körökre. A garantált védelem érdekében minden körben csatlakoztasd a védőkorlátokat egy ágenshez.
Használati eset: Egyszeri konverzáció ágens nélkül, vagy egy ágens védőkorlátjainak felülírása egy adott kéréshez.
3. szint: Ágens
A client.beta.agents.create() híváshoz átadott védőkorlátok az ágens definíciójának részévé válnak. A dokumentáció szerint minden konverzáció, amely ezt az agenst használja, örökli ezeket anélkül, hogy meg kellene ismételni őket. Egy konverzációs kérés azonban felülírhatja őket a saját guardrails paraméterének átadásával.
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!")
Használati eset: Éles környezet (production), amikor több csapat vagy szolgáltatás hívja meg ugyanazt az asszisztenst.
Mit adnak vissza a védőkorlátok
Amikor a kérés sikeres, az API válasz tartalmaz a szabványos mezők mellett egy guardrails mezőt is: ez egy lista, amely minden védőkorláthoz egy eredményt tartalmaz. Íme ez a mező a dokumentációs példából:
{
"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 }
}
}
}
]
}
Ha az ignore_other_categories értéke True, csak a küszöbeidben felsorolt kategóriák jelennek meg ebben az eredményben. A Python SDK-ban egy konverzációs válasz elérhetővé teszi ezt a mezőt (conversation.guardrails). A chat.complete() válasznak azonban nincs kijelölt mezője erre az SDK 3.7.0 verziójában: ott elveszik. Ha naplózni szeretnéd a pontszámokat – és hasznos tudni később, hogy a küszöbeid túl lazák vagy túl szigorúak –, használj konverzációkat, vagy olvasd ki a nyers HTTP választ.
Ha egy küszöböt túllépnek, az API egy 403 hibát ad vissza, amelynek törzse részletezi a döntést, kategóriánként:
{
"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"
}
}
}
}
Az SDK ekkor egy errors.SDKError kivételt dob, ahol a status_code 403, és a body tartalmazza ezt a JSON-t:
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}")
Ez a hasznos teher (payload) lehetővé teszi, hogy egy blokkolást megmagyarázz egy fellebbezés során: melyik kategória, milyen pontszám, milyen küszöb.
Végül ott van a degradált eset. Ha maga a kiértékelés meghiúsul, és a block_on_error értéke True, a kérést elutasítják a 3201 hibakóddal és a Request blocked due to error in guardrail evaluation and block_on_error is set to True. üzenettel. Ez a fail-safe (biztonsági hibakezelés) mód: kétség esetén blokkolj. Ha a block_on_error értéke False (ami az alapértelmezett érték az SDK-ban), a kérés ellenőrizetlenül haladna át.
A megfelelő szint kiválasztása
| Kritérium | Chat Completions | Konverzáció | Ágens |
|---|---|---|---|
| Hol deklarálják a védőkorlátokat | Minden hívásban | Indításkor (start) | Ágens létrehozásakor |
| Öröklődés | Nincs | Nem dokumentált a későbbi körökre | Minden ágens-konverzációra |
| Felülírható | — | — | Igen, egy konverzációs kéréssel |
| Használati eset | Tesztek, küszöbértékek hangolása | Egyszeri konverzáció | Éles környezet (Production) |
A gyakorlatban hangold a küszöbértékeidet Chat Completions kéréseken valós esetek segítségével, majd ahogy a kód kikerül a gépedről, helyezd át a politikát egy ágenshez: így nem lesz több elfelejtett hívás.
Főbb megállapítások
- A védőkorlátok blokkolják a promptokat mielőtt azok elérnék a modellt, egy
403hiba révén; nem ellenőrzik a kimenetet - A paraméter egy lista, amely
{"block_on_error": ..., "moderation_llm_v2": {...}}objektumokat tartalmaz, nem pedig egyenabledkulcsot tartalmazó szótárat - Tizenegy kategória rögzített nevekkel (
hate_and_discrimination,violence_and_threats, …), mindegyikhez 0 és 1 közötti küszöb tartozik; az1letiltja - Három szint:
chat.complete(),conversations.start(),agents.create(); az ágensek átadják a védőkorlátjaikat minden konverzációjuknak - A
block_on_error=Truebiztosítja a fail-safe viselkedést (3201hiba)