Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Ikkonfigura l-guardrails fil-Python

Lezzjoni 3 / 12 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Mit-teorija għall-kodiċi
  2. Il-parametru guardrails fid-dettall
  3. Eżempju sħiħ: chatbot bil-guardrails
  4. Ġesti l-iżbalji ta’ imblukkar b’mod nadif
  5. L-aħjar prattiki tal-konfigurazzjoni
  6. Punti Ewlenin

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 ttestjat e.status_code == 3201, għalkemm 3201 huwa 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-SDK mistralai 3.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

  • guardrails hija lista ta’ oġġetti {"block_on_error": ..., "moderation_llm_v2": {...}}
  • Ġewwa moderation_llm_v2: custom_category_thresholds, ignore_other_categories, action, u fakultattivament model_name
  • Limiti minn 0 sa 1; aktar baxx huwa aktar strett; 1 jiddiżattiva kategorija. Ielenka kull kategorija li għandha timblokka
  • Imblukkar iqajjem errors.SDKError b’status_code == 403; falliment b’block_on_error iġorr il-kodiċi 3201 fil-korp
  • Żomm block_on_error=True fil-produzzjoni, peress li l-valur standard huwa False