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

Custom Guardrails: Imblokka Qabel il-Mudell

Lezzjoni 2 / 12 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Il-Prinċipju tal-Custom Guardrails
  2. Kif Jaħdem
  3. Il-Format tal-Parametru guardrails
  4. Il-Ħdax-il Kategorija
  5. It-Tliet Livelli ta’ Applikazzjoni
  6. X’Jirritornaw il-Guardrails
  7. L-Għażla tal-Livell It-Tajjeb
  8. Punti Ewlenin

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), metodu conversation.send() nieqes fl-SDK, u tweġibiet JSON immaġinarji. Il-format uffiċjali huwa lista ta’ konfigurazzjonijiet moderation_llm_v2, u t-tweġibiet hawn taħt jaqblu mad-dokumentazzjoni. Il-kodiċi ġie vverifikat kontra t-tipi tal-SDK mistralai verż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:

  1. L-applikazzjoni tiegħek tibgħat it-talba bil-parametru guardrails.
  2. Il-klassifikatur mistral-moderation-2603 jagħti punteġġ lill-prompt f’kull kategorija.
  3. Jekk punteġġ jaqbeż il-limitu tiegħu, l-API tirritorna żball 403 u l-mudell ma jissejjaħx.
  4. Inkella, il-mudell jipproċessa t-talba normalment.
  5. It-tweġiba tinkludi kamp guardrails li 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",
        },
    }
]
ĊavettaPostRwol
custom_category_thresholdsġewwa moderation_llm_v2Limitu minn 0 sa 1 għal kull kategorija; 1 jiddiżattiva l-kategorija
ignore_other_categoriesġewwa moderation_llm_v2True: 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, opzjonaliMudell ta’ moderazzjoni differenti mill-predefinit mistral-moderation-2603
block_on_errormaġenb moderation_llm_v2True: 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:

ĊavettaX’tiskopri
sexualKontenut sesswali espliċitu
hate_and_discriminationMibegħda jew diskriminazzjoni bbażata fuq karatteristiċi protetti
violence_and_threatsVjolenza fiżika deskritta, igglorifikata jew imhedda
dangerousImġiba estremament perikoluża
criminalAttivitajiet illegali
selfharmAwto-ħsara, suwiċidju, disturbi fl-ikel
healthTalbiet għal pariri mediċi dettaljati jew personalizzati
financialTalbiet għal pariri finanzjarji dettaljati jew personalizzati
lawTalbiet għal pariri legali dettaljati jew personalizzati
piiData personali mitluba jew maqsuma
jailbreakingTentattivi 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

KriterjuChat CompletionsKonversazzjoniAġent
Fejn jiġu ddikjarati l-guardrailsF’kull sejħaFil-bidu (start)Fil-ħolqien tal-aġent
WirtL-ebdaMhux iddokumentat għad-dawriet sussegwentiIl-konversazzjonijiet kollha tal-aġent
Jista’ jinbidel——Iva, minn talba ta’ konversazzjoni
Każ ta’ użuTestijiet, aġġustament tal-limitiKonversazzjoni waħdaProduzzjoni

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; 1 jiddiż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=True jiżgura mġiba fail-safe (żball 3201)