Konfiguracja mechanizmów ochronnych (guardrails) w Pythonie
Na tej stronie
Lekcja przepisana 3 listopada 2026 r. Poprzednia wersja konfigurowała mechanizmy ochronne przy użyciu wymyślonego słownika (
enabled), nieistniejących kategorii (hate,violence,unpredictable), twierdząc, że niewymienione kategorie zachowują „domyślne progi“, oraz testowałae.status_code == 3201, mimo że3201to kod błędu w treści odpowiedzi, a nie status HTTP. Konfiguracja została dostosowana do oficjalnego formatu, a kod zweryfikowano pod kątem typów w SDKmistralaiw wersji 3.7.0. Źródła: Moderation & Guardrailing · mistralai Python SDK.
Od teorii do kodu
Rozumiesz już, jak działają mechanizmy ochronne. W tej lekcji skonfigurujesz je precyzyjnie: wybierzesz kategorie, zdefiniujesz progi i obsłużysz blokady w kodzie Pythona.
Rozpocznij od zainstalowania Mistral SDK (mechanizmy ochronne wymagają wersji 2 lub nowszej) i załaduj klucz API ze zmiennych środowiskowych, zamiast hardkodować go w kodzie.
pip install "mistralai>=2"
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Parametr guardrails w szczegółach
Parametr guardrails to lista. Każdy element łączy opcję block_on_error z konfiguracją moderation_llm_v2, która sama zawiera progi, opcję ignore_other_categories oraz akcję:
from mistralai.client.models import GuardrailConfigTypedDict
GUARDRAILS: list[GuardrailConfigTypedDict] = [
{
# Zablokuj, jeśli sama ewaluacja się nie powiedzie
"block_on_error": True,
"moderation_llm_v2": {
# Progi dla każdej kategorii, od 0 do 1 (1 wyłącza kategorię)
"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,
# Akcja po przekroczeniu progu
"action": "block",
},
}
]
Domyślnym modelem moderacji jest mistral-moderation-2603; opcjonalny klucz model_name pozwala wskazać inny.
Adnotacja list[GuardrailConfigTypedDict] nie jest wymagana, ale warto jej użyć: SDK opisuje każdy dozwolony klucz, więc checker typów, taki jak pyright lub mypy, wykryje literówkę w nazwie kategorii (violence zamiast violence_and_threats), której samo API by nie wychwyciło.
custom_category_thresholds
To sedno konfiguracji. Każda kategoria otrzymuje próg między 0 a 1, porównywany z wynikiem przypisanym przez klasyfikator do promptu. Im niższy próg, tym bardziej filtr blokuje, co niesie ryzyko odrzucenia legitnych żądań. Próg równy 1 wyraźnie wyłącza kategorię. Mistral nie publikuje zalecanej siatki wartości: musisz skalibrować je na własnych przykładach (lekcja 7).
Wartości mają sens tylko w kontekście Twojej aplikacji. Chatbot publiczny blokuje wrażliwe kategorie przy najniższych ustawieniach, podczas gdy narzędzie wewnętrzne dla pracowników służby zdrowia musi pozwalać na pytania medyczne, pozostając surowym wobec danych osobowych.
# Publiczny chatbot: bardzo niskie progi
public_thresholds = {
"sexual": 0.1,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.1,
"criminal": 0.1,
"selfharm": 0.1,
}
# Wewnętrzne narzędzie medyczne: health wyłączone, PII nadal monitorowane
medical_thresholds = {
"sexual": 0.2,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.3,
"health": 1, # wyłącza kategorię: pytania medyczne to główna funkcja narzędzia
"pii": 0.1,
}
Kategorie, których nie wymieniasz
Co dzieje się z kategoriami brakującymi w custom_category_thresholds? Dokumentacja nie stwierdza tego wprost, ale przykład blokady jest wymowny: niewymienione kategorie pojawiają się tam z progiem 1.0, odnotowane, lecz nieskuteczne. Nie polegaj na domyślnym progu: wymień każdą kategorię, która powinna mieć możliwość blokowania.
Opcja ignore_other_categories kontroluje jedynie to, co jest ewaluowane i zwracane. Gdy ustawiona na False, wszystkie ewaluowane kategorie pojawiają się w wyniku; gdy True, ewaluowane są tylko te, które wymieniłeś.
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, # ewaluuje tylko te dwie kategorie
"action": "block",
},
}
]
Ostrzeżenie: przy tej konfiguracji próba jailbreaku lub żądanie danych osobowych przeszłyby nieskontrolowanie. Ogranicz listę tylko z konkretnego powodu.
Pełny przykład: chatbot z mechanizmami ochronnymi
Oto minimalna funkcja: wysyła wiadomość z pełną konfiguracją i zamienia blokadę w czytelną odpowiedź dla użytkownika.
from mistralai.client import errors
def chat_securise(message_utilisateur: str) -> str:
"""Wysyła wiadomość chronioną mechanizmami ochronnymi."""
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 "Przepraszamy, tego żądania nie można przetworzyć."
raise
contenu = response.choices[0].message.content
return contenu if isinstance(contenu, str) else ""
print(chat_securise("Wyjaśnij mi uczenie maszynowe"))
Dwie uwagi. message.content może być ciągiem znaków lub listą części w zależności od modelu, stąd sprawdzenie isinstance. Odpowiedź z chat.complete() nie udostępnia wyników mechanizmów ochronnych w SDK 3.7.0: aby je logować, użyj Conversations API, którego odpowiedź zawiera je w polu guardrails.
Czysta obsługa błędów blokujących
Musisz rozróżnić dwa rodzaje niepowodzeń, które wymagają zarówno innego komunikatu, jak i innego alertu: blokada zgodna z polityką treści, zwracająca status HTTP 403, oraz niepowodzenie ewaluacji moderacji przy włączonym block_on_error, sygnalizowane w treści odpowiedzi kodem 3201. Obie sytuacje przychodzą jako errors.SDKError, którego body zawiera JSON zwrócony przez API:
import json
from typing import Any
from mistralai.client import errors
def chat_avec_gestion_erreurs(message_utilisateur: str) -> dict[str, Any]:
"""Czat rozróżniający blokady polityki od niepowodzeń moderacji."""
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": "Usługa moderacji niedostępna. Żądanie zablokowane jako środek ostrożności.",
}
if e.status_code == 403:
decisions = corps["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
return {
"status": "blocked",
"content": "Twoja wiadomość została zablokowana przez naszą politykę bezpieczeństwa.",
"categories": [nom for nom, d in decisions.items() if d["violated"]],
}
raise
return {"status": "ok", "content": response.choices[0].message.content}
Najpierw sprawdź kod 3201, ponieważ dokumentacja nie precyzuje statusu HTTP dla tego błędu. Naruszone kategorie pochodzą z decisions, gdzie każdy wpis podaje threshold, score i violated: to właśnie te dane zalogujesz, aby wyjaśnić przyczynę blokady.
Najlepsze praktyki konfiguracji
Zacznij restrykcyjnie, a następnie poluzuj ustawienia. Niskie progi na starcie pomagają wykryć fałszywe pozytywy, gdy wolumen jest jeszcze możliwy do opanowania, a każda zmiana jest podejmowana na podstawie zaobserwowanych przypadków, a nie intuicji:
# Faza 1: start (bardzo restrykcyjne)
phase1 = {"hate_and_discrimination": 0.1, "violence_and_threats": 0.1, "criminal": 0.1}
# Faza 2: po analizie fałszywych pozytywów
phase2 = {"hate_and_discrimination": 0.15, "violence_and_threats": 0.25, "criminal": 0.1}
# Faza 3: stabilna produkcja
phase3 = {"hate_and_discrimination": 0.2, "violence_and_threats": 0.3, "criminal": 0.15}
Te wartości ilustrują podejście; Twoje wynikną z własnych pomiarów. Pozostaw block_on_error ustawione na True w środowisku produkcyjnym: jego domyślna wartość w SDK to False, a niepowodzenie moderacji przepuściłoby wtedy niezweryfikowaną treść. Na koniec dokumentacja ostrzega, że model moderacji ewoluuje: polityki oparte na wynikach mogą wymagać ponownej kalibracji.
Kluczowe wnioski
guardrailsto lista obiektów{"block_on_error": ..., "moderation_llm_v2": {...}}- Wewnątrz
moderation_llm_v2:custom_category_thresholds,ignore_other_categories,actionoraz opcjonalniemodel_name - Progi od
0do1; niższy oznacza surowszy;1wyłącza kategorię. Wymień każdą kategorię, która powinna blokować - Blokada zgłasza
errors.SDKErrorzstatus_code == 403; niepowodzenie zblock_on_errorniesie kod3201w treści odpowiedzi - Utrzymuj
block_on_error=Truew produkcji, ponieważ domyślnie jestFalse