Salt la conținutul principal
Română— Alege o limbă
Meniu

Configurarea barierelor de protecție în Python

Lecția 3 din 12 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. De la teorie la cod
  2. Parametrul guardrails în detaliu
  3. Exemplu complet: chatbot cu bariere de protecție
  4. Gestionarea corectă a erorilor de blocare
  5. Cele mai bune practici de configurare
  6. Puncte cheie

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 testa e.status_code == 3201, deși 3201 este 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 SDK mistralai 3.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

  • guardrails este o listă de obiecte {"block_on_error": ..., "moderation_llm_v2": {...}}
  • În interiorul moderation_llm_v2: custom_category_thresholds, ignore_other_categories, action și opțional model_name
  • Praguri de la 0 la 1; mai mic înseamnă mai strict; 1 dezactivează o categorie. Listați fiecare categorie care ar trebui să blocheze
  • Un blocaj ridică errors.SDKError cu status_code == 403; un eșec cu block_on_error poartă codul 3201 în corp
  • Mențineți block_on_error=True în producție, deoarece valoarea implicită este False