Guardrail-ek konfigurálása Pythonban
Ezen az oldalon
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 ae.status_code == 3201feltételt tesztelte, holott a3201egy 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 amistralaiSDK 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
guardrailsegy objektumokból álló lista:{"block_on_error": ..., "moderation_llm_v2": {...}} - A
moderation_llm_v2belül:custom_category_thresholds,ignore_other_categories,action, és opcionálisanmodel_name - Küszöbértékek
0és1között; minél alacsonyabb, annál szigorúbb; az1letiltja a kategóriát. Sorold fel minden blokkolni képes kategóriát - A blokkolás
errors.SDKErrorkivételt dobstatus_code == 403értékkel; ablock_on_errormelletti hiba a testben3201kódot hordoz - Éles környezetben tartsd a
block_on_error=Truebeállítást, mivel az alapértelmezett értékFalse