Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Vlastné ochranné mechanizmy: Blokovanie pred modelom

Lekcia 2 z 12 Aktualizované 3. novembra 2026 Vývojár
Na tejto strane
  1. Princíp vlastných ochranných mechanizmov
  2. Ako to funguje
  3. Formát parametra guardrails
  4. Jedenásť kategórií
  5. Tri úrovne aplikácie
  6. Čo vracajú ochranné mechanizmy
  7. Výber správnej úrovne
  8. Kľúčové poznatky

Lekcia prepísaná 3. novembra 2026. Predchádzajúca verzia popisovala fiktívny parameter guardrails (slovník s kľúčom enabled), neexistujúce kategórie (hate, violence), chýbajúcu metódu conversation.send() v SDK a imaginárne JSON odpovede. Oficiálny formát je zoznam konfigurácií moderation_llm_v2 a nižšie uvedené odpovede zodpovedajú dokumentácii. Kód bol overený oproti typom SDK mistralai verzie 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:

  1. Tvoja aplikácia odošle požiadavku s parametrom guardrails.
  2. Klasifikátor mistral-moderation-2603 ohodnotí prompt v každej kategórii.
  3. Ak skóre prekročí svoj prah, API vráti chybu 403 a model sa nevyvolá.
  4. Inak model spracuje požiadavku bežným spôsobom.
  5. Odpoveď obsahuje pole guardrails s 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_thresholdsvnútri moderation_llm_v2Prah od 0 do 1 pre každú kategóriu; 1 kategóriu vypne
ignore_other_categoriesvnútri moderation_llm_v2True: vyhodnotia sa iba uvedené kategórie
actionvnútri moderation_llm_v2"block" na odmietnutie požiadavky pri prekročení prahu
model_namevnútri moderation_llm_v2, voliteľnéModel na moderáciu iný ako predvolený mistral-moderation-2603
block_on_errorvedľa moderation_llm_v2True: 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
sexualExplicitný sexuálny obsah
hate_and_discriminationNenávisť alebo diskriminácia na základe chránených charakteristík
violence_and_threatsOpísané, oslavované alebo hroziace fyzické násilie
dangerousExtrémne nebezpečné správanie
criminalNelegálne aktivity
selfharmSebapoš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
piiVyžiadané alebo zdieľané osobné údaje
jailbreakingPokusy 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ériumChat CompletionsKonverzáciaAgent
Kde sú deklarované ochranné mechanizmyV každom volaníPri štarte (start)Pri vytvorení agenta
DedičnosťŽiadnaNedokumentované pre následné koláVšetky konverzácie agenta
Prepísateľnosť——Áno, požiadavkou na konverzáciu
Prípad použitiaTesty, ladenie prahovJednorazová konverzáciaProdukcia

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 s enabled
  • Jedenásť kategórií s pevnými názvami (hate_and_discrimination, violence_and_threats, …), každá s prahom od 0 do 1; 1 ju 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=True zabezpečuje správanie fail-safe (chyba 3201)