Configurarea barierelor de protecție în Python
Pe această pagină
Lecție rescrisă la 3 noiembrie 2026. Versiunea anterioară configura barierele de protecție folosind un dicționar inventat (
enabled), categorii inexistente (hate,violence,unpredictable), afirma că categoriile nemenționate păstrau „praguri implicite“ și testae.status_code == 3201, deși3201este un cod de eroare din corpul răspunsului, nu un statut HTTP. Configurația respectă acum formatul oficial, iar codul a fost verificat față de tipurile SDKmistralai3.7.0. Surse: Moderation & Guardrailing · mistralai Python SDK.
De la teorie la cod
Ați înțeles acum cum funcționează barierele de protecție. În această lecție, le veți configura cu precizie: selectați categoriile, definiți pragurile și gestionați blocările în codul dumneavoastră Python.
Începeți prin instalarea SDK-ului Mistral (barierele de protecție necesită versiunea 2 sau ulterioară) și încărcați cheia API din variabilele de mediu, nu hardcoded.
pip install "mistralai>=2"
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Parametrul guardrails în detaliu
Parametrul guardrails este o listă. Fiecare element asociază opțiunea block_on_error cu o configurație moderation_llm_v2, care conține la rândul ei pragurile, opțiunea ignore_other_categories și acțiunea:
from mistralai.client.models import GuardrailConfigTypedDict
GUARDRAILS: list[GuardrailConfigTypedDict] = [
{
# Blochează dacă evaluarea însăși eșuează
"block_on_error": True,
"moderation_llm_v2": {
# Praguri per categorie, de la 0 la 1 (1 dezactivează categoria)
"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,
# Acțiune la depășirea pragului
"action": "block",
},
}
]
Modelul de moderare implicit este mistral-moderation-2603; cheia opțională model_name vă permite să specificați unul diferit.
Adnotarea list[GuardrailConfigTypedDict] nu este obligatorie, dar merită folosită: SDK descrie fiecare cheie permisă, astfel încât un verificator de tipuri precum pyright sau mypy va semnala o categorie scrisă greșit (violence în loc de violence_and_threats) pe care API-ul însuși nu ar prinde-o.
custom_category_thresholds
Acesta este nucleul configurației. Fiecare categorie primește un prag între 0 și 1, comparat cu scorul atribuit de clasificator promptului. Cu cât pragul este mai mic, cu atât filtrul blochează mai mult, cu riscul de a respinge cereri legitime. Un prag de 1 dezactivează explicit categoria. Mistral nu publică o grilă de valori recomandate: trebuie să le calibrați pe propriile exemple (lecția 7).
Valorile au sens doar în contextul aplicației dumneavoastră. Un chatbot accesibil publicului blochează categoriile sensibile la cele mai stricte setări, în timp ce un instrument intern pentru profesioniștii din sănătate trebuie să permită întrebările medicale, rămânând totodată strict privind datele personale.
# Chatbot public: praguri foarte scăzute
public_thresholds = {
"sexual": 0.1,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.1,
"criminal": 0.1,
"selfharm": 0.1,
}
# Instrument medical intern: health dezactivat, PII monitorizat în continuare
medical_thresholds = {
"sexual": 0.2,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.3,
"health": 1, # dezactivează categoria: întrebările medicale sunt funcția principală a instrumentului
"pii": 0.1,
}
Categorii pe care nu le listați
Ce se întâmplă cu categoriile absente din custom_category_thresholds? Documentația nu o precizează explicit, dar exemplul său de blocare este elocvent: categoriile nemenționate apar acolo cu un prag de 1.0, notate dar ineficiente. Nu vă bazați pe un prag implicit: listați fiecare categorie care ar trebui să poată bloca.
Opțiunea ignore_other_categories controlează doar ceea ce este evaluat și returnat. Când este setată la False, toate categoriile evaluate apar în rezultat; când este True, doar cele pe care le-ați listat sunt evaluate.
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, # evaluează doar aceste două categorii
"action": "block",
},
}
]
Avertisment: cu această configurație, o tentativă de jailbreak sau o cerere de date personale ar trece necontrolată. Restricționați lista doar pentru un motiv specific.
Exemplu complet: chatbot cu bariere de protecție
Iată o funcție minimală: trimite mesajul cu configurația completă și transformă un blocaj într-un răspuns lizibil pentru utilizator.
from mistralai.client import errors
def chat_securise(message_utilisateur: str) -> str:
"""Trimite un mesaj protejat de bariere de protecție."""
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 "Ne pare rău, această cerere nu poate fi procesată."
raise
contenu = response.choices[0].message.content
return contenu if isinstance(contenu, str) else ""
print(chat_securise("Explain machine learning to me"))
Două observații. message.content poate fi un șir de caractere sau o listă de părți, în funcție de model, de aici și verificarea isinstance. De asemenea, răspunsul de la chat.complete() nu expune scorurile barierelor de protecție în SDK 3.7.0: pentru a le înregistra în jurnal, utilizați API-ul Conversations, al cărui răspuns le conține în guardrails.
Gestionarea corectă a erorilor de blocare
Trebuie să distingeți două tipuri de eșecuri care necesită nici același mesaj, nici aceeași alertă: un blocaj conform politicii de conținut, care returnează statutul HTTP 403, și un eșec al evaluării de moderare cu block_on_error activat, pe care corpul răspunsului îl semnalează cu codul 3201. Ambele ajung sub formă de errors.SDKError, al cărui body conține JSON-ul returnat de API:
import json
from typing import Any
from mistralai.client import errors
def chat_avec_gestion_erreurs(message_utilisateur: str) -> dict[str, Any]:
"""Chat care distinge blocajele politicii de eșecurile de moderare."""
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": "Serviciul de moderare este indisponibil. Cerere blocată ca măsură de precauție.",
}
if e.status_code == 403:
decisions = corps["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
return {
"status": "blocked",
"content": "Mesajul dumneavoastră a fost blocat de politica noastră de securitate.",
"categories": [nom for nom, d in decisions.items() if d["violated"]],
}
raise
return {"status": "ok", "content": response.choices[0].message.content}
Verificați mai întâi codul 3201, deoarece documentația nu specifică statutul HTTP pentru această eroare. Categoriile încălcate provin din decisions, unde fiecare intrare oferă threshold, score și violated: acesta este ceea ce veți înregistra în jurnal pentru a explica un blocaj.
Cele mai bune practici de configurare
Începeți restrictiv, apoi relaxați treptat. Pragurile scăzute la lansare vă ajută să descoperiți falsurile pozitive în timp ce volumul este încă gestionabil, iar fiecare creștere se decide pe baza cazurilor observate, nu a intuiției:
# Faza 1: lansare (foarte restrictiv)
phase1 = {"hate_and_discrimination": 0.1, "violence_and_threats": 0.1, "criminal": 0.1}
# Faza 2: după analizarea falsurilor pozitive
phase2 = {"hate_and_discrimination": 0.15, "violence_and_threats": 0.25, "criminal": 0.1}
# Faza 3: producție stabilă
phase3 = {"hate_and_discrimination": 0.2, "violence_and_threats": 0.3, "criminal": 0.15}
Aceste valori ilustrează abordarea; ale dumneavoastră vor rezulta din propriile măsurători. Mențineți block_on_error setat la True în producție: valoarea sa implicită în SDK este False, iar un eșec al moderării ar permite atunci trecerea conținutului neverificat. În final, documentația avertizează că modelul de moderare evoluează: politicile bazate pe scoruri pot necesita recalibrare.
Puncte cheie
guardrailseste o listă de obiecte{"block_on_error": ..., "moderation_llm_v2": {...}}- În interiorul
moderation_llm_v2:custom_category_thresholds,ignore_other_categories,actionși opționalmodel_name - Praguri de la
0la1; mai mic înseamnă mai strict;1dezactivează o categorie. Listați fiecare categorie care ar trebui să blocheze - Un blocaj ridică
errors.SDKErrorcustatus_code == 403; un eșec cublock_on_errorpoartă codul3201în corp - Mențineți
block_on_error=Trueîn producție, deoarece valoarea implicită esteFalse