Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Guardrail-ek konfigurálása Pythonban

3. lecke 12 közül Frissítve 2026. november 3. Fejlesztő
Ezen az oldalon
  1. Az elmélettől a kódig
  2. A guardrails paraméter részletesen
  3. Teljes példa: chatbot guardrail-ekkel
  4. Blokkolási hibák tiszta kezelése
  5. Konfigurációs legjobb gyakorlatok
  6. Főbb megállapítások

A leckét 2026. november 3-án írtuk át. Az előző verzió egy kitalált szótárral (enabled) és nem létező kategóriákkal (hate, violence, unpredictable) konfigurálta a guardrail-eket, azt állítva, hogy a fel nem sorolt kategóriák „alapértelmezett küszöbértékeket“ tartanak fenn, valamint a e.status_code == 3201 feltételt tesztelte, holott a 3201 egy választestben lévő hibakód, nem pedig HTTP státuszkód. A konfiguráció most a hivatalos formátumot követi, a kódot pedig ellenőriztük a mistralai SDK 3.7.0 típusai alapján. Források: Moderáció és Guardrailing · mistralai Python SDK.

Az elmélettől a kódig

Most már érted, hogyan működnek a guardrail-ek. Ebben a leckében pontosan konfigurálod őket: kiválasztod a kategóriákat, meghatározod a küszöbértékeket, és kezeled a blokkolásokat a Python kódodban.

Kezdjük a Mistral SDK telepítésével (a guardrail-ekhez legalább a 2-es verzió szükséges), és győződj meg róla, hogy az API kulcsot a környezetből töltöd be, nem pedig keménykódolod.

pip install "mistralai>=2"
import os

from mistralai.client import Mistral

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

A guardrails paraméter részletesen

A guardrails paraméter egy lista. Minden elem párosítja a block_on_error opciót egy moderation_llm_v2 konfigurációval, amely maga is tartalmaz küszöbértékeket, az ignore_other_categories opciót és a műveletet:

from mistralai.client.models import GuardrailConfigTypedDict

GUARDRAILS: list[GuardrailConfigTypedDict] = [
    {
        # Blokkolás, ha maga az értékelés sikertelen
        "block_on_error": True,
        "moderation_llm_v2": {
            # Kategóriánkénti küszöbértékek 0 és 1 között (az 1 letiltja a kategóriát)
            "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,
            # Művelet küszöbérték-túllépés esetén
            "action": "block",
        },
    }
]

Az alapértelmezett moderációs modell a mistral-moderation-2603; az opcionális model_name kulccsal mást is megadhatsz.

A list[GuardrailConfigTypedDict] annotáció nem kötelező, de érdemes használni: az SDK felsorol minden engedélyezett kulcsot, így egy típusellenőrző, mint a pyright vagy a mypy, jelezni fogja az elgépelést (például violence a violence_and_threats helyett), amit maga az API nem feltétlenül kapna el.

custom_category_thresholds

Ez a konfiguráció szíve. Minden kategória kap egy 0 és 1 közötti küszöbértéket, amelyet az osztályozó által a promptnak adott pontszámhoz hasonlítunk. Minél alacsonyabb a küszöb, annál többet blokkol a szűrő, de nő a jogos kérések elutasításának kockázata is. Az 1 érték kifejezetten letiltja a kategóriát. A Mistral nem tesz közzé ajánlott értéktáblázatot: neked kell kalibrálnod ezeket a saját példáidon (7. lecke).

Az értékek csak az alkalmazásod kontextusában értelmesek. Egy nyilvános chatbot a legalacsonyabb beállításokra zárja le az érzékeny kategóriákat, míg egy egészségügyi szakembereknek szánt belső eszköznek engednie kell az orvosi kérdéseket, miközben szigorú marad a személyes adatok terén.

# Nyilvános chatbot: nagyon alacsony küszöbök
public_thresholds = {
    "sexual": 0.1,
    "hate_and_discrimination": 0.1,
    "violence_and_threats": 0.1,
    "criminal": 0.1,
    "selfharm": 0.1,
}

# Belső orvosi eszköz: health letiltva, PII továbbra is figyelve
medical_thresholds = {
    "sexual": 0.2,
    "hate_and_discrimination": 0.1,
    "violence_and_threats": 0.3,
    "health": 1,   # kategória letiltása: az orvosi kérdések az eszköz fő funkciói
    "pii": 0.1,
}

A fel nem sorolt kategóriák

Mi történik azokkal a kategóriákkal, amelyek hiányoznak a custom_category_thresholds listából? A dokumentáció nem fogalmazza meg ezt expliciten, de a blokkolási példa beszédes: a fel nem sorolt kategóriák ott 1.0 küszöbértékkel jelennek meg, ami jegyzetelt, de hatástalan. Ne támaszkodj alapértelmezett küszöbértékre: sorold fel minden olyan kategóriát, amelynek blokkolnia kell.

Az ignore_other_categories opció csak azt szabályozza, mi kerül kiértékelésre és visszaadásra. Ha False, minden kiértékelt kategória megjelenik az eredményben; ha True, csak a felsoroltakat értékeli ki a rendszer.

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,  # csak ezt a két kategóriát értékeli ki
            "action": "block",
        },
    }
]

Figyelem: ezzel a konfigurációval egy jailbreak kísérlet vagy személyes adatokra irányuló kérés ellenőrizetlenül átmehet. Csak konkrét okból korlátozd a listát.

Teljes példa: chatbot guardrail-ekkel

Íme egy minimális függvény: elküldi az üzenetet a teljes konfigurációval, és a blokkolást a felhasználó számára olvasható válasszá alakítja.

from mistralai.client import errors


def chat_securise(message_utilisateur: str) -> str:
    """Üzenet küldése guardrail-ek védelmében."""
    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 "Sajnáljuk, ezt a kérést nem tudjuk feldolgozni."
        raise

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


print(chat_securise("Magyarázd el nekem a gépi tanulást"))

Két megjegyzés. A message.content lehet szöveg vagy részek listája a modelltől függően, ezért szükséges az isinstance ellenőrzés. A chat.complete() válasza az SDK 3.7.0 verziójában nem teszi elérhetővé a guardrail pontszámokat: ezek naplózásához használd a Conversations API-t, amelynek válasza a guardrails mezőben hordozza azokat.

Blokkolási hibák tiszta kezelése

Két olyan hibát kell megkülönböztetned, amelyek sem ugyanazt az üzenetet, sem ugyanazt a riasztást nem igénylik: egy tartalmi szabályzat miatti blokkolást, amely HTTP 403 státuszkódot ad vissza, és egy moderációs értékelési hibát, amikor a block_on_error engedélyezve van, amit a választest a 3201 kóddal jelez. Mindkettő errors.SDKError kivételként érkezik, amelynek body attribútuma tartalmazza az API által visszaadott JSON-t:

import json
from typing import Any

from mistralai.client import errors


def chat_avec_gestion_erreurs(message_utilisateur: str) -> dict[str, Any]:
    """Chat, amely megkülönbözteti a szabályzati blokkolást a moderációs hibáktól."""
    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": "A moderációs szolgáltatás nem elérhető. A kérést elővigyázatosságból blokkoltuk.",
            }
        if e.status_code == 403:
            decisions = corps["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
            return {
                "status": "blocked",
                "content": "Az üzenetedet blokkolta a biztonsági szabályzatunk.",
                "categories": [nom for nom, d in decisions.items() if d["violated"]],
            }
        raise

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

Először a 3201 kódot ellenőrizd, mert a dokumentáció nem specifikálja ennek a hibának a HTTP státuszkódját. A megsértett kategóriák a decisions elemből származnak, ahol minden bejegyzés tartalmaz threshold, score és violated adatot: ezt naplózod, hogy megmagyarázd a blokkolást.

Konfigurációs legjobb gyakorlatok

Kezdj szigorúan, majd lazíts. Az alacsony küszöbértékek az induláskor segítenek felfedezni a téves pozitív eredményeket, amíg a forgalom még kezelhető, és minden emelést megfigyelt esetek alapján döntesz el, nem pedig megérzésből:

# 1. fázis: indulás (nagyon szigorú)
phase1 = {"hate_and_discrimination": 0.1, "violence_and_threats": 0.1, "criminal": 0.1}

# 2. fázis: a téves pozitívok elemzése után
phase2 = {"hate_and_discrimination": 0.15, "violence_and_threats": 0.25, "criminal": 0.1}

# 3. fázis: stabil éles környezet
phase3 = {"hate_and_discrimination": 0.2, "violence_and_threats": 0.3, "criminal": 0.15}

Ezek az értékek csak a megközelítést illusztrálják; a tieid a saját méréseidből fognak származni. Éles környezetben tartsd a block_on_error értéket True-n: az SDK alapértelmezett értéke False, és egy moderációs hiba ekkor ellenőrizetlen tartalmat engedne át. Végül a dokumentáció figyelmeztet, hogy a moderációs modell fejlődik: a pontszámokon alapuló szabályzatok újrakalibrálást igényelhetnek.

Főbb megállapítások

  • A guardrails egy objektumokból álló lista: {"block_on_error": ..., "moderation_llm_v2": {...}}
  • A moderation_llm_v2 belül: custom_category_thresholds, ignore_other_categories, action, és opcionálisan model_name
  • Küszöbértékek 0 és 1 között; minél alacsonyabb, annál szigorúbb; az 1 letiltja a kategóriát. Sorold fel minden blokkolni képes kategóriát
  • A blokkolás errors.SDKError kivételt dob status_code == 403 értékkel; a block_on_error melletti hiba a testben 3201 kódot hordoz
  • Éles környezetben tartsd a block_on_error=True beállítást, mivel az alapértelmezett érték False