Custom Guardrails: Imblokka Qabel il-Mudell
F'din il-paġna
Lezzjon miktub mill-ġdid fit-3 ta’ Novembru 2026. Il-verżjoni preċedenti kienet tiddeskrivi parametru fittizju
guardrails(dizzjunarju b’enabled), kategoriji li ma jeżistux (hate,violence), metoduconversation.send()nieqes fl-SDK, u tweġibiet JSON immaġinarji. Il-format uffiċjali huwa lista ta’ konfigurazzjonijietmoderation_llm_v2, u t-tweġibiet hawn taħt jaqblu mad-dokumentazzjoni. Il-kodiċi ġie vverifikat kontra t-tipi tal-SDKmistralaiverżjoni 3.7.0. Sorsi: Moderation & Guardrailing · mistralai Python SDK.
Il-Prinċipju tal-Custom Guardrails
Il-Custom Guardrails ta’ Mistral jaġixxu bħala filtru tal-input: janalizzaw il-prompt tal-utent qabel ma jilħaq il-mudell tal-ġenerazzjoni. Jekk il-kontenut jaqbeż kwalunkwe limitu (threshold) li stabbilejt, it-talba tiġi mblukkata b’żball HTTP 403. Il-mudell qatt ma jara l-prompt problematiku.
Żomm f’moħħok żewġ limitazzjonijiet mill-bidu nett. L-ewwel, il-guardrails jimmoderaw l-input biss; ma jiċċekkjawx x’jiġġenera l-mudell. Dak hu r-rwol tal-API tal-Moderazzjoni (Lezzjoni 5). It-tieni, huma jissostitwixxu x-xogħol li kieku kellek tipprogramma int stess: is-sejħa tal-API tal-Moderazzjoni, it-tqabbil tal-punteġġi mal-limiti tiegħek, u ċ-ċaħda tat-talba.
Kif Jaħdem
Meta żżid il-guardrails ma’ talba, il-fluss fuq in-naħa ta’ Mistral huwa kif ġej:
- L-applikazzjoni tiegħek tibgħat it-talba bil-parametru
guardrails. - Il-klassifikatur
mistral-moderation-2603jagħti punteġġ lill-prompt f’kull kategorija. - Jekk punteġġ jaqbeż il-limitu tiegħu, l-API tirritorna żball
403u l-mudell ma jissejjaħx. - Inkella, il-mudell jipproċessa t-talba normalment.
- It-tweġiba tinkludi kamp
guardrailsli fih il-punteġġi evalwati.
Flow: prompt → [mistral-moderation-2603] → score > threshold? → 403 (imblukkat)
→ inkella → [LLM] → tweġiba + punteġġi
Id-deċiżjoni tiddependi fuq punteġġ imqabbel ma’ limitu li tistabbilixxi int, kategorija b’kategorija, bejn 0 u 1. Limitu baxx jimblokak aktar kontenut; limitu ta’ 1 jiddiżattiva espliċitament il-kategorija.
Il-Format tal-Parametru guardrails
Il-parametru huwa lista. Kull element huwa oġġett li fih konfigurazzjoni moderation_llm_v2 u, flimkien magħha, l-għażla block_on_error:
guardrails = [
{
"block_on_error": True, # imblokka jekk il-moderazzjoni nnifisha tfalli
"moderation_llm_v2": {
"custom_category_thresholds": {
"jailbreaking": 0.3,
"criminal": 0.2,
},
"ignore_other_categories": False,
"action": "block",
},
}
]
| Ċavetta | Post | Rwol |
|---|---|---|
custom_category_thresholds | ġewwa moderation_llm_v2 | Limitu minn 0 sa 1 għal kull kategorija; 1 jiddiżattiva l-kategorija |
ignore_other_categories | ġewwa moderation_llm_v2 | True: jiġu evalwati biss il-kategoriji elenkati |
action | ġewwa moderation_llm_v2 | "block" biex tiċħad it-talba jekk jinqabeż limitu |
model_name | ġewwa moderation_llm_v2, opzjonali | Mudell ta’ moderazzjoni differenti mill-predefinit mistral-moderation-2603 |
block_on_error | maġenb moderation_llm_v2 | True: it-talba tiġi mblukkata jekk tevalwazzjoni tfalli |
Tista’ tpoġġi oġġetti multipli fil-lista: it-talba tiġi mblukkata malli wieħed minnhom jiġi attivat. Kull oġġett fih konfigurazzjoni waħda biss ta’ moderation_llm_v2. Konfigurazzjoni eqdem, moderation_llm_v1, għadha teżisti fl-SDK b’kategoriji mill-mudell deprekat mistral-moderation-2411 (deprekat fil-31 ta’ Marzu 2026): tużahiex għal proġetti ġodda.
Il-Ħdax-il Kategorija
Iċ-ċwievet f’custom_category_thresholds huma ffissati; ċavetta oħra, bħal violence jew hate, ma tkun tfisser xejn:
| Ċavetta | X’tiskopri |
|---|---|
sexual | Kontenut sesswali espliċitu |
hate_and_discrimination | Mibegħda jew diskriminazzjoni bbażata fuq karatteristiċi protetti |
violence_and_threats | Vjolenza fiżika deskritta, igglorifikata jew imhedda |
dangerous | Imġiba estremament perikoluża |
criminal | Attivitajiet illegali |
selfharm | Awto-ħsara, suwiċidju, disturbi fl-ikel |
health | Talbiet għal pariri mediċi dettaljati jew personalizzati |
financial | Talbiet għal pariri finanzjarji dettaljati jew personalizzati |
law | Talbiet għal pariri legali dettaljati jew personalizzati |
pii | Data personali mitluba jew maqsuma |
jailbreaking | Tentattivi biex jinġiebu biċ-ċirkostanza r-regoli tal-mudell |
Il-Lezzjoni 6 terġa’ tgħaddi minn kull waħda minn dawn u tiddiskuti l-għażla tal-limiti.
It-Tliet Livelli ta’ Applikazzjoni
L-istess parametru huwa aċċettat f’tliet postijiet. L-għażla tiegħek tiddetermina fejn tgħix il-politika tas-sigurtà tiegħek u min jista’ jinsa japplikaha.
Livell 1: Talba ta’ Chat Completions
Tgħaddi guardrails fis-sejħa chat.complete(). Kull talba ġġorr ir-regoli tagħha stess: prattiku għall-esplorazzjoni, iżda riskjuż fuq skala kbira, peress li sejħa waħda mingħajr il-parametru tgħaddi mingħajr kontroll.
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)
Każ ta’ użu: Prototipar, sejħiet waħda biss, aġġustament tal-limiti.
Livell 2: Konversazzjoni
Bl-API tal-Konversazzjonijiet, tgħaddi guardrails fil-bidu, f’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)
Il-messaġġi sussegwenti jintbagħtu b’client.beta.conversations.append(conversation_id=conversation.conversation_id, inputs=...). Dan il-metodu ma jaċċettax parametru guardrails fl-SDK 3.7.0, u d-dokumentazzjoni ma tispeċifikax jekk il-guardrails tal-bidu japplikawx għad-dawriet sussegwenti. Għal protezzjoni garantita fuq kull dawra, waħħal il-guardrails ma’ aġent.
Każ ta’ użu: Konversazzjoni waħda mingħajr aġent, jew biex tibdel il-guardrails ta’ aġent għal talba speċifika.
Livell 3: Aġent
Il-Guardrails mgħoddija lil client.beta.agents.create() isiru parti mid-definizzjoni tal-aġent. Skont id-dokumentazzjoni, il-konversazzjonijiet kollha li jużaw dan l-aġent jirtuhom mingħajr ħtieġa li terġa’ tgħoddihom. Madankollu, talba ta’ konversazzjoni tista’ tibdilha billi tgħaddi l-guardrails tagħha stess.
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!")
Każ ta’ użu: Produzzjoni, meta timijiet jew servizzi multipli jsejħu l-istess assistent.
X’Jirritornaw il-Guardrails
Meta t-talba tgħaddi, it-tweġiba tal-API tinkludi, flimkien mal-kampijiet standard, kamp guardrails: lista b’riżultat wieħed għal kull guardrail. Hawnhekk dak il-kamp mill-eżempju tad-dokumentazzjoni:
{
"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 }
}
}
}
]
}
B’ignore_other_categories issettjat għal True, biss il-kategoriji elenkati fil-limiti tiegħek jidhru f’dan ir-riżultat. Fl-SDK tal-Python, tweġiba ta’ konversazzjoni tesponi dan il-kamp (conversation.guardrails). It-tweġiba chat.complete(), madankollu, m’għandha l-ebda kamp iddedikat għalih fl-SDK 3.7.0: tintilef hemmhekk. Jekk trid tirreġistra l-punteġġi—u huwa utli li tkun taf aktar tard jekk il-limiti tiegħek humiex wisq laxki jew wisq stretti—uża l-konversazzjonijiet jew aqra t-tweġiba HTTP raw.
Meta jinqabeż limitu, l-API tirritorna żball 403 li l-korp tiegħu jiddettalja d-deċiżjoni, kategorija b’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"
}
}
}
}
L-SDK imbagħad iqajjem errors.SDKError, fejn status_code huwa 403 u body fiha dan il-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}")
Dan il-payload jippermettilek tispjega blokk matul appell: liema kategorija, liema punteġġ, liema limitu.
Fl-aħħar nett, hemm il-każ degradat. Jekk l-evalwazzjoni nnifisha tfalli u block_on_error ikun True, it-talba tiġi rifjutata bil-kodiċi ta’ żball 3201 u l-messaġġ Request blocked due to error in guardrail evaluation and block_on_error is set to True. Dan huwa mod fail-safe: meta jkollok dubju, imblokka. B’block_on_error issettjat għal False (il-valur predefinit tiegħu fl-SDK), it-talba tgħaddi mingħajr kontroll.
L-Għażla tal-Livell It-Tajjeb
| Kriterju | Chat Completions | Konversazzjoni | Aġent |
|---|---|---|---|
| Fejn jiġu ddikjarati l-guardrails | F’kull sejħa | Fil-bidu (start) | Fil-ħolqien tal-aġent |
| Wirt | L-ebda | Mhux iddokumentat għad-dawriet sussegwenti | Il-konversazzjonijiet kollha tal-aġent |
| Jista’ jinbidel | — | — | Iva, minn talba ta’ konversazzjoni |
| Każ ta’ użu | Testijiet, aġġustament tal-limiti | Konversazzjoni waħda | Produzzjoni |
Fil-prattika, aġġusta l-limiti tiegħek fuq talbiet ta’ Chat Completions billi tuża każijiet reali, imbagħad mexxi l-politika lejn aġent malli l-kodiċi joħroġ mill-magna tiegħek: ma jkunx hemm aktar sejħiet minsija.
Punti Ewlenin
- Il-Guardrails jimblokkaw il-prompts qabel il-mudell permezz ta’ żball
403; ma jiċċekkjawx l-output - Il-parametru huwa lista ta’ oġġetti
{"block_on_error": ..., "moderation_llm_v2": {...}}, mhux dizzjunarju b’enabled - Ħdax-il kategorija b’ismijiet iffissati (
hate_and_discrimination,violence_and_threats, …), kull waħda b’limitu minn 0 sa 1;1jiddiżattiva - Tliet livelli:
chat.complete(),conversations.start(),agents.create(); l-aġenti jgħaddu l-guardrails tagħhom lill-konversazzjonijiet kollha tagħhom block_on_error=Truejiżgura mġiba fail-safe (żball3201)