Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Vlastní ochranné mechanismy: Blokování před modelem

Lekce 2 z 12 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Princip vlastních ochranných mechanismů
  2. Jak to funguje
  3. Formát parametru guardrails
  4. Jedenáct kategorií
  5. Tři úrovně aplikace
  6. Co ochranné mechanismy vracejí
  7. Výběr správné úrovně
  8. Klíčové poznatky

Lekce přepsána 3. listopadu 2026. Předchozí verze popisovala fiktivní parametr guardrails (slovník s klíčem enabled), neexistující kategorie (hate, violence), chybějící metodu conversation.send() v SDK a imaginární odpovědi ve formátu JSON. Oficiální formát je seznam konfigurací moderation_llm_v2 a níže uvedené odpovědi odpovídají dokumentaci. Kód byl ověřen proti typům SDK mistralai verze 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:

  1. Tvoje aplikace odešle požadavek s parametrem guardrails.
  2. Klasifikátor mistral-moderation-2603 ohodnotí prompt v každé kategorii.
  3. Pokud skóre překročí svůj práh, API vrátí chybu 403 a model není zavolán.
  4. V opačném případě model zpracuje požadavek běžným způsobem.
  5. Odpověď obsahuje pole guardrails s 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_thresholdsuvnitř moderation_llm_v2Prah od 0 do 1 pro každou kategorii; 1 kategorii deaktivuje
ignore_other_categoriesuvnitř moderation_llm_v2True: vyhodnocují se pouze uvedené kategorie
actionuvnitř moderation_llm_v2"block" pro odmítnutí požadavku při překročení prahu
model_nameuvnitř moderation_llm_v2, volitelnéModerovací model jiný než výchozí mistral-moderation-2603
block_on_errorvedle moderation_llm_v2True: 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
sexualExplicitní sexuální obsah
hate_and_discriminationNenávist nebo diskriminace na základě chráněných charakteristik
violence_and_threatsPopisovaná, oslavovaná nebo hrozící fyzická násilí
dangerousExtrémně nebezpečné chování
criminalNelegální aktivity
selfharmSebepoš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
piiVyžadování nebo sdílení osobních údajů
jailbreakingPokusy 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ériumChat CompletionsKonverzaceAgent
Kde jsou ochranné mechanismy deklaroványV každém voláníPři startu (start)Při vytvoření agenta
DědičnostŽádnáNedokumentováno pro následující kolaVšechny konverzace agenta
Přepsatelnost——Ano, požadavkem na konverzaci
Případ použitíTesty, ladění prahůJednorázová konverzaceProdukce

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 s enabled
  • Jedenáct kategorií s pevnými názvy (hate_and_discrimination, violence_and_threats, …), každá s prahem od 0 do 1; 1 deaktivuje
  • 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=True zajišťuje chování fail-safe (chyba 3201)