Custom Guardrails: Blockiraj prije modela
Na ovoj stranici
Lekcija je ponovno napisana 3. studenoga 2026. Prethodna verzija opisivala je fiktivni parametar
guardrails(rječnik senabled), nepostojeće kategorije (hate,violence), nedostajuću metoduconversation.send()u SDK-u i imaginarne JSON odgovore. Službeni format je lista konfiguracijamoderation_llm_v2, a odgovori u nastavku usklađeni su s dokumentacijom. Kod je verificiran prema tipovimamistralaiSDK verzije 3.7.0. Izvori: Moderation & Guardrailing · mistralai Python SDK.
Načelo prilagođenih guardrailsa
Mistralovi prilagođeni guardrailsi djeluju kao ulazni filtar: analiziraju upit korisnika prije nego što stigne do modela za generiranje. Ako sadržaj prijeđe bilo koji prag koji si postavio, zahtjev se blokira HTTP pogreškom 403. Model nikada ne vidi problematičan upit.
Od samog početka imaj na umu dva ograničenja. Prvo, guardrailsi moderiraju samo ulaz; ne provjeravaju što model generira. To je uloga Moderation API-ja (Lekcija 5). Drugo, oni zamjenjuju posao koji bi inače morao sam kodirati: pozivanje Moderation API-ja, usporedbu rezultata s tvojim pragovima i odbijanje zahtjeva.
Kako to funkcionira
Kada dodaš guardrailse u zahtjev, tijek na strani Mistrala je sljedeći:
- Tvoja aplikacija šalje zahtjev s parametrom
guardrails. - Klasifikator
mistral-moderation-2603boduje upit u svakoj kategoriji. - Ako rezultat prijeđe prag, API vraća pogrešku
403i model se ne poziva. - Inače, model obrađuje zahtjev normalno.
- Odgovor uključuje polje
guardrailskoje sadrži procijenjene rezultate.
Flow: prompt → [mistral-moderation-2603] → score > threshold? → 403 (blocked)
→ else → [LLM] → response + scores
Odluka se temelji na rezultatu uspoređenom s pragom koji postavljaš ti, kategorija po kategorija, između 0 i 1. Nizak prag blokira više sadržaja; prag od 1 izričito onemogućuje kategoriju.
Format parametra guardrails
Parametar je lista. Svaki element je objekt koji sadrži konfiguraciju moderation_llm_v2 i, uz nju, opciju block_on_error:
guardrails = [
{
"block_on_error": True, # blockiraj ako sama moderacija ne uspije
"moderation_llm_v2": {
"custom_category_thresholds": {
"jailbreaking": 0.3,
"criminal": 0.2,
},
"ignore_other_categories": False,
"action": "block",
},
}
]
| Ključ | Lokacija | Uloga |
|---|---|---|
custom_category_thresholds | unutar moderation_llm_v2 | Prag od 0 do 1 po kategoriji; 1 onemogućuje kategoriju |
ignore_other_categories | unutar moderation_llm_v2 | True: procjenjuju se samo navedene kategorije |
action | unutar moderation_llm_v2 | "block" za odbijanje zahtjeva ako je prag premašen |
model_name | unutar moderation_llm_v2, opcionalno | Model za moderaciju drugačiji od zadanog mistral-moderation-2603 |
block_on_error | uz moderation_llm_v2 | True: zahtjev se blokira ako procjena ne uspije |
U listu možeš staviti više objekata: zahtjev se blokira čim bilo koji od njih okine. Svaki objekt sadrži samo jednu konfiguraciju moderation_llm_v2. Starija konfiguracija, moderation_llm_v1, još uvijek postoji u SDK-u s kategorijama iz zastarjelog modela mistral-moderation-2411 (zastario 31. ožujka 2026.): nemoj je koristiti za nove projekte.
Jedanaest kategorija
Ključevi u custom_category_thresholds su fiksni; drugi ključ, poput violence ili hate, ne odgovara ničemu:
| Ključ | Što detektira |
|---|---|
sexual | Eksplicitan seksualni sadržaj |
hate_and_discrimination | Mržnja ili diskriminacija na temelju zaštićenih obilježja |
violence_and_threats | Opisano, veličano ili prijećeno fizičko nasilje |
dangerous | Izuzetno opasna ponašanja |
criminal | Ilegalne aktivnosti |
selfharm | Samoozljeđivanje, samoubojstvo, poremećaji prehrane |
health | Zahtjevi za detaljne ili personalizirane medicinske savjete |
financial | Zahtjevi za detaljne ili personalizirane financijske savjete |
law | Zahtjevi za detaljne ili personalizirane pravne savjete |
pii | Zatraženi ili podijeljeni osobni podaci |
jailbreaking | Pokušaji zaobilaženja pravila modela |
Lekcija 6 ponovno obrađuje svaku od njih i raspravlja o odabiru pragova.
Tri razine primjene
Isti se parametar prihvaća na tri mjesta. Tvoj izbor određuje gdje živi tvoja sigurnosna politika i tko bi je mogao zaboraviti primijeniti.
Razina 1: Zahtjev za Chat Completions
Proslijeđuješ guardrails u pozivu chat.complete(). Svaki zahtjev nosi svoja pravila: praktično za istraživanje, ali rizično u velikom obujmu, jer jedan poziv bez parametra prolazi neprovjeren.
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)
Slučaj upotrebe: Prototipiranje, jednokratni pozivi, ugađanje pragova.
Razina 2: Razgovor (Conversation)
Kod Conversations API-ja, proslijeđuješ guardrails pri pokretanju, u 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)
Naknadne poruke šalju se s client.beta.conversations.append(conversation_id=conversation.conversation_id, inputs=...). Ova metoda ne prihvaća parametar guardrails u SDK-u 3.7.0, a dokumentacija ne specificira primjenjuju li se guardrailsi s početka na naknadne okrete. Za zajamčenu zaštitu u svakom okretu, pričvrsti guardrailse na agenta.
Slučaj upotrebe: Jednokratni razgovor bez agenta ili nadjačavanje guardrailsa agenta za specifičan zahtjev.
Razina 3: Agent
Guardrailsi proslijeđeni u client.beta.agents.create() postaju dio definicije agenta. Prema dokumentaciji, svi razgovori koji koriste ovog agenta nasljeđuju ih bez potrebe za ponavljanjem. Međutim, zahtjev za razgovor može ih nadjačati proslijeđivanjem vlastitih 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!")
Slučaj upotrebe: Produkcija, kada više timova ili servisa poziva istog asistenta.
Što guardrailsi vraćaju
Kada zahtjev prođe, odgovor API-ja uključuje, uz standardna polja, polje guardrails: listu s jednim rezultatom po guardrailsu. Evo tog polja iz primjera u dokumentaciji:
{
"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 }
}
}
}
]
}
Ako je ignore_other_categories postavljen na True, u ovom se rezultatu pojavljuju samo kategorije navedene u tvojim pragovima. U Python SDK-u, odgovor razgovora izlaže ovo polje (conversation.guardrails). Odgovor chat.complete(), međutim, nema namjensko polje za to u SDK-u 3.7.0: ondje se gubi. Ako želiš bilježiti rezultate – a korisno je kasnije znati jesu li tvoji pragovi preširoki ili preuski – koristi razgovore ili čitaj sirovi HTTP odgovor.
Kada je prag premašen, API vraća pogrešku 403 čije tijelo detaljno opisuje odluku, kategorija po kategorija:
{
"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 tada podiže errors.SDKError, gdje je status_code 403, a body sadrži ovaj 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}")
Ovaj teret omogućuje ti da objasniš blokadu tijekom žalbe: koja kategorija, koji rezultat, koji prag.
Konačno, tu je i degradirani slučaj. Ako sama procjena ne uspije, a block_on_error je True, zahtjev se odbija s kodom pogreške 3201 i porukom Request blocked due to error in guardrail evaluation and block_on_error is set to True. Ovo je način fail-safe: u slučaju nedoumice, blokiraj. Ako je block_on_error postavljen na False (njegova zadana vrijednost u SDK-u), zahtjev bi prošao neprovjeren.
Odabir prave razine
| Kriterij | Chat Completions | Razgovor (Conversation) | Agent |
|---|---|---|---|
| Gdje se deklariraju guardrailsi | U svakom pozivu | Pri pokretanju (start) | Pri stvaranju agenta |
| Nasljeđivanje | Nema | Nedokumentirano za naknadne okrete | Svi razgovori agenta |
| Mogućnost nadjačavanja | — | — | Da, zahtjevom za razgovor |
| Slučaj upotrebe | Testovi, ugađanje pragova | Jednokratni razgovor | Produkcija |
U praksi, ugodi svoje pragove na zahtjevima za Chat Completions koristeći stvarne slučajeve, a zatim premjesti politiku na agenta čim kod napusti tvoje računalo: više neće biti zaboravljenih poziva.
Ključne točke
- Guardrailsi blokiraju upite prije modela putem pogreške
403; ne provjeravaju izlaz - Parametar je lista objekata
{"block_on_error": ..., "moderation_llm_v2": {...}}, a ne rječnik senabled - Jedanaest kategorija s fiksnim imenima (
hate_and_discrimination,violence_and_threats, …), svaka s pragom od 0 do 1;1onemogućuje - Tri razine:
chat.complete(),conversations.start(),agents.create(); agenti prosljeđuju svoje guardrailse svim svojim razgovorima block_on_error=Trueosigurava ponašanje fail-safe (pogreška3201)