Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Custom Guardrails: Block Before the Model

Lekcija 2 od 12 Posodobljeno 3. november 2026 Razvijalec
Na tej strani
  1. Načelo prilagojenih varoval (Custom Guardrails)
  2. Kako deluje
  3. Format parametra guardrails
  4. Enajst kategorij
  5. Tri ravni uporabe
  6. Kaj vrnejo varovale
  7. Izbira prave ravni
  8. Ključne ugotovitve

Lekcija je bila ponovno napisana 3. novembra 2026. Prejšnja različica je opisovala fiktivni parameter guardrails (slovar z enabled), neobstoječe kategorije (hate, violence), manjkajočo metodo conversation.send() v SDK-ju in namišljene odgovore JSON. Uradni format je seznam konfiguracij moderation_llm_v2, spodnji odgovori pa ustrezajo dokumentaciji. Koda je bila preverjena glede na tipe SDK-ja mistralai različice 3.7.0. Viri: Moderation & Guardrailing · mistralai Python SDK.

Načelo prilagojenih varoval (Custom Guardrails)

Prilagojene varovale Mistral delujejo kot filter vhodnih podatkov: analizirajo uporabnikov poziv preden ta doseže model za generiranje. Če vsebina preseže kateri koli prag, ki ste ga nastavili, je zahteva blokirana s napako HTTP 403. Model problematičnega poziva nikoli ne vidi.

Od samega začetka imej v mislih dve omejitvi. Prvič, varovale moderirajo samo vhod; ne preverjajo tega, kar model ustvari. To je naloga API-ja za moderiranje (5. lekcija). Drugič, nadomeščajo delo, ki bi ga sicer moral kodirati sam: klicanje API-ja za moderiranje, primerjanje rezultatov s tvojimi pragovi in zavrnitev zahteve.

Kako deluje

Ko zahtevi dodaš varovale, je potek na strani Mistrala naslednji:

  1. Tvoja aplikacija pošlje zahtevo s parametrom guardrails.
  2. Klasifikator mistral-moderation-2603 ovrednoti poziv v vsaki kategoriji.
  3. Če rezultat preseže prag, API vrne napako 403 in model ni poklican.
  4. V nasprotnem primeru model obdela zahtevo običajno.
  5. Odgovor vključuje polje guardrails, ki vsebuje ovrednotene rezultate.
Flow: prompt → [mistral-moderation-2603] → score > threshold? → 403 (blocked)
                                           → else             → [LLM] → response + scores

Odločitev temelji na rezultatu, primerjanem s pragom, ki ga nastaviš ti, kategorija za kategorijo, med 0 in 1. Nizek prag blokira več vsebine; prag 1 kategorijo izrecno onemogoči.

Format parametra guardrails

Parameter je seznam. Vsak element je objekt, ki vsebuje konfiguracijo moderation_llm_v2 in ob njej možnost block_on_error:

guardrails = [
    {
        "block_on_error": True,          # block if moderation itself fails
        "moderation_llm_v2": {
            "custom_category_thresholds": {
                "jailbreaking": 0.3,
                "criminal": 0.2,
            },
            "ignore_other_categories": False,
            "action": "block",
        },
    }
]
KljučLokacijaVloga
custom_category_thresholdsznotraj moderation_llm_v2Prag od 0 do 1 na kategorijo; 1 onemogoči kategorijo
ignore_other_categoriesznotraj moderation_llm_v2True: ovrednotene so samo navedene kategorije
actionznotraj moderation_llm_v2"block" za zavrnitev zahteve, če je prag presežen
model_nameznotraj moderation_llm_v2, opcijskoModel za moderiranje, drugačen od privzetega mistral-moderation-2603
block_on_errorob moderation_llm_v2True: zahteva je blokirana, če ovrednotenje ne uspe

Na seznam lahko dodaš več objektov: zahteva je blokirana, takoj ko se sproži kateri koli od njih. Vsak objekt vsebuje samo eno konfiguracijo moderation_llm_v2. Starejša konfiguracija, moderation_llm_v1, še vedno obstaja v SDK-ju s kategorijami iz zastarelega modela mistral-moderation-2411 (zastarel 31. marca 2026): ne uporabljaj je za nove projekte.

Enajst kategorij

Ključi v custom_category_thresholds so fiksni; drug ključ, kot sta violence ali hate, ne ustreza ničemer:

KljučKaj zazna
sexualEksplicitna spolna vsebina
hate_and_discriminationSovraštvo ali diskriminacija na podlagi zaščitenih značilnosti
violence_and_threatsOpisano, poveličevano ali ogrožajoče fizično nasilje
dangerousIzjemno nevarna vedenja
criminalNezakonite dejavnosti
selfharmSamopoškodovanje, samomor, motnje hranjenja
healthZahteve za podrobne ali personalizirane zdravstvene nasvete
financialZahteve za podrobne ali personalizirane finančne nasvete
lawZahteve za podrobne ali personalizirane pravne nasvete
piiZahtevani ali deljeni osebni podatki
jailbreakingPoskusi obida pravil modela
  1. lekcija ponovno obravnava vsako od teh in razpravlja o izbiri pragov.

Tri ravni uporabe

Isti parameter je sprejet na treh mestih. Tvoja izbira določa, kje živi tvoja varnostna politika in kdo bi jo lahko pozabil uporabiti.

1. raven: Zahteva za dopolnjevanje klepeta (Chat Completions)

Parameter guardrails posreduješ v klicu chat.complete(). Vsaka zahteva nosi svoja pravila: praktično za raziskovanje, a tvegano v velikem obsegu, saj en sam klic brez parametra neopažen uide nadzoru.

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)

Primer uporabe: Prototipiranje, enkratni klici, uglaševanje pragov.

2. raven: Pogovor (Conversation)

Z API-jem za pogovore posreduješ guardrails ob zagonu, v 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)

Naslednja sporočila se pošljejo z client.beta.conversations.append(conversation_id=conversation.conversation_id, inputs=...). Ta metoda v SDK-ju 3.7.0 ne sprejme parametra guardrails, dokumentacija pa ne določa, ali se zagonske varovale uporabljajo za naslednje poteze. Za zagotovljeno zaščito pri vsaki potezi pripni varovale agentu.

Primer uporabe: Enkraten pogovor brez agenta ali preglasitev varoval agenta za določeno zahtevo.

3. raven: Agent

Varovale, posredovane v client.beta.agents.create(), postanejo del definicije agenta. Po dokumentaciji vsi pogovori, ki uporabljajo tega agenta, podedujejo te varovale, ne da bi jih bilo treba ponavljati. Vendar pa lahko zahteva za pogovor te varovale preglasi tako, da posreduje svoje lastne guardrails.

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!")

Primer uporabe: Produkcijsko okolje, ko več ekip ali storitev kliče istega pomočnika.

Kaj vrnejo varovale

Ko zahteva uspe, odgovor API-ja vključuje poleg standardnih polj še polje guardrails: seznam z enim rezultatom na varovalo. Tukaj je to polje iz primera v dokumentaciji:

{
  "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 }
        }
      }
    }
  ]
}

Če je ignore_other_categories nastavljen na True, se v tem rezultatu prikažejo samo kategorije, navedene v tvojih pragovih. V Python SDK-ju odgovor pogovora izpostavi to polje (conversation.guardrails). Odgovor chat.complete() pa v SDK-ju 3.7.0 nima določenega polja za to: tam se izgubi. Če želiš beležiti rezultate – kar je koristno, da kasneje veš, ali so tvoji pragovi preširoki ali preozki – uporabi pogovore ali preberi surov odgovor HTTP.

Ko je prag presežen, API vrne napako 403, katere telo podrobno opisuje odločitev, kategorija za kategorijo:

{
  "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"
      }
    }
  }
}

SDK nato sproži errors.SDKError, kjer je status_code enak 403 in body vsebuje ta 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}")

Ta vsebina ti omogoča, da med pritožbo razložiš blokado: katera kategorija, kakšen rezultat, kakšen prag.

Nazadnje, tu je še poslabšan primer. Če samo ovrednotenje ne uspe in je block_on_error nastavljen na True, je zahteva zavrnjena s kodo napake 3201 in sporočilom Request blocked due to error in guardrail evaluation and block_on_error is set to True. To je način fail-safe: ko si v dvomih, blokiraj. Če je block_on_error nastavljen na False (njegova privzeta vrednost v SDK-ju), bi zahteva šla skozi brez nadzora.

Izbira prave ravni

MeriloChat CompletionsConversationAgent
Kje so varovale deklariraneV vsakem klicuOb zagonu (start)Ob ustvarjanju agenta
DedovanjeNobenoNedokumentirano za naslednje potezeVsi pogovori agenta
Možnost preglasitve——Da, z zahtevo za pogovor
Primer uporabeTesti, uglaševanje pragovEnkraten pogovorProdukcijsko okolje

V praksi uglašaj svoje pragove na zahtevah Chat Completions z uporabo realnih primerov, nato pa politiko premakni na agenta, takoj ko koda zapusti tvoj računalnik: tako ne bo več pozabljenih klicev.

Ključne ugotovitve

  • Varovale blokirajo pozive pred modelom z napako 403; ne preverjajo izhoda
  • Parameter je seznam objektov {"block_on_error": ..., "moderation_llm_v2": {...}}, ne slovar z enabled
  • Enajst kategorij s fiksnimi imeni (hate_and_discrimination, violence_and_threats, …), vsaka s pragom od 0 do 1; 1 onemogoči
  • Tri ravni: chat.complete(), conversations.start(), agents.create(); agenti posredujejo svoje varovale vsem svojim pogovorom
  • block_on_error=True zagotavlja vedenje fail-safe (napaka 3201)