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

Konfigurácia ochranných mechanizmov v Pythone

Lekcia 3 z 12 Aktualizované 3. novembra 2026 Vývojár
Na tejto strane
  1. Od teórie ku kódu
  2. Parameter guardrails v detailoch
  3. Kompletný príklad: chatbot s ochrannými mechanizmami
  4. Čisté ošetrenie chýb pri blokovaní
  5. Najlepšie postupy konfigurácie
  6. Kľúčové poznatky

Lekcia prepísaná 3. novembra 2026. Predchádzajúca verzia konfigurovala ochranné mechanizmy pomocou vymysleného slovníka (enabled), neexistujúcich kategórií (hate, violence, unpredictable), tvrdila, že neuvedené kategórie si zachovávajú „predvolené prahové hodnoty“, a testovala e.status_code == 3201, hoci 3201 je kód chyby v tele odpovede, nie HTTP stavový kód. Konfigurácia teraz nasleduje oficiálny formát a kód bol overený oproti typom SDK mistralai verzie 3.7.0. Zdroje: Moderácia a ochranné mechanizmy · Python SDK pre mistralai.

Od teórie ku kódu

Teraz už chápeš, ako fungujú ochranné mechanizmy. V tejto lekcii ich presne nakonfiguruješ: vyberieš kategórie, definuješ prahové hodnoty a ošetríš blokovania vo svojom Pythone.

Začni s nainštalovaným Mistral SDK (ochranné mechanizmy vyžadujú verziu 2 alebo novšiu) a API kľúčom načítaným z prostredia, nie hardcoded v kóde.

pip install "mistralai>=2"
import os

from mistralai.client import Mistral

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

Parameter guardrails v detailoch

Parameter guardrails je zoznam. Každá položka spája možnosť block_on_error s konfiguráciou moderation_llm_v2, ktorá sama obsahuje prahové hodnoty, možnosť ignore_other_categories a akciu:

from mistralai.client.models import GuardrailConfigTypedDict

GUARDRAILS: list[GuardrailConfigTypedDict] = [
    {
        # Blokovať, ak samotné vyhodnotenie zlyhá
        "block_on_error": True,
        "moderation_llm_v2": {
            # Prahové hodnoty pre kategórie, od 0 do 1 (1 kategóriu 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,
            # Akcia pri prekročení prahu
            "action": "block",
        },
    }
]

Predvolený model moderácie je mistral-moderation-2603; voliteľný kľúč model_name ti umožňuje špecifikovať iný.

Anotácia list[GuardrailConfigTypedDict] nie je povinná, ale oplatí sa ju použiť: SDK popisuje každý povolený kľúč, takže kontrola typov ako pyright alebo mypy upozorní na preklep v kategórii (violence namiesto violence_and_threats), ktorý by samotné API neodhalilo.

custom_category_thresholds

Toto je srdce konfigurácie. Každá kategória dostane prahovú hodnotu medzi 0 a 1, ktorá sa porovná so skóre prideleným klasifikátorom promptu. Čím nižšia prahová hodnota, tým viac filter blokuje, čo so sebou nesie riziko zamietnutia legitímnych požiadaviek. Prahová hodnota 1 kategóriu explicitne vypne. Mistral nezverejňuje odporúčanú mriežku hodnôt: tieto hodnoty musíš kalibrovať na vlastných príkladoch (lekcia 7).

Hodnoty dávajú zmysel len v kontexte tvojej aplikácie. Verejne dostupný chatbot uzamkne citlivé kategórie na najnižšie nastavenia, zatiaľ čo interný nástroj pre zdravotníckych pracovníkov musí povoľovať lekárske otázky, pričom zostáva prísny na osobné údaje.

# Verejný chatbot: veľmi nízke prahy
public_thresholds = {
    "sexual": 0.1,
    "hate_and_discrimination": 0.1,
    "violence_and_threats": 0.1,
    "criminal": 0.1,
    "selfharm": 0.1,
}

# Interný lekársky nástroj: health vypnuté, PII stále monitorované
medical_thresholds = {
    "sexual": 0.2,
    "hate_and_discrimination": 0.1,
    "violence_and_threats": 0.3,
    "health": 1,   # vypne kategóriu: lekárske otázky sú hlavnou funkciou nástroja
    "pii": 0.1,
}

Kategórie, ktoré neuvedieš

Čo sa stane s kategóriami chýbajúcimi v custom_category_thresholds? Dokumentácia to explicitne neuvádza, ale jej príklad blokovania je výrečný: neuvedené kategórie sa tam objavujú s prahovou hodnotou 1.0, zaznamenané, ale neúčinné. Nespoliehaj sa na predvolenú prahovú hodnotu: uveď každú kategóriu, ktorá má mať schopnosť blokovať.

Možnosť ignore_other_categories riadi len to, čo sa vyhodnotí a vráti. Ak je nastavená na False, vo výsledku sa objavia všetky vyhodnotené kategórie; ak je True, vyhodnotia sa len tie, ktoré si uviedol.

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í len tieto dve kategórie
            "action": "block",
        },
    }
]

Upozornenie: s touto konfiguráciou by pokus o jailbreak alebo požiadavka na osobné údaje prešli bez kontroly. Zoznam obmedzuj len z konkrétneho dôvodu.

Kompletný príklad: chatbot s ochrannými mechanizmami

Tu je minimálna funkcia: odošle správu s úplnou konfiguráciou a zmení blokovanie na čitateľnú odpoveď pre používateľa.

from mistralai.client import errors


def chat_securise(message_utilisateur: str) -> str:
    """Odošle správu chránenú ochrannými mechanizmami."""
    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 "Prepáč, túto požiadavku nie je možné spracovať."
        raise

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


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

Dve poznámky. message.content môže byť reťazec alebo zoznam častí v závislosti od modelu, preto je potrebná kontrola isinstance. A odpoveď z chat.complete() v SDK 3.7.0 nezverejňuje skóre ochranných mechanizmov: na ich logovanie použij Conversations API, ktorého odpoveď ich nesie v poli guardrails.

Čisté ošetrenie chýb pri blokovaní

Musíš rozlíšiť dva typy zlyhaní, ktoré si vyžadujú odlišnú správu aj odlišné upozornenie: blokovanie podľa pravidiel obsahu, ktoré vráti HTTP stavový kód 403, a zlyhanie vyhodnotenia moderácie so zapnutým block_on_error, ktoré telo odpovede signalizuje kódom 3201. Obe prichádzajú ako errors.SDKError, ktorého body obsahuje JSON vrátený API:

import json
from typing import Any

from mistralai.client import errors


def chat_avec_gestion_erreurs(message_utilisateur: str) -> dict[str, Any]:
    """Chat, ktorý rozlišuje medzi blokovaním podľa pravidiel a zlyhaním moderácie."""
    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 moderácie nie je dostupná. Požiadavka bola preventívne zablokovaná.",
            }
        if e.status_code == 403:
            decisions = corps["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
            return {
                "status": "blocked",
                "content": "Tvoja správa bola zablokovaná našou bezpečnostnou politikou.",
                "categories": [nom for nom, d in decisions.items() if d["violated"]],
            }
        raise

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

Najprv skontroluj kód 3201, pretože dokumentácia nešpecifikuje HTTP stav pre túto chybu. Porušené kategórie pochádzajú z decisions, kde každá položka poskytuje threshold, score a violated: toto je to, čo budeš logovať, aby si vysvetlil blokovanie.

Najlepšie postupy konfigurácie

Začni prísne a potom uvoľňuj. Nízke prahy pri spustení ti pomôžu odhaliť falošne pozitívne výsledky, keď je objem ešte zvládnuteľný, a každé zvýšenie sa rozhoduje na základe pozorovaných prípadov, nie intuície:

# Fáza 1: spustenie (veľmi prísne)
phase1 = {"hate_and_discrimination": 0.1, "violence_and_threats": 0.1, "criminal": 0.1}

# Fáza 2: po analýze falošne pozitívnych výsledkov
phase2 = {"hate_and_discrimination": 0.15, "violence_and_threats": 0.25, "criminal": 0.1}

# Fáza 3: stabilná produkcia
phase3 = {"hate_and_discrimination": 0.2, "violence_and_threats": 0.3, "criminal": 0.15}

Tieto hodnoty ilustrujú prístup; tvoje vyplynú z tvojich vlastných meraní. V produkcii nechaj block_on_error nastavené na True: jeho predvolená hodnota v SDK je False a zlyhanie moderácie by potom prepustilo neoverený obsah. Nakoniec, dokumentácia varuje, že model moderácie sa vyvíja: politiky založené na skóre môžu vyžadovať recalibráciu.

Kľúčové poznatky

  • guardrails je zoznam objektov {"block_on_error": ..., "moderation_llm_v2": {...}}
  • Vnútri moderation_llm_v2: custom_category_thresholds, ignore_other_categories, action a voliteľne model_name
  • Prahové hodnoty od 0 do 1; nižšia znamená prísnejšie; 1 kategóriu vypne. Uveď každú kategóriu, ktorá má blokovať
  • Blokovanie vyvolá errors.SDKError s status_code == 403; zlyhanie s block_on_error nesie v tele kód 3201
  • V produkcii udržuj block_on_error=True, pretože predvolená hodnota je False