Niestandardowe Guardrails: Blokuj zanim model odpowie
Na tej stronie
Lekcja przepisana 3 listopada 2026 r. Poprzednia wersja opisywała fikcyjny parametr
guardrails(słownik z kluczemenabled), nieistniejące kategorie (hate,violence), brakującą metodęconversation.send()w SDK oraz zmyślone odpowiedzi JSON. Oficjalny format to lista konfiguracjimoderation_llm_v2, a poniższe odpowiedzi są zgodne z dokumentacją. Kod został zweryfikowany pod kątem typów SDKmistralaiw 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:
- Twoja aplikacja wysyła żądanie z parametrem
guardrails. - Klasyfikator
mistral-moderation-2603ocenia prompt w każdej kategorii. - Jeśli wynik przekroczy próg, API zwraca błąd
403, a model nie zostaje wywołany. - W przeciwnym razie model przetwarza żądanie normalnie.
- Odpowiedź zawiera pole
guardrailsz 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",
},
}
]
| Klucz | Lokalizacja | Rola |
|---|---|---|
custom_category_thresholds | wewnątrz moderation_llm_v2 | Próg od 0 do 1 dla każdej kategorii; 1 wyłącza kategorię |
ignore_other_categories | wewnątrz moderation_llm_v2 | True: oceniane są tylko wymienione kategorie |
action | wewnątrz moderation_llm_v2 | "block" odrzuca żądanie, jeśli próg zostanie przekroczony |
model_name | wewnątrz moderation_llm_v2, opcjonalnie | Model moderacji inny niż domyślny mistral-moderation-2603 |
block_on_error | obok moderation_llm_v2 | True: żą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:
| Klucz | Co wykrywa |
|---|---|
sexual | Treści o charakterze seksualnym |
hate_and_discrimination | Mowa nienawiści lub dyskryminacja ze względu na cechy chronione |
violence_and_threats | Opisane, gloryfikowane lub zagrożenia przemocą fizyczną |
dangerous | Skrajnie niebezpieczne zachowania |
criminal | Działania nielegalne |
selfharm | Samookaleczenia, samobójstwa, zaburzenia odżywiania |
health | Prośby o szczegółowe lub spersonalizowane porady medyczne |
financial | Prośby o szczegółowe lub spersonalizowane porady finansowe |
law | Prośby o szczegółowe lub spersonalizowane porady prawne |
pii | Żądanie lub udostępnienie danych osobowych |
jailbreaking | Pró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
| Kryterium | Chat Completions | Konwersacja | Agent |
|---|---|---|---|
| Gdzie deklarowane są guardrails | W każdym wywołaniu | Przy starcie (start) | Przy tworzeniu agenta |
| Dziedziczenie | Brak | Nieudokumentowane dla kolejnych tur | Wszystkie konwersacje agenta |
| Możliwość nadpisania | — | — | Tak, przez żądanie konwersacji |
| Przypadek użycia | Testy, strojenie progów | Jednorazowa konwersacja | Produkcja |
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 zenabled - Jedenaście kategorii o stałych nazwach (
hate_and_discrimination,violence_and_threats, …), każda z progiem od 0 do 1;1wyłącza - Trzy poziomy:
chat.complete(),conversations.start(),agents.create(); agenci przekazują swoje guardrails wszystkim swoim konwersacjom block_on_error=Truezapewnia zachowanie fail-safe (błąd3201)