Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Configureerige kaitsepiiranguid Pythonis

Õppetund 3 / 12 Värskendatud 3. november 2026 Arendajatele
Sellel lehel
  1. Teooriast koodini
  2. Parameeter guardrails lähemalt
  3. Täielik näide: vestlusrobot kaitsepiirangutega
  4. Käsitle blokeerimisvigu korrektselt
  5. Konfiguratsiooni parimad tavad
  6. Peamised punktid

Õppetund kirjutati 3. novembril 2026 ümber. Eelmises versioonis konfigureeriti kaitsepiiranguid väljamõeldud sõnastiku (enabled) ja olematute kategooriate (hate, violence, unpredictable) abil, väideti, et loetlemata kategooriad säilitavad „vaikimisi lävendid“, ning testiti tingimust e.status_code == 3201, kuigi 3201 on vastuse keha veakood, mitte HTTP olekukood. Konfiguratsioon järgib nüüd ametlikku formaati ja kood on kontrollitud mistralai SDK 3.7.0 tüüpide vastu. Allikad: Moderation & Guardrailing · mistralai Python SDK.

Teooriast koodini

Sa mõistad nüüd, kuidas kaitsepiirangud toimivad. Selles õppetunnis konfigureerid need täpselt: valid oma kategooriad, määrad lävendid ja käsitled blokeeringuid oma Pythoni koodis.

Alusta Mistrali SDK installimisest (kaitsepiirangud nõuavad versiooni 2 või uuemat) ja API võtme laadimisest keskkonnamuutujatest, mitte selle otsekoodistamisest.

pip install "mistralai>=2"
import os

from mistralai.client import Mistral

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

Parameeter guardrails lähemalt

Parameeter guardrails on loend. Iga element ühendab valiku block_on_error konfiguratsiooniga moderation_llm_v2, mis omakorda sisaldab lävendeid, valikut ignore_other_categories ja tegevust:

from mistralai.client.models import GuardrailConfigTypedDict

GUARDRAILS: list[GuardrailConfigTypedDict] = [
    {
        # Blokeeri, kui hindamine ise ebaõnnestub
        "block_on_error": True,
        "moderation_llm_v2": {
            # Lävennid kategooria kohta, vahemikus 0 kuni 1 (1 keelab kategooria)
            "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,
            # Tegevus lävendi ületamisel
            "action": "block",
        },
    }
]

Vaikimisi moderatsioonimudel on mistral-moderation-2603; valikuline võti model_name võimaldab määrata mõne muu.

Annotatsioon list[GuardrailConfigTypedDict] ei ole kohustuslik, kuid selle kasutamine on soovitatav: SDK kirjeldab iga lubatud võtit, nii et tüübikontrollija nagu pyright või mypy tuvastab valesti kirjutatud kategooria (violence asemel violence_and_threats), mida API ise ei pruugi märgata.

custom_category_thresholds

See on konfiguratsiooni süda. Iga kategooria saab lävendi vahemikus 0 kuni 1, mida võrreldakse klassifikaatori poolt sisendile omistatud skooriga. Mida madalam on lävend, seda rohkem filter blokeerib, riskides tagasi lükata õiguspäraseid päringuid. Lävend 1 keelab kategooria sõnaselgelt. Mistral ei avalda soovitatud väärtuste tabelit: pead need kalibreerima oma näidete põhjal (õppetund 7).

Väärtustel on mõtet ainult sinu rakenduse kontekstis. Avalikkusele suunatud vestlusrobot lukustab tundlikud kategooriad madalaimate seadetega, samas kui tervishoiutöötajatele mõeldud sisetööriist peab lubama meditsiinilisi küsimusi, jäädes samal ajal isikuandmete osas rangeks.

# Avalik vestlusrobot: väga madalad lävendid
public_thresholds = {
    "sexual": 0.1,
    "hate_and_discrimination": 0.1,
    "violence_and_threats": 0.1,
    "criminal": 0.1,
    "selfharm": 0.1,
}

# Sisene meditsiinitööriist: tervis keelatud, PII-d jälgitakse endiselt
medical_thresholds = {
    "sexual": 0.2,
    "hate_and_discrimination": 0.1,
    "violence_and_threats": 0.3,
    "health": 1,   # keelab kategooria: meditsiinilised küsimused on tööriista põhifunktsioon
    "pii": 0.1,
}

Kategooriad, mida sa ei loetle

Mis juhtub kategooriatega, mida custom_category_thresholds ei sisalda? Dokumentatsioon ei ütle seda sõnaselgelt, kuid selle blokeerimise näide on kõnekas: loetlemata kategooriad ilmuvad seal lävendiga 1.0, märgitud, kuid mitteefektiivsena. Ära tugine vaikimisi lävendile: loetle iga kategooria, mis peaks suutma blokeerida.

Valik ignore_other_categories kontrollib ainult seda, mida hinnatakse ja tagastatakse. Kui see on määratud väärtusele False, ilmuvad tulemusse kõik hinnatud kategooriad; kui True, hinnatakse ainult neid, mida sa loetlesid.

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,  # hindab ainult neid kahte kategooriat
            "action": "block",
        },
    }
]

Hoiatus: selle konfiguratsiooniga pääseksid näiteks jailbreak’i katsed või isikuandmete päringud kontrollimatult läbi. Piira loendit ainult kindlal põhjusel.

Täielik näide: vestlusrobot kaitsepiirangutega

Siin on minimaalne funktsioon: see saadab sõnumi koos täieliku konfiguratsiooniga ja muudab blokeeringu kasutajale loetavaks vastuseks.

from mistralai.client import errors


def chat_securise(message_utilisateur: str) -> str:
    """Saadab kaitsepiirangutega kaitstud sõnumi."""
    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 "Vabandust, seda päringut ei saa töödelda."
        raise

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


print(chat_securise("Selgita mulle masinõpet"))

Kaks märkust. message.content võib olenevalt mudelist olla kas sõne või osade loend, seega on vajalik kontroll isinstance. Ja vastus funktsioonilt chat.complete() ei avalda SDK 3.7.0 versioonis kaitsepiirangute skoore: nende logimiseks kasuta Conversations API-t, mille vastus kannab neid väljal guardrails.

Käsitle blokeerimisvigu korrektselt

Pead eristama kahte ebaõnnestumist, mis nõuavad nii erinevat sõnumit kui ka erinevat hoiatust: sisupoliitika blokeering, mis tagastab HTTP olekukoodi 403, ja moderatsiooni hindamise ebaõnnestumine lubatud block_on_error korral, millele vastuse keha viitab koodiga 3201. Mõlemad jõuavad kohale kui errors.SDKError, mille body sisaldab API tagastatud JSON-i:

import json
from typing import Any

from mistralai.client import errors


def chat_avec_gestion_erreurs(message_utilisateur: str) -> dict[str, Any]:
    """Vestlus, mis eristab poliitikablokeeringuid moderatsiooni ebaõnnestumistest."""
    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": "Moderatsiooniteenus pole saadaval. Päring blokeeriti ettevaatusabinõuna.",
            }
        if e.status_code == 403:
            decisions = corps["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
            return {
                "status": "blocked",
                "content": "Sinu sõnum blokeeriti meie turvapoliitika poolt.",
                "categories": [nom for nom, d in decisions.items() if d["violated"]],
            }
        raise

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

Kontrolli esmalt koodi 3201, kuna dokumentatsioon ei täpsusta selle vea HTTP olekut. Rikutud kategooriad pärinevad decisions-ist, kus iga kirje annab threshold, score ja violated: seda kasutad blokeeringu selgitamiseks logimisel.

Konfiguratsiooni parimad tavad

Alusta rangelt ja lõdvesta seejärel. Madalad lävendid käivitamisel aitavad tuvastada valepositiivseid tulemusi seni, kuni maht on veel hallatav, ja iga suurendamine otsustatakse vaadeldud juhtumite, mitte intuitsiooni põhjal:

# 1. etapp: käivitamine (väga range)
phase1 = {"hate_and_discrimination": 0.1, "violence_and_threats": 0.1, "criminal": 0.1}

# 2. etapp: pärast valepositiivsete tulemuste analüüsi
phase2 = {"hate_and_discrimination": 0.15, "violence_and_threats": 0.25, "criminal": 0.1}

# 3. etapp: stabiilne tootmine
phase3 = {"hate_and_discrimination": 0.2, "violence_and_threats": 0.3, "criminal": 0.15}

Need väärtused illustreerivad lähenemist; sinu omad tulenevad sinu enda mõõtmistest. Hoia tootmises block_on_error väärtusel True: selle vaikimisi väärtus SDK-s on False ja moderatsiooni ebaõnnestumine laseks siis kontrollimata sisu läbi. Lõpuks hoiatab dokumentatsioon, et moderatsioonimudel areneb: skooridel põhinevad poliitikad võivad vajada ümberkalibreerimist.

Peamised punktid

  • guardrails on loend objektidest {"block_on_error": ..., "moderation_llm_v2": {...}}
  • sees moderation_llm_v2: custom_category_thresholds, ignore_other_categories, action ja valikuliselt model_name
  • Lävennid vahemikus 0 kuni 1; madalam tähendab rangemat; 1 keelab kategooria. Loetle iga kategooria, mis peaks blokeerima
  • Blokeering tõstab errors.SDKError koos status_code == 403; ebaõnnestumine koos block_on_error kannab kehas koodi 3201
  • Hoia tootmises block_on_error=True, kuna vaikimisi on see False