Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Custom Guardrails: Blockiraj prije modela

Lekcija 2 od 12 Ažurirano 3. studenoga 2026. Programer
Na ovoj stranici
  1. Načelo prilagođenih guardrailsa
  2. Kako to funkcionira
  3. Format parametra guardrails
  4. Jedanaest kategorija
  5. Tri razine primjene
  6. Što guardrailsi vraćaju
  7. Odabir prave razine
  8. Ključne točke

Lekcija je ponovno napisana 3. studenoga 2026. Prethodna verzija opisivala je fiktivni parametar guardrails (rječnik s enabled), nepostojeće kategorije (hate, violence), nedostajuću metodu conversation.send() u SDK-u i imaginarne JSON odgovore. Službeni format je lista konfiguracija moderation_llm_v2, a odgovori u nastavku usklađeni su s dokumentacijom. Kod je verificiran prema tipovima mistralai SDK verzije 3.7.0. Izvori: Moderation & Guardrailing · mistralai Python SDK.

Načelo prilagođenih guardrailsa

Mistralovi prilagođeni guardrailsi djeluju kao ulazni filtar: analiziraju upit korisnika prije nego što stigne do modela za generiranje. Ako sadržaj prijeđe bilo koji prag koji si postavio, zahtjev se blokira HTTP pogreškom 403. Model nikada ne vidi problematičan upit.

Od samog početka imaj na umu dva ograničenja. Prvo, guardrailsi moderiraju samo ulaz; ne provjeravaju što model generira. To je uloga Moderation API-ja (Lekcija 5). Drugo, oni zamjenjuju posao koji bi inače morao sam kodirati: pozivanje Moderation API-ja, usporedbu rezultata s tvojim pragovima i odbijanje zahtjeva.

Kako to funkcionira

Kada dodaš guardrailse u zahtjev, tijek na strani Mistrala je sljedeći:

  1. Tvoja aplikacija šalje zahtjev s parametrom guardrails.
  2. Klasifikator mistral-moderation-2603 boduje upit u svakoj kategoriji.
  3. Ako rezultat prijeđe prag, API vraća pogrešku 403 i model se ne poziva.
  4. Inače, model obrađuje zahtjev normalno.
  5. Odgovor uključuje polje guardrails koje sadrži procijenjene rezultate.
Flow: prompt → [mistral-moderation-2603] → score > threshold? → 403 (blocked)
                                           → else             → [LLM] → response + scores

Odluka se temelji na rezultatu uspoređenom s pragom koji postavljaš ti, kategorija po kategorija, između 0 i 1. Nizak prag blokira više sadržaja; prag od 1 izričito onemogućuje kategoriju.

Format parametra guardrails

Parametar je lista. Svaki element je objekt koji sadrži konfiguraciju moderation_llm_v2 i, uz nju, opciju block_on_error:

guardrails = [
    {
        "block_on_error": True,          # blockiraj ako sama moderacija ne uspije
        "moderation_llm_v2": {
            "custom_category_thresholds": {
                "jailbreaking": 0.3,
                "criminal": 0.2,
            },
            "ignore_other_categories": False,
            "action": "block",
        },
    }
]
KljučLokacijaUloga
custom_category_thresholdsunutar moderation_llm_v2Prag od 0 do 1 po kategoriji; 1 onemogućuje kategoriju
ignore_other_categoriesunutar moderation_llm_v2True: procjenjuju se samo navedene kategorije
actionunutar moderation_llm_v2"block" za odbijanje zahtjeva ako je prag premašen
model_nameunutar moderation_llm_v2, opcionalnoModel za moderaciju drugačiji od zadanog mistral-moderation-2603
block_on_erroruz moderation_llm_v2True: zahtjev se blokira ako procjena ne uspije

U listu možeš staviti više objekata: zahtjev se blokira čim bilo koji od njih okine. Svaki objekt sadrži samo jednu konfiguraciju moderation_llm_v2. Starija konfiguracija, moderation_llm_v1, još uvijek postoji u SDK-u s kategorijama iz zastarjelog modela mistral-moderation-2411 (zastario 31. ožujka 2026.): nemoj je koristiti za nove projekte.

Jedanaest kategorija

Ključevi u custom_category_thresholds su fiksni; drugi ključ, poput violence ili hate, ne odgovara ničemu:

KljučŠto detektira
sexualEksplicitan seksualni sadržaj
hate_and_discriminationMržnja ili diskriminacija na temelju zaštićenih obilježja
violence_and_threatsOpisano, veličano ili prijećeno fizičko nasilje
dangerousIzuzetno opasna ponašanja
criminalIlegalne aktivnosti
selfharmSamoozljeđivanje, samoubojstvo, poremećaji prehrane
healthZahtjevi za detaljne ili personalizirane medicinske savjete
financialZahtjevi za detaljne ili personalizirane financijske savjete
lawZahtjevi za detaljne ili personalizirane pravne savjete
piiZatraženi ili podijeljeni osobni podaci
jailbreakingPokušaji zaobilaženja pravila modela

Lekcija 6 ponovno obrađuje svaku od njih i raspravlja o odabiru pragova.

Tri razine primjene

Isti se parametar prihvaća na tri mjesta. Tvoj izbor određuje gdje živi tvoja sigurnosna politika i tko bi je mogao zaboraviti primijeniti.

Razina 1: Zahtjev za Chat Completions

Proslijeđuješ guardrails u pozivu chat.complete(). Svaki zahtjev nosi svoja pravila: praktično za istraživanje, ali rizično u velikom obujmu, jer jedan poziv bez parametra prolazi neprovjeren.

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)

Slučaj upotrebe: Prototipiranje, jednokratni pozivi, ugađanje pragova.

Razina 2: Razgovor (Conversation)

Kod Conversations API-ja, proslijeđuješ guardrails pri pokretanju, u 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)

Naknadne poruke šalju se s client.beta.conversations.append(conversation_id=conversation.conversation_id, inputs=...). Ova metoda ne prihvaća parametar guardrails u SDK-u 3.7.0, a dokumentacija ne specificira primjenjuju li se guardrailsi s početka na naknadne okrete. Za zajamčenu zaštitu u svakom okretu, pričvrsti guardrailse na agenta.

Slučaj upotrebe: Jednokratni razgovor bez agenta ili nadjačavanje guardrailsa agenta za specifičan zahtjev.

Razina 3: Agent

Guardrailsi proslijeđeni u client.beta.agents.create() postaju dio definicije agenta. Prema dokumentaciji, svi razgovori koji koriste ovog agenta nasljeđuju ih bez potrebe za ponavljanjem. Međutim, zahtjev za razgovor može ih nadjačati proslijeđivanjem vlastitih 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!")

Slučaj upotrebe: Produkcija, kada više timova ili servisa poziva istog asistenta.

Što guardrailsi vraćaju

Kada zahtjev prođe, odgovor API-ja uključuje, uz standardna polja, polje guardrails: listu s jednim rezultatom po guardrailsu. Evo tog polja iz primjera u 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 }
        }
      }
    }
  ]
}

Ako je ignore_other_categories postavljen na True, u ovom se rezultatu pojavljuju samo kategorije navedene u tvojim pragovima. U Python SDK-u, odgovor razgovora izlaže ovo polje (conversation.guardrails). Odgovor chat.complete(), međutim, nema namjensko polje za to u SDK-u 3.7.0: ondje se gubi. Ako želiš bilježiti rezultate – a korisno je kasnije znati jesu li tvoji pragovi preširoki ili preuski – koristi razgovore ili čitaj sirovi HTTP odgovor.

Kada je prag premašen, API vraća pogrešku 403 čije tijelo detaljno opisuje odluku, kategorija po 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"
      }
    }
  }
}

SDK tada podiže errors.SDKError, gdje je status_code 403, a body sadrži ovaj 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}")

Ovaj teret omogućuje ti da objasniš blokadu tijekom žalbe: koja kategorija, koji rezultat, koji prag.

Konačno, tu je i degradirani slučaj. Ako sama procjena ne uspije, a block_on_error je True, zahtjev se odbija s kodom pogreške 3201 i porukom Request blocked due to error in guardrail evaluation and block_on_error is set to True. Ovo je način fail-safe: u slučaju nedoumice, blokiraj. Ako je block_on_error postavljen na False (njegova zadana vrijednost u SDK-u), zahtjev bi prošao neprovjeren.

Odabir prave razine

KriterijChat CompletionsRazgovor (Conversation)Agent
Gdje se deklariraju guardrailsiU svakom pozivuPri pokretanju (start)Pri stvaranju agenta
NasljeđivanjeNemaNedokumentirano za naknadne okreteSvi razgovori agenta
Mogućnost nadjačavanja——Da, zahtjevom za razgovor
Slučaj upotrebeTestovi, ugađanje pragovaJednokratni razgovorProdukcija

U praksi, ugodi svoje pragove na zahtjevima za Chat Completions koristeći stvarne slučajeve, a zatim premjesti politiku na agenta čim kod napusti tvoje računalo: više neće biti zaboravljenih poziva.

Ključne točke

  • Guardrailsi blokiraju upite prije modela putem pogreške 403; ne provjeravaju izlaz
  • Parametar je lista objekata {"block_on_error": ..., "moderation_llm_v2": {...}}, a ne rječnik s enabled
  • Jedanaest kategorija s fiksnim imenima (hate_and_discrimination, violence_and_threats, …), svaka s pragom od 0 do 1; 1 onemogućuje
  • Tri razine: chat.complete(), conversations.start(), agents.create(); agenti prosljeđuju svoje guardrailse svim svojim razgovorima
  • block_on_error=True osigurava ponašanje fail-safe (pogreška 3201)