Przejdź do głównej treści
Polski— Wybierz język
Menu

Konfiguracja mechanizmów ochronnych (guardrails) w Pythonie

Lekcja 3 z 12 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Od teorii do kodu
  2. Parametr guardrails w szczegółach
  3. Pełny przykład: chatbot z mechanizmami ochronnymi
  4. Czysta obsługa błędów blokujących
  5. Najlepsze praktyki konfiguracji
  6. Kluczowe wnioski

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ła e.status_code == 3201, mimo że 3201 to 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 SDK mistralai w 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

  • guardrails to lista obiektów {"block_on_error": ..., "moderation_llm_v2": {...}}
  • Wewnątrz moderation_llm_v2: custom_category_thresholds, ignore_other_categories, action oraz opcjonalnie model_name
  • Progi od 0 do 1; niższy oznacza surowszy; 1 wyłącza kategorię. Wymień każdą kategorię, która powinna blokować
  • Blokada zgłasza errors.SDKError z status_code == 403; niepowodzenie z block_on_error niesie kod 3201 w treści odpowiedzi
  • Utrzymuj block_on_error=True w produkcji, ponieważ domyślnie jest False