Custom Guardrails: Block Before the Model
Na tej strani
Lekcija je bila ponovno napisana 3. novembra 2026. Prejšnja različica je opisovala fiktivni parameter
guardrails(slovar zenabled), neobstoječe kategorije (hate,violence), manjkajočo metodoconversation.send()v SDK-ju in namišljene odgovore JSON. Uradni format je seznam konfiguracijmoderation_llm_v2, spodnji odgovori pa ustrezajo dokumentaciji. Koda je bila preverjena glede na tipe SDK-jamistralairazličice 3.7.0. Viri: Moderation & Guardrailing · mistralai Python SDK.
Načelo prilagojenih varoval (Custom Guardrails)
Prilagojene varovale Mistral delujejo kot filter vhodnih podatkov: analizirajo uporabnikov poziv preden ta doseže model za generiranje. Če vsebina preseže kateri koli prag, ki ste ga nastavili, je zahteva blokirana s napako HTTP 403. Model problematičnega poziva nikoli ne vidi.
Od samega začetka imej v mislih dve omejitvi. Prvič, varovale moderirajo samo vhod; ne preverjajo tega, kar model ustvari. To je naloga API-ja za moderiranje (5. lekcija). Drugič, nadomeščajo delo, ki bi ga sicer moral kodirati sam: klicanje API-ja za moderiranje, primerjanje rezultatov s tvojimi pragovi in zavrnitev zahteve.
Kako deluje
Ko zahtevi dodaš varovale, je potek na strani Mistrala naslednji:
- Tvoja aplikacija pošlje zahtevo s parametrom
guardrails. - Klasifikator
mistral-moderation-2603ovrednoti poziv v vsaki kategoriji. - Če rezultat preseže prag, API vrne napako
403in model ni poklican. - V nasprotnem primeru model obdela zahtevo običajno.
- Odgovor vključuje polje
guardrails, ki vsebuje ovrednotene rezultate.
Flow: prompt → [mistral-moderation-2603] → score > threshold? → 403 (blocked)
→ else → [LLM] → response + scores
Odločitev temelji na rezultatu, primerjanem s pragom, ki ga nastaviš ti, kategorija za kategorijo, med 0 in 1. Nizek prag blokira več vsebine; prag 1 kategorijo izrecno onemogoči.
Format parametra guardrails
Parameter je seznam. Vsak element je objekt, ki vsebuje konfiguracijo moderation_llm_v2 in ob njej možnost block_on_error:
guardrails = [
{
"block_on_error": True, # block if moderation itself fails
"moderation_llm_v2": {
"custom_category_thresholds": {
"jailbreaking": 0.3,
"criminal": 0.2,
},
"ignore_other_categories": False,
"action": "block",
},
}
]
| Ključ | Lokacija | Vloga |
|---|---|---|
custom_category_thresholds | znotraj moderation_llm_v2 | Prag od 0 do 1 na kategorijo; 1 onemogoči kategorijo |
ignore_other_categories | znotraj moderation_llm_v2 | True: ovrednotene so samo navedene kategorije |
action | znotraj moderation_llm_v2 | "block" za zavrnitev zahteve, če je prag presežen |
model_name | znotraj moderation_llm_v2, opcijsko | Model za moderiranje, drugačen od privzetega mistral-moderation-2603 |
block_on_error | ob moderation_llm_v2 | True: zahteva je blokirana, če ovrednotenje ne uspe |
Na seznam lahko dodaš več objektov: zahteva je blokirana, takoj ko se sproži kateri koli od njih. Vsak objekt vsebuje samo eno konfiguracijo moderation_llm_v2. Starejša konfiguracija, moderation_llm_v1, še vedno obstaja v SDK-ju s kategorijami iz zastarelega modela mistral-moderation-2411 (zastarel 31. marca 2026): ne uporabljaj je za nove projekte.
Enajst kategorij
Ključi v custom_category_thresholds so fiksni; drug ključ, kot sta violence ali hate, ne ustreza ničemer:
| Ključ | Kaj zazna |
|---|---|
sexual | Eksplicitna spolna vsebina |
hate_and_discrimination | Sovraštvo ali diskriminacija na podlagi zaščitenih značilnosti |
violence_and_threats | Opisano, poveličevano ali ogrožajoče fizično nasilje |
dangerous | Izjemno nevarna vedenja |
criminal | Nezakonite dejavnosti |
selfharm | Samopoškodovanje, samomor, motnje hranjenja |
health | Zahteve za podrobne ali personalizirane zdravstvene nasvete |
financial | Zahteve za podrobne ali personalizirane finančne nasvete |
law | Zahteve za podrobne ali personalizirane pravne nasvete |
pii | Zahtevani ali deljeni osebni podatki |
jailbreaking | Poskusi obida pravil modela |
- lekcija ponovno obravnava vsako od teh in razpravlja o izbiri pragov.
Tri ravni uporabe
Isti parameter je sprejet na treh mestih. Tvoja izbira določa, kje živi tvoja varnostna politika in kdo bi jo lahko pozabil uporabiti.
1. raven: Zahteva za dopolnjevanje klepeta (Chat Completions)
Parameter guardrails posreduješ v klicu chat.complete(). Vsaka zahteva nosi svoja pravila: praktično za raziskovanje, a tvegano v velikem obsegu, saj en sam klic brez parametra neopažen uide nadzoru.
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)
Primer uporabe: Prototipiranje, enkratni klici, uglaševanje pragov.
2. raven: Pogovor (Conversation)
Z API-jem za pogovore posreduješ guardrails ob zagonu, v 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)
Naslednja sporočila se pošljejo z client.beta.conversations.append(conversation_id=conversation.conversation_id, inputs=...). Ta metoda v SDK-ju 3.7.0 ne sprejme parametra guardrails, dokumentacija pa ne določa, ali se zagonske varovale uporabljajo za naslednje poteze. Za zagotovljeno zaščito pri vsaki potezi pripni varovale agentu.
Primer uporabe: Enkraten pogovor brez agenta ali preglasitev varoval agenta za določeno zahtevo.
3. raven: Agent
Varovale, posredovane v client.beta.agents.create(), postanejo del definicije agenta. Po dokumentaciji vsi pogovori, ki uporabljajo tega agenta, podedujejo te varovale, ne da bi jih bilo treba ponavljati. Vendar pa lahko zahteva za pogovor te varovale preglasi tako, da posreduje svoje lastne 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!")
Primer uporabe: Produkcijsko okolje, ko več ekip ali storitev kliče istega pomočnika.
Kaj vrnejo varovale
Ko zahteva uspe, odgovor API-ja vključuje poleg standardnih polj še polje guardrails: seznam z enim rezultatom na varovalo. Tukaj je to polje iz primera v 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 }
}
}
}
]
}
Če je ignore_other_categories nastavljen na True, se v tem rezultatu prikažejo samo kategorije, navedene v tvojih pragovih. V Python SDK-ju odgovor pogovora izpostavi to polje (conversation.guardrails). Odgovor chat.complete() pa v SDK-ju 3.7.0 nima določenega polja za to: tam se izgubi. Če želiš beležiti rezultate – kar je koristno, da kasneje veš, ali so tvoji pragovi preširoki ali preozki – uporabi pogovore ali preberi surov odgovor HTTP.
Ko je prag presežen, API vrne napako 403, katere telo podrobno opisuje odločitev, kategorija za kategorijo:
{
"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 nato sproži errors.SDKError, kjer je status_code enak 403 in body vsebuje ta 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}")
Ta vsebina ti omogoča, da med pritožbo razložiš blokado: katera kategorija, kakšen rezultat, kakšen prag.
Nazadnje, tu je še poslabšan primer. Če samo ovrednotenje ne uspe in je block_on_error nastavljen na True, je zahteva zavrnjena s kodo napake 3201 in sporočilom Request blocked due to error in guardrail evaluation and block_on_error is set to True. To je način fail-safe: ko si v dvomih, blokiraj. Če je block_on_error nastavljen na False (njegova privzeta vrednost v SDK-ju), bi zahteva šla skozi brez nadzora.
Izbira prave ravni
| Merilo | Chat Completions | Conversation | Agent |
|---|---|---|---|
| Kje so varovale deklarirane | V vsakem klicu | Ob zagonu (start) | Ob ustvarjanju agenta |
| Dedovanje | Nobeno | Nedokumentirano za naslednje poteze | Vsi pogovori agenta |
| Možnost preglasitve | — | — | Da, z zahtevo za pogovor |
| Primer uporabe | Testi, uglaševanje pragov | Enkraten pogovor | Produkcijsko okolje |
V praksi uglašaj svoje pragove na zahtevah Chat Completions z uporabo realnih primerov, nato pa politiko premakni na agenta, takoj ko koda zapusti tvoj računalnik: tako ne bo več pozabljenih klicev.
Ključne ugotovitve
- Varovale blokirajo pozive pred modelom z napako
403; ne preverjajo izhoda - Parameter je seznam objektov
{"block_on_error": ..., "moderation_llm_v2": {...}}, ne slovar zenabled - Enajst kategorij s fiksnimi imeni (
hate_and_discrimination,violence_and_threats, …), vsaka s pragom od 0 do 1;1onemogoči - Tri ravni:
chat.complete(),conversations.start(),agents.create(); agenti posredujejo svoje varovale vsem svojim pogovorom block_on_error=Truezagotavlja vedenje fail-safe (napaka3201)