Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Konfiguriranje varoval v Pythonu

Lekcija 3 od 12 Posodobljeno 3. november 2026 Razvijalec
Na tej strani
  1. Od teorije do kode
  2. Parameter guardrails v podrobnostih
  3. Celoten primer: chatbot z varovali
  4. Čista obravnava napak blokiranja
  5. Najboljše prakse konfiguracije
  6. Ključne ugotovitve

Lekcija je bila ponovno napisana 3. novembra 2026. Prejšnja različica je konfigurirala varovala z uporabo izmišljenega slovarja (enabled), neobstoječih kategorij (hate, violence, unpredictable), trdila, da nenavedene kategorije ohranjajo „privzete pragove”, in testirala e.status_code == 3201, čeprav je 3201 koda napake v telesu odgovora, ne HTTP status. Konfiguracija zdaj sledi uradnemu formatu, koda pa je bila preverjena glede na tipe SDK mistralai različice 3.7.0. Viri: Moderation & Guardrailing · mistralai Python SDK.

Od teorije do kode

Zdaj razumeš, kako delujejo varovala. V tej lekciji jih boš natančno konfiguriral: izbral svoje kategorije, določil pragove in obravnaval blokade v svoji kodi Python.

Začni z nameščenim SDK Mistral (varovala zahtevajo različico 2 ali novejšo) in ključem API, naloženim iz okolja, namesto da bi bil zapisan neposredno v kodi.

pip install "mistralai>=2"
import os

from mistralai.client import Mistral

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

Parameter guardrails v podrobnostih

Parameter guardrails je seznam. Vsak element združuje možnost block_on_error s konfiguracijo moderation_llm_v2, ki sama vsebuje pragove, možnost ignore_other_categories in dejanje:

from mistralai.client.models import GuardrailConfigTypedDict

GUARDRAILS: list[GuardrailConfigTypedDict] = [
    {
        # Blokiraj, če sama evalvacija ne uspe
        "block_on_error": True,
        "moderation_llm_v2": {
            # Pragovi na kategorijo, od 0 do 1 (1 onemogoči kategorijo)
            "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,
            # Dejanje ob kršitvi praga
            "action": "block",
        },
    }
]

Privzeti model za moderacijo je mistral-moderation-2603; opcijski ključ model_name ti omogoča določitev drugega.

Anotacija list[GuardrailConfigTypedDict] ni obvezna, vendar jo je vredno uporabiti: SDK opisuje vsak dovoljeni ključ, zato bo preverjevalnik tipov, kot sta pyright ali mypy, opozoril na napačno črkovano kategorijo (violence namesto violence_and_threats), česar sam API ne bi zaznal.

custom_category_thresholds

To je srce konfiguracije. Vsaka kategorija dobi prag med 0 in 1, ki se primerja z oceno, ki jo klasifikator dodeli pozivu. Nižji kot je prag, bolj filter blokira, vendar s tveganjem zavrnitve legitimnih zahtevkov. Prag 1 izrecno onemogoči kategorijo. Mistral ne objavlja priporočene mreže vrednosti: te moraš umeriti na lastnih primerih (lekcija 7).

Vrednosti imajo smisel le v kontekstu tvoje aplikacije. Chatbot, dostopen javnosti, zaklene občutljive kategorije pri najnižjih nastavitvah, medtem ko mora interno orodje za zdravstvene delavce dovoliti zdravstvena vprašanja, hkrati pa ostati strogo pri osebnih podatkih.

# Javni chatbot: zelo nizki pragovi
public_thresholds = {
    "sexual": 0.1,
    "hate_and_discrimination": 0.1,
    "violence_and_threats": 0.1,
    "criminal": 0.1,
    "selfharm": 0.1,
}

# Interno medicinsko orodje: health onemogočen, PII še vedno nadzorovan
medical_thresholds = {
    "sexual": 0.2,
    "hate_and_discrimination": 0.1,
    "violence_and_threats": 0.3,
    "health": 1,   # onemogoči kategorijo: zdravstvena vprašanja so glavna funkcija orodja
    "pii": 0.1,
}

Kategorije, ki jih ne navedeš

Kaj se zgodi s kategorijami, ki manjkajo v custom_category_thresholds? Dokumentacija tega ne navaja izrecno, vendar je njen primer blokiranja zgovoren: nenavedene kategorije se tam pojavijo s pragom 1.0, zabeležene, a neučinkovite. Ne zanašaj se na privzeti prag: naštej vsako kategorijo, ki mora biti sposobna blokirati.

Možnost ignore_other_categories nadzira le, kaj se ovrednoti in vrne. Ko je nastavljena na False, se v rezultatu pojavijo vse ovrednotene kategorije; ko je True, se ovrednotijo le tiste, ki si jih navedel.

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,  # ovrednoti le ti dve kategoriji
            "action": "block",
        },
    }
]

Opozorilo: s to konfiguracijo bi poskus preboja zaščite (jailbreak) ali zahtevek za osebne podatke šel skozi brez nadzora. Seznam omeji le iz specifičnega razloga.

Celoten primer: chatbot z varovali

Tukaj je minimalna funkcija: pošlje sporočilo s popolno konfiguracijo in blokado pretvori v berljiv odgovor za uporabnika.

from mistralai.client import errors


def chat_securise(message_utilisateur: str) -> str:
    """Pošlje sporočilo, zaščiteno z varovali."""
    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 "Oprostite, tega zahtevka ni mogoče obdelati."
        raise

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


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

Dve opombi. message.content je lahko niz ali seznam delov, odvisno od modela, zato je potreben preverjek isinstance. In odgovor iz chat.complete() v SDK 3.7.0 ne razkriva ocen varoval: za njihovo beleženje uporabi API Conversations, katerega odgovor jih nosi v guardrails.

Čista obravnava napak blokiranja

Razlikovati moraš med dvema vrstama napak, ki zahtevata različno sporočilo in različno opozorilo: blokada zaradi pravil o vsebini, ki vrne HTTP status 403, in napaka pri evalvaciji moderacije z omogočenim block_on_error, ki jo telo odgovora signalizira s kodo 3201. Obe prispeteta kot errors.SDKError, katerega body vsebuje JSON, ki ga vrne API:

import json
from typing import Any

from mistralai.client import errors


def chat_avec_gestion_erreurs(message_utilisateur: str) -> dict[str, Any]:
    """Chat, ki razlikuje med blokadami zaradi pravil in napakami moderacije."""
    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": "Storitev moderacije ni na voljo. Zahtevek je preventivno blokiran.",
            }
        if e.status_code == 403:
            decisions = corps["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
            return {
                "status": "blocked",
                "content": "Vaše sporočilo je bilo blokirano zaradi naše varnostne politike.",
                "categories": [nom for nom, d in decisions.items() if d["violated"]],
            }
        raise

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

Najprej preveri kodo 3201, ker dokumentacija ne določa HTTP statusa za to napako. Kršene kategorije prihajajo iz decisions, kjer vsak vnos poda threshold, score in violated: to je tisto, kar boš beležil, da pojasniš blokado.

Najboljše prakse konfiguracije

Začni restriktivno, nato popuščaj. Nizki pragovi ob zagonu ti pomagajo odkriti lažno pozitivne rezultate, medtem ko je obseg še obvladljiv, in vsako povečanje temelji na opaženih primerih, ne na intuiciji:

# Faza 1: zagon (zelo restriktivno)
phase1 = {"hate_and_discrimination": 0.1, "violence_and_threats": 0.1, "criminal": 0.1}

# Faza 2: po analizi lažno pozitivnih rezultatov
phase2 = {"hate_and_discrimination": 0.15, "violence_and_threats": 0.25, "criminal": 0.1}

# Faza 3: stabilna proizvodnja
phase3 = {"hate_and_discrimination": 0.2, "violence_and_threats": 0.3, "criminal": 0.15}

Te vrednosti ilustrirajo pristop; tvoje bodo izhajale iz tvojih lastnih meritev. V proizvodnji ohrani block_on_error nastavljen na True: njegova privzeta vrednost v SDK je False, in napaka pri moderaciji bi potem prepustila nepreverjeno vsebino skozi. Končno, dokumentacija opozarja, da se model za moderacijo razvija: politike, ki temeljijo na ocenah, bodo morda zahtevale ponovno umerjanje.

Ključne ugotovitve

  • guardrails je seznam objektov {"block_on_error": ..., "moderation_llm_v2": {...}}
  • Znotraj moderation_llm_v2: custom_category_thresholds, ignore_other_categories, action in opcijsko model_name
  • Pragovi od 0 do 1; nižje je strožje; 1 onemogoči kategorijo. Naštej vsako kategorijo, ki mora blokirati
  • Blokada sproži errors.SDKError s status_code == 403; napaka z block_on_error nosi kodo 3201 v telesu
  • V proizvodnji ohrani block_on_error=True, saj je privzeto False