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

Niestandardowe Guardrails: Blokuj zanim model odpowie

Lekcja 2 z 12 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Zasada działania niestandardowych Guardrails
  2. Jak to działa
  3. Format parametru guardrails
  4. Jedenaście kategorii
  5. Trzy poziomy zastosowania
  6. Co zwracają Guardrails
  7. Wybór odpowiedniego poziomu
  8. Kluczowe wnioski

Lekcja przepisana 3 listopada 2026 r. Poprzednia wersja opisywała fikcyjny parametr guardrails (słownik z kluczem enabled), nieistniejące kategorie (hate, violence), brakującą metodę conversation.send() w SDK oraz zmyślone odpowiedzi JSON. Oficjalny format to lista konfiguracji moderation_llm_v2, a poniższe odpowiedzi są zgodne z dokumentacją. Kod został zweryfikowany pod kątem typów SDK mistralai w wersji 3.7.0. Źródła: Moderation & Guardrailing · mistralai Python SDK.

Zasada działania niestandardowych Guardrails

Niestandardowe Guardrails od Mistral działają jako filtr wejściowy: analizują prompt użytkownika zanim trafi on do modelu generującego. Jeśli treść przekroczy którykolwiek z ustawionych przez Ciebie progów, żądanie zostanie zablokowane błędem HTTP 403. Model nigdy nie zobaczy problematycznego promptu.

Od samego początku pamiętaj o dwóch ograniczeniach. Po pierwsze, guardrails moderują tylko dane wejściowe; nie sprawdzają tego, co wygeneruje model. Do tego służy API Moderacji (Lekcja 5). Po drugie, zastępują one pracę, którą musiałbyś wykonać samodzielnie: wywołanie API Moderacji, porównanie wyników z własnymi progami i odrzucenie żądania.

Jak to działa

Gdy dodasz guardrails do żądania, przepływ po stronie Mistral wygląda następująco:

  1. Twoja aplikacja wysyła żądanie z parametrem guardrails.
  2. Klasyfikator mistral-moderation-2603 ocenia prompt w każdej kategorii.
  3. Jeśli wynik przekroczy próg, API zwraca błąd 403, a model nie zostaje wywołany.
  4. W przeciwnym razie model przetwarza żądanie normalnie.
  5. Odpowiedź zawiera pole guardrails z ocenionymi wynikami.
Flow: prompt → [mistral-moderation-2603] → score > threshold? → 403 (zablokowane)
                                           → else             → [LLM] → response + scores

Decyzja zależy od wyniku porównanego z progiem, który ustawiasz Ty, kategoria po kategorii, w zakresie od 0 do 1. Niski próg blokuje więcej treści; próg równy 1 jawnie wyłącza daną kategorię.

Format parametru guardrails

Parametr ten jest listą. Każdy element to obiekt zawierający konfigurację moderation_llm_v2 oraz, obok niej, opcję block_on_error:

guardrails = [
    {
        "block_on_error": True,          # zablokuj, jeśli sama moderacja zawiedzie
        "moderation_llm_v2": {
            "custom_category_thresholds": {
                "jailbreaking": 0.3,
                "criminal": 0.2,
            },
            "ignore_other_categories": False,
            "action": "block",
        },
    }
]
KluczLokalizacjaRola
custom_category_thresholdswewnątrz moderation_llm_v2Próg od 0 do 1 dla każdej kategorii; 1 wyłącza kategorię
ignore_other_categorieswewnątrz moderation_llm_v2True: oceniane są tylko wymienione kategorie
actionwewnątrz moderation_llm_v2"block" odrzuca żądanie, jeśli próg zostanie przekroczony
model_namewewnątrz moderation_llm_v2, opcjonalnieModel moderacji inny niż domyślny mistral-moderation-2603
block_on_errorobok moderation_llm_v2True: żądanie jest blokowane, jeśli ocena się nie powiedzie

Możesz umieścić w liście wiele obiektów: żądanie zostanie zablokowane, gdy tylko jeden z nich zadziała. Każdy obiekt zawiera tylko jedną konfigurację moderation_llm_v2. Starsza konfiguracja, moderation_llm_v1, nadal istnieje w SDK z kategoriami z przestarzałego modelu mistral-moderation-2411 (przestarzały od 31 marca 2026 r.): nie używaj jej w nowych projektach.

Jedenaście kategorii

Klucze w custom_category_thresholds są stałe; inny klucz, taki jak violence czy hate, nic nie oznacza:

KluczCo wykrywa
sexualTreści o charakterze seksualnym
hate_and_discriminationMowa nienawiści lub dyskryminacja ze względu na cechy chronione
violence_and_threatsOpisane, gloryfikowane lub zagrożenia przemocą fizyczną
dangerousSkrajnie niebezpieczne zachowania
criminalDziałania nielegalne
selfharmSamookaleczenia, samobójstwa, zaburzenia odżywiania
healthProśby o szczegółowe lub spersonalizowane porady medyczne
financialProśby o szczegółowe lub spersonalizowane porady finansowe
lawProśby o szczegółowe lub spersonalizowane porady prawne
piiŻądanie lub udostępnienie danych osobowych
jailbreakingPróby obejścia zasad modelu

Lekcja 6 ponownie omawia każdą z nich i dyskutuje wybór progów.

Trzy poziomy zastosowania

Ten sam parametr jest akceptowany w trzech miejscach. Twój wybór decyduje o tym, gdzie żyje Twoja polityka bezpieczeństwa i kto może zapomnieć ją zastosować.

Poziom 1: Żądanie Chat Completions

Przekazujesz guardrails w wywołaniu chat.complete(). Każde żądanie niesie własne zasady: praktyczne do eksploracji, ale ryzykowne na dużą skalę, ponieważ pojedyncze wywołanie bez tego parametru przejdzie nieskontrolowane.

import os

from mistralai.client import Mistral

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

response = client.chat.complete(
    model="mistral-large-latest",
    messages=[{"role": "user", "content": "What is the distance from the Earth to the Moon?"}],
    guardrails=[
        {
            "block_on_error": True,
            "moderation_llm_v2": {
                "custom_category_thresholds": {"sexual": 0.1, "selfharm": 0.1},
                "ignore_other_categories": False,
                "action": "block",
            },
        }
    ],
)
print(response.choices[0].message.content)

Przypadek użycia: Prototypowanie, jednorazowe wywołania, strojenie progów.

Poziom 2: Konwersacja

Korzystając z Conversations API, przekazujesz guardrails przy starcie, w client.beta.conversations.start():

conversation = client.beta.conversations.start(
    model="mistral-large-latest",
    inputs="Hello, can you help me prepare for an interview?",
    guardrails=[
        {
            "block_on_error": True,
            "moderation_llm_v2": {
                "custom_category_thresholds": {
                    "sexual": 0.2,
                    "hate_and_discrimination": 0.1,
                    "violence_and_threats": 0.3,
                    "selfharm": 0.1,
                },
                "action": "block",
            },
        }
    ],
)
for entree in conversation.outputs:
    if entree.type == "message.output":
        print(entree.content)

Kolejne wiadomości są wysyłane za pomocą client.beta.conversations.append(conversation_id=conversation.conversation_id, inputs=...). Metoda ta nie przyjmuje parametru guardrails w SDK 3.7.0, a dokumentacja nie precyzuje, czy guardrails ze startu dotyczą kolejnych tur. Aby mieć gwarancję ochrony w każdej turze, dołącz guardrails do agenta.

Przypadek użycia: Jednorazowa konwersacja bez agenta lub nadpisanie guardrails agenta dla konkretnego żądania.

Poziom 3: Agent

Guardrails przekazane do client.beta.agents.create() stają się częścią definicji agenta. Zgodnie z dokumentacją, wszystkie konwersacje korzystające z tego agenta dziedziczą je bez konieczności powtarzania. Jednakże żądanie konwersacji może je nadpisać, przekazując własne guardrails.

agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="Secure Assistant",
    instructions="You are a professional customer service assistant.",
    guardrails=[
        {
            "block_on_error": True,
            "moderation_llm_v2": {
                "custom_category_thresholds": {
                    "sexual": 0.1,
                    "hate_and_discrimination": 0.1,
                    "violence_and_threats": 0.2,
                    "criminal": 0.1,
                    "selfharm": 0.1,
                    "jailbreaking": 0.3,
                },
                "ignore_other_categories": False,
                "action": "block",
            },
        }
    ],
)

conversation = client.beta.conversations.start(agent_id=agent.id, inputs="Hello!")

Przypadek użycia: Produkcja, gdy wiele zespołów lub usług wywołuje tego samego asystenta.

Co zwracają Guardrails

Gdy żądanie przejdzie pomyślnie, odpowiedź API zawiera, obok standardowych pól, pole guardrails: listę z jednym wynikiem dla każdego guardrail. Oto to pole z przykładu w dokumentacji:

{
  "guardrails": [
    {
      "moderation_llm_v2": {
        "action": "pass",
        "categories": {
          "sexual": { "score": 0.03, "violated": false },
          "selfharm": { "score": 0.05, "violated": false },
          "violence_and_threats": { "score": 0.0, "violated": false },
          "hate_and_discrimination": { "score": 0.0, "violated": false }
        }
      }
    }
  ]
}

Gdy ignore_other_categories jest ustawione na True, w tym wyniku pojawiają się tylko kategorie wymienione w Twoich progach. W Python SDK odpowiedź konwersacji udostępnia to pole (conversation.guardrails). Odpowiedź chat.complete() nie ma jednak w SDK 3.7.0 dedykowanego pola dla niego: tam dane te giną. Jeśli chcesz logować wyniki – a warto wiedzieć później, czy Twoje progi są zbyt luźne, czy zbyt ciasne – użyj konwersacji lub odczytaj surową odpowiedź HTTP.

Gdy próg zostanie przekroczony, API zwraca błąd 403, którego treść szczegółowo opisuje decyzję, kategoria po kategorii:

{
  "error": { "message": "Content blocked by guardrail", "status": 403 },
  "guardrails": {
    "results": {
      "moderation_llm_v2": {
        "model_name": "mistral-moderation-2603",
        "decisions": {
          "sexual": { "threshold": 0.1, "score": 0.3, "violated": true },
          "selfharm": { "threshold": 0.1, "score": 0.05, "violated": false }
        },
        "violated": true,
        "action": "block"
      }
    }
  }
}

SDK zgłasza wtedy errors.SDKError, gdzie status_code wynosi 403, a body zawiera ten JSON:

import json

from mistralai.client import errors

try:
    response = client.chat.complete(
        model="mistral-large-latest",
        messages=[{"role": "user", "content": user_message}],
        guardrails=guardrails,
    )
except errors.SDKError as e:
    if e.status_code != 403:
        raise
    decisions = json.loads(e.body)["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
    violated = [name for name, d in decisions.items() if d["violated"]]
    print(f"Request blocked: {violated}")

Ten ładunek pozwala wyjaśnić blokadę podczas odwołania: która kategoria, jaki wynik, jaki próg.

Na koniec przypadek degradacji. Jeśli sama ocena się nie powiedzie, a block_on_error jest ustawione na True, żądanie zostaje odrzucone z kodem błędu 3201 i komunikatem Request blocked due to error in guardrail evaluation and block_on_error is set to True. Jest to tryb fail-safe: w razie wątpliwości blokuj. Przy block_on_error ustawionym na False (wartość domyślna w SDK), żądanie przeszłoby nieskontrolowane.

Wybór odpowiedniego poziomu

KryteriumChat CompletionsKonwersacjaAgent
Gdzie deklarowane są guardrailsW każdym wywołaniuPrzy starcie (start)Przy tworzeniu agenta
DziedziczenieBrakNieudokumentowane dla kolejnych turWszystkie konwersacje agenta
Możliwość nadpisania——Tak, przez żądanie konwersacji
Przypadek użyciaTesty, strojenie progówJednorazowa konwersacjaProdukcja

W praktyce dostroj swoje progi na żądaniach Chat Completions, używając rzeczywistych przypadków, a następnie przenieś politykę do agenta, gdy tylko kod opuści Twoją maszynę: nie będzie już zapomnianych wywołań.

Kluczowe wnioski

  • Guardrails blokują prompty przed modelem poprzez błąd 403; nie sprawdzają wyjścia
  • Parametr to lista obiektów {"block_on_error": ..., "moderation_llm_v2": {...}}, a nie słownik z enabled
  • Jedenaście kategorii o stałych nazwach (hate_and_discrimination, violence_and_threats, …), każda z progiem od 0 do 1; 1 wyłącza
  • Trzy poziomy: chat.complete(), conversations.start(), agents.create(); agenci przekazują swoje guardrails wszystkim swoim konwersacjom
  • block_on_error=True zapewnia zachowanie fail-safe (błąd 3201)