Ikkonfigura l-guardrails fil-Python
F'din il-paġna
Lezzjoni miktuba mill-ġdid fit-3 ta’ Novembru 2026. Il-verżjoni preċedenti kkonfigurat il-guardrails bl-użu ta’ dizzjunarju inventat (
enabled), kategoriji li ma jeżistux (hate,violence,unpredictable), iddikjarat li kategoriji mhux elenkati żammew “limiti standard”, u ttestjate.status_code == 3201, għalkemm3201huwa kodiċi ta’ żball fil-korp tar-rispons, mhux status HTTP. Il-konfigurazzjoni issa ssegwi l-format uffiċjali, u l-kodiċi ġie vverifikat kontra t-tipi tal-SDKmistralai3.7.0. Sorsi: Moderation & Guardrailing · mistralai Python SDK.
Mit-teorija għall-kodiċi
Issa tifhem kif jaħdmu l-guardrails. F’din il-lezzjoni, se tikkonfigurahom b’mod preċiż: agħżel il-kategoriji tiegħek, iddefinixxi l-limiti tiegħek, u ġesti l-imblukkar fil-kodiċi Python tiegħek.
Ibda bl-SDK ta’ Mistral installat (il-guardrails jeħtieġu l-verżjoni 2 jew aktar tard) u ċavetta API mgħobbija mill-ambjent minflok ma tkun imwaħħla fil-kodiċi (hardcoded).
pip install "mistralai>=2"
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Il-parametru guardrails fid-dettall
Il-parametru guardrails huwa lista. Kull element jgħaqqad l-għażla block_on_error ma’ konfigurazzjoni moderation_llm_v2, li fiha nnifisha fiha l-limiti (thresholds), l-għażla ignore_other_categories, u l-azzjoni:
from mistralai.client.models import GuardrailConfigTypedDict
GUARDRAILS: list[GuardrailConfigTypedDict] = [
{
# Imblokka jekk l-evalwazzjoni nnifisha tfalli
"block_on_error": True,
"moderation_llm_v2": {
# Limiti għal kull kategorija, minn 0 sa 1 (1 jiddiżattiva l-kategorija)
"custom_category_thresholds": {
"sexual": 0.2,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.3,
"dangerous": 0.2,
"criminal": 0.1,
"selfharm": 0.1,
"health": 0.5,
"financial": 0.5,
"law": 0.5,
"pii": 0.2,
"jailbreaking": 0.1,
},
"ignore_other_categories": False,
# Azzjoni meta jinqabeż il-limitu
"action": "block",
},
}
]
Il-mudell ta’ moderazzjoni standard huwa mistral-moderation-2603; iċ-ċavetta fakultattiva model_name tippermettilek tispeċifika wieħed differenti.
L-annotazzjoni list[GuardrailConfigTypedDict] mhix obbligatorja, iżda tiswa li tużaha: l-SDK jiddeskrivi kull ċavetta permessa, allura verifikatur tat-tipi bħal pyright jew mypy se jindika kategorija miktuba ħażin (violence minflok violence_and_threats) li l-API nnifisha ma taqbidx.
custom_category_thresholds
Dan huwa l-qalb tal-konfigurazzjoni. Kull kategorija tikseb limitu bejn 0 u 1, imqabbel mal-punteġġ li l-klassifikatur jagħti lill-prompt. Aktar ma jkun baxx il-limitu, aktar il-filtru jimblokka, bir-riskju li jiċħad talbiet leġittimi. Limitu ta’ 1 jiddiżattiva espliċitament il-kategorija. Mistral ma tippubblikax grilja ta’ valuri rrakkomandati: trid tikkalibrahom fuq l-eżempji tiegħek stess (lezzjoni 7).
Il-valuri jagħmlu sens biss fil-kuntest tal-applikazzjoni tiegħek. Chatbot miftuħ għall-pubbliku jisserraħ il-kategoriji sensittivi bl-aktar settings baxxi, filwaqt li għodda interna għall-professjonisti tas-saħħa trid tippermetti mistoqsijiet mediċi filwaqt li tibqa’ stretta fuq id-data personali.
# Chatbot pubbliku: limiti baxxi ħafna
public_thresholds = {
"sexual": 0.1,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.1,
"criminal": 0.1,
"selfharm": 0.1,
}
# Għodda medika interna: is-saħħa diżattivata, PII għadha ssorveljata
medical_thresholds = {
"sexual": 0.2,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.3,
"health": 1, # jiddiżattiva l-kategorija: il-mistoqsijiet mediċi huma l-funzjoni ewlenija tal-għodda
"pii": 0.1,
}
Kategoriji li ma telenkax
X’jiġri mill-kategoriji nieqsa minn custom_category_thresholds? Id-dokumentazzjoni ma tgħidhiex espliċitament, iżda l-eżempju ta’ imblukkar tagħha huwa sinifikanti: il-kategoriji mhux elenkati jidhru hemm b’limitu ta’ 1.0, innutati iżda ineffettivi. Tiddependix fuq limitu standard: elenka kull kategorija li għandha tkun kapaċi timblokka.
L-għażla ignore_other_categories tikkontrolla biss x’jiġi evalwat u rritornat. Meta tkun issettjata għal False, il-kategoriji evalwati kollha jidhru fir-riżultat; meta tkun True, biss dawk li elenkajt huma evalwati.
TARGETED_GUARDRAILS: list[GuardrailConfigTypedDict] = [
{
"block_on_error": True,
"moderation_llm_v2": {
"custom_category_thresholds": {
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.2,
},
"ignore_other_categories": True, # jevalwa biss dawn iż-żewġ kategoriji
"action": "block",
},
}
]
Twissija: b’din il-konfigurazzjoni, tentattiv ta’ jailbreak jew talba għal data personali tgħaddi mingħajr kontroll. Irrestrinġi l-lista biss għal raġuni speċifika.
Eżempju sħiħ: chatbot bil-guardrails
Hawnhekk hemm funzjoni minima: tibgħat il-messaġġ bil-konfigurazzjoni sħiħa u tbiddel imblukkar f’rispons li jista’ jinqara għall-utent.
from mistralai.client import errors
def chat_securise(message_utilisateur: str) -> str:
"""Tibgħat messaġġ protett minn guardrails."""
try:
response = client.chat.complete(
model="mistral-large-latest",
messages=[
{"role": "system", "content": "You are a professional assistant."},
{"role": "user", "content": message_utilisateur},
],
guardrails=GUARDRAILS,
)
except errors.SDKError as e:
if e.status_code == 403:
return "Jiddispjaċini, din it-talba ma tistax tiġi pproċessata."
raise
contenu = response.choices[0].message.content
return contenu if isinstance(contenu, str) else ""
print(chat_securise("Explain machine learning to me"))
Żewġ noti. message.content tista’ tkun stringa jew lista ta’ partijiet skont il-mudell, għalhekk iċ-ċekk isinstance. U r-rispons minn chat.complete() ma jesponix il-punteġġi tal-guardrails fl-SDK 3.7.0: biex tirreġistrahom (log), uża l-API tal-Conversations, li r-rispons tagħha iġorrhom f’guardrails.
Ġesti l-iżbalji ta’ imblukkar b’mod nadif
Trid tiddistingwi żewġ fallimenti li ma jsejħux l-istess messaġġ u lanqas l-istess allarm: imblukkar tal-politika tal-kontenut, li jirritorna l-istatus HTTP 403, u falliment tal-evalwazzjoni tal-moderazzjoni b’block_on_error attivat, li l-korp tar-rispons jissignalah bil-kodiċi 3201. It-tnejn jaslu bħala errors.SDKError, li l-body tiegħu fih il-JSON irritornat mill-API:
import json
from typing import Any
from mistralai.client import errors
def chat_avec_gestion_erreurs(message_utilisateur: str) -> dict[str, Any]:
"""Chat li jiddistingwi l-imblukkar tal-politika mill-fallimenti tal-moderazzjoni."""
try:
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": message_utilisateur}],
guardrails=GUARDRAILS,
)
except errors.SDKError as e:
try:
corps = json.loads(e.body)
except json.JSONDecodeError:
raise e
if corps.get("code") == 3201:
return {
"status": "error",
"content": "Is-servizz ta' moderazzjoni mhux disponibbli. It-talba ġiet imblukkata bħala prekawzjoni.",
}
if e.status_code == 403:
decisions = corps["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
return {
"status": "blocked",
"content": "Il-messaġġ tiegħek ġie mblukkat mill-politika ta' sigurtà tagħna.",
"categories": [nom for nom, d in decisions.items() if d["violated"]],
}
raise
return {"status": "ok", "content": response.choices[0].message.content}
Iċċekkja l-kodiċi 3201 l-ewwel, għax id-dokumentazzjoni ma tispeċifikax l-istatus HTTP għal dan l-iżball. Il-kategoriji miksurin jiġu minn decisions, fejn kull entrata tagħti threshold, score, u violated: dan huwa dak li se tirreġistra biex tispjega imblukkar.
L-aħjar prattiki tal-konfigurazzjoni
Ibda ristrettiv, imbagħad irrilassa. Limiti baxxi fil-bidu jgħinuk tiskopri pożittivi foloz (false positives) filwaqt li l-volum għadu ġestibbli, u kull żieda tiġi deċiża abbażi ta’ każijiet osservati minflok intuizzjoni:
# Fażi 1: tnedija (ristrettiva ħafna)
phase1 = {"hate_and_discrimination": 0.1, "violence_and_threats": 0.1, "criminal": 0.1}
# Fażi 2: wara li tanalizza l-pożittivi foloz
phase2 = {"hate_and_discrimination": 0.15, "violence_and_threats": 0.25, "criminal": 0.1}
# Fażi 3: produzzjoni stabbli
phase3 = {"hate_and_discrimination": 0.2, "violence_and_threats": 0.3, "criminal": 0.15}
Dawn il-valuri juru l-approċċ; tiegħek se jiġu mill-kejl tiegħek stess. Żomm block_on_error issettjat għal True fil-produzzjoni: il-valur standard tiegħu fl-SDK huwa False, u falliment fil-moderazzjoni imbagħad iħalli kontenut mhux ivverifikat jgħaddi. Fl-aħħar nett, id-dokumentazzjoni twissi li l-mudell tal-moderazzjoni jevolvi: il-politiki bbażati fuq il-punteġġi jistgħu jeħtieġu rikalibrazzjoni.
Punti Ewlenin
guardrailshija lista ta’ oġġetti{"block_on_error": ..., "moderation_llm_v2": {...}}- Ġewwa
moderation_llm_v2:custom_category_thresholds,ignore_other_categories,action, u fakultattivamentmodel_name - Limiti minn
0sa1; aktar baxx huwa aktar strett;1jiddiżattiva kategorija. Ielenka kull kategorija li għandha timblokka - Imblukkar iqajjem
errors.SDKErrorb’status_code == 403; falliment b’block_on_erroriġorr il-kodiċi3201fil-korp - Żomm
block_on_error=Truefil-produzzjoni, peress li l-valur standard huwaFalse