Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Egyéni védőkorlátok: Blokkolás a modell előtt

2. lecke 12 közül Frissítve 2026. november 3. Fejlesztő
Ezen az oldalon
  1. Az egyéni védőkorlátok elve
  2. Hogyan működik
  3. A guardrails paraméter formátuma
  4. A tizenegy kategória
  5. Az alkalmazás három szintje
  6. Mit adnak vissza a védőkorlátok
  7. A megfelelő szint kiválasztása
  8. Főbb megállapítások

Lecke átírva: 2026. november 3. Az előző verzió egy kitalált guardrails paramétert (egy enabled kulcsot 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, amely moderation_llm_v2 konfigurációkat tartalmaz, és az alábbi válaszok megfelelnek a dokumentációnak. A kódot ellenőriztük a mistralai SDK 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ő:

  1. Az alkalmazásod elküldi a kérést a guardrails paraméterrel.
  2. A osztályozó (mistral-moderation-2603) kiértékeli a promptot minden kategóriában.
  3. Ha egy pontszám meghaladja a küszöböt, az API egy 403 hibát ad vissza, és a modellt nem hívják meg.
  4. Ellenkező esetben a modell normálisan feldolgozza a kérést.
  5. A válasz tartalmaz egy guardrails mező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",
        },
    }
]
KulcsHelyeSzerepe
custom_category_thresholdsa moderation_llm_v2 belülKüszöb 0 és 1 között kategóriánként; az 1 letiltja a kategóriát
ignore_other_categoriesa moderation_llm_v2 belülTrue: csak a felsorolt kategóriákat értékeli ki
actiona moderation_llm_v2 belül"block" a kérés elutasításához, ha egy küszöböt túllépnek
model_namea moderation_llm_v2 belül, opcionálisModerációs modell az alapértelmezett mistral-moderation-2603 helyett
block_on_errora moderation_llm_v2 mellettTrue: 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:

KulcsMit észlel
sexualExplicit szexuális tartalom
hate_and_discriminationGyűlölet vagy diszkrimináció védett jellemzők alapján
violence_and_threatsLeírt, dicsőített vagy fenyegető fizikai erőszak
dangerousRendkívül veszélyes viselkedések
criminalIllegális tevékenységek
selfharmÖnsértés, öngyilkosság, evészavarok
healthRészletes vagy személyre szabott orvosi tanácsadás kérése
financialRészletes vagy személyre szabott pénzügyi tanácsadás kérése
lawRészletes vagy személyre szabott jogi tanácsadás kérése
piiSzemélyes adatok kérése vagy megosztása
jailbreakingKí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ériumChat CompletionsKonverzációÁgens
Hol deklarálják a védőkorlátokatMinden hívásbanIndításkor (start)Ágens létrehozásakor
ÖröklődésNincsNem dokumentált a későbbi körökreMinden ágens-konverzációra
Felülírható——Igen, egy konverzációs kéréssel
Használati esetTesztek, küszöbértékek hangolásaEgyszeri 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 403 hiba révén; nem ellenőrzik a kimenetet
  • A paraméter egy lista, amely {"block_on_error": ..., "moderation_llm_v2": {...}} objektumokat tartalmaz, nem pedig egy enabled kulcsot 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; az 1 letiltja
  • 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=True biztosítja a fail-safe viselkedést (3201 hiba)