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

Konfigurace ochranných mechanismů v Pythonu

Lekce 3 z 12 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Od teorie ke kódu
  2. Parametr guardrails do detailu
  3. Kompletní příklad: chatbot s ochrannými mechanismy
  4. Čisté zpracování chyb blokování
  5. Osvědčené postupy konfigurace
  6. Klíčové poznatky

Lekce přepsána 3. listopadu 2026. Předchozí verze konfigurovala ochranné mechanismy pomocí vymyšleného slovníku (enabled), neexistujících kategorií (hate, violence, unpredictable), tvrdila, že neuvedené kategorie zachovávají „výchozí prahové hodnoty“, a testovala e.status_code == 3201, přestože 3201 je kód chyby v těle odpovědi, nikoliv HTTP stavový kód. Konfigurace nyní následuje oficiální formát a kód byl ověřen proti typům SDK mistralai verze 3.7.0. Zdroje: Moderation & Guardrailing · mistralai Python SDK.

Od teorie ke kódu

Nyní rozumíš tomu, jak ochranné mechanismy fungují. V této lekci je přesně nakonfiguruješ: vybereš kategorie, definuješ prahové hodnoty a zpracuješ blokování ve svém Python kódu.

Začni s nainstalovaným Mistral SDK (ochranné mechanismy vyžadují verzi 2 nebo novější) a klíčem API načteným z prostředí, nikoliv natvrdo zakódovaným v kódu.

pip install "mistralai>=2"
import os

from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

Parametr guardrails do detailu

Parametr guardrails je seznam. Každá položka spojuje možnost block_on_error s konfigurací moderation_llm_v2, která sama obsahuje prahové hodnoty, možnost ignore_other_categories a akci:

from mistralai.client.models import GuardrailConfigTypedDict

GUARDRAILS: list[GuardrailConfigTypedDict] = [
    {
        # Blokovat, pokud selže samotné vyhodnocení
        "block_on_error": True,
        "moderation_llm_v2": {
            # Prahové hodnoty pro každou kategorii od 0 do 1 (1 kategorii vypne)
            "custom_category_thresholds": {
                "sexual": 0.2,
                "hate_and_discrimination": 0.1,
                "violence_and_threats": 0.3,
                "dangerous": 0.2,
                "criminal": 0.1,
                "selfharm": 0.1,
                "health": 0.5,
                "financial": 0.5,
                "law": 0.5,
                "pii": 0.2,
                "jailbreaking": 0.1,
            },
            "ignore_other_categories": False,
            # Akce při překročení prahu
            "action": "block",
        },
    }
]

Výchozí model moderace je mistral-moderation-2603; volitelný klíč model_name ti umožňuje určit jiný.

Anotace list[GuardrailConfigTypedDict] není povinná, ale stojí za to ji použít: SDK popisuje každý povolený klíč, takže kontrola typů jako pyright nebo mypy upozorní na překlep v kategorii (violence místo violence_and_threats), který by samotné API neodhalilo.

custom_category_thresholds

Toto je srdce konfigurace. Každá kategorie dostane prahovou hodnotu mezi 0 a 1, která se porovná se skóre, které klasifikátor přiřadí promptu. Čím nižší prahová hodnota, tím více filtr blokuje, což s sebou nese riziko odmítnutí legitimních požadavků. Prahová hodnota 1 kategorii explicitně vypne. Mistral nezveřejňuje doporučenou matici hodnot: musíš je kalibrovat na vlastních příkladech (lekce 7).

Hodnoty dávají smysl pouze v kontextu tvé aplikace. Chatbot určený pro veřejnost uzamkne citlivé kategorie na nejnižší nastavení, zatímco interní nástroj pro zdravotnické pracovníky musí umožnit lékařské dotazy, ale zůstat přísný u osobních údajů.

# Veřejný chatbot: velmi nízké prahy
public_thresholds = {
    "sexual": 0.1,
    "hate_and_discrimination": 0.1,
    "violence_and_threats": 0.1,
    "criminal": 0.1,
    "selfharm": 0.1,
}

# Interní lékařský nástroj: health vypnuto, PII stále monitorováno
medical_thresholds = {
    "sexual": 0.2,
    "hate_and_discrimination": 0.1,
    "violence_and_threats": 0.3,
    "health": 1,   # vypne kategorii: lékařské dotazy jsou hlavní funkcí nástroje
    "pii": 0.1,
}

Kategorie, které neuvedeš

Co se stane s kategoriemi chybějícími v custom_category_thresholds? Dokumentace to explicitně neuvádí, ale její příklad blokování je vypovídající: neuvedené kategorie se tam objevují s prahovou hodnotou 1.0, jsou zaznamenány, ale neúčinné. Nespoléhej na výchozí prahovou hodnotu: uveď každou kategorii, která má být schopna blokovat.

Možnost ignore_other_categories ovládá pouze to, co je vyhodnoceno a vráceno. Když je nastavena na False, všechny vyhodnocené kategorie se objeví ve výsledku; když je True, vyhodnotí se pouze ty, které jsi uvedl.

TARGETED_GUARDRAILS: list[GuardrailConfigTypedDict] = [
    {
        "block_on_error": True,
        "moderation_llm_v2": {
            "custom_category_thresholds": {
                "hate_and_discrimination": 0.1,
                "violence_and_threats": 0.2,
            },
            "ignore_other_categories": True,  # vyhodnotí pouze tyto dvě kategorie
            "action": "block",
        },
    }
]

Upozornění: s touto konfigurací by pokus o jailbreak nebo žádost o osobní údaje prošly bez kontroly. Seznam omez pouze z konkrétního důvodu.

Kompletní příklad: chatbot s ochrannými mechanismy

Zde je minimální funkce: odešle zprávu s úplnou konfigurací a změní blokování na čitelnou odpověď pro uživatele.

from mistralai.client import errors


def chat_securise(message_utilisateur: str) -> str:
    """Odešle zprávu chráněnou ochrannými mechanismy."""
    try:
        response = client.chat.complete(
            model="mistral-large-latest",
            messages=[
                {"role": "system", "content": "You are a professional assistant."},
                {"role": "user", "content": message_utilisateur},
            ],
            guardrails=GUARDRAILS,
        )
    except errors.SDKError as e:
        if e.status_code == 403:
            return "Omlouváme se, tento požadavek nelze zpracovat."
        raise

    contenu = response.choices[0].message.content
    return contenu if isinstance(contenu, str) else ""


print(chat_securise("Explain machine learning to me"))

Dvě poznámky. message.content může být řetězec nebo seznam částí v závislosti na modelu, proto je zde kontrola isinstance. A odpověď z chat.complete() v SDK 3.7.0 nezveřejňuje skóre ochranných mechanismů: pro jejich logování použij Conversations API, jehož odpověď je nese v guardrails.

Čisté zpracování chyb blokování

Musíš rozlišit dvě selhání, která vyžadují odlišnou zprávu i odlišné upozornění: blokování zásadami obsahu, které vrací HTTP stavový kód 403, a selhání vyhodnocení moderace s povoleným block_on_error, které tělo odpovědi signalizuje kódem 3201. Oba případy přicházejí jako errors.SDKError, jehož body obsahuje JSON vrácený API:

import json
from typing import Any

from mistralai.client import errors


def chat_avec_gestion_erreurs(message_utilisateur: str) -> dict[str, Any]:
    """Chat, který rozlišuje blokování zásadami od selhání moderace."""
    try:
        response = client.chat.complete(
            model="mistral-large-latest",
            messages=[{"role": "user", "content": message_utilisateur}],
            guardrails=GUARDRAILS,
        )
    except errors.SDKError as e:
        try:
            corps = json.loads(e.body)
        except json.JSONDecodeError:
            raise e

        if corps.get("code") == 3201:
            return {
                "status": "error",
                "content": "Služba moderace není dostupná. Požadavek byl preventivně zablokován.",
            }
        if e.status_code == 403:
            decisions = corps["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
            return {
                "status": "blocked",
                "content": "Vaše zpráva byla zablokována našimi bezpečnostními zásadami.",
                "categories": [nom for nom, d in decisions.items() if d["violated"]],
            }
        raise

    return {"status": "ok", "content": response.choices[0].message.content}

Nejprve zkontroluj kód 3201, protože dokumentace neurčuje HTTP stav pro tuto chybu. Porušené kategorie pocházejí z decisions, kde každá položka uvádí threshold, score a violated: to je to, co budeš logovat, abys vysvětlil blokování.

Osvědčené postupy konfigurace

Začni restriktivně a poté uvolňuj. Nízké prahy při spuštění ti pomohou odhalit falešně pozitivní výsledky, dokud je objem stále zvládnutelný, a každé zvýšení se rozhoduje na základě pozorovaných případů, nikoliv intuice:

# Fáze 1: spuštění (velmi restriktivní)
phase1 = {"hate_and_discrimination": 0.1, "violence_and_threats": 0.1, "criminal": 0.1}

# Fáze 2: po analýze falešně pozitivních výsledků
phase2 = {"hate_and_discrimination": 0.15, "violence_and_threats": 0.25, "criminal": 0.1}

# Fáze 3: stabilní produkce
phase3 = {"hate_and_discrimination": 0.2, "violence_and_threats": 0.3, "criminal": 0.15}

Tyto hodnoty ilustrují přístup; ty tvé vyplynou z tvých vlastních měření. V produkci ponech block_on_error nastaveno na True: jeho výchozí hodnota v SDK je False a selhání moderace by pak propustilo neověřený obsah. Nakonec dokumentace varuje, že model moderace se vyvíjí: zásady založené na skóre mohou vyžadovat rekalibraci.

Klíčové poznatky

  • guardrails je seznam objektů {"block_on_error": ..., "moderation_llm_v2": {...}}
  • Uvnitř moderation_llm_v2: custom_category_thresholds, ignore_other_categories, action a volitelně model_name
  • Prahové hodnoty od 0 do 1; nižší znamená přísnější; 1 kategorii vypne. Uveď každou kategorii, která má blokovat
  • Blokování vyvolá errors.SDKError s status_code == 403; selhání s block_on_error nese v těle kód 3201
  • V produkci udržuj block_on_error=True, protože výchozí hodnota je False