Spring til hovedindhold
Dansk— Vælg et sprog
Menu

Custom Guardrails: Bloker før modellen

Lektion 2 af 12 Opdateret 3. november 2026 Udvikler
På denne side
  1. Princippet bag Custom Guardrails
  2. Sådan fungerer det
  3. Formatet for parameteren guardrails
  4. De elleve kategorier
  5. De tre anvendelsesniveauer
  6. Hvad guardrails returnerer
  7. Valg af det rigtige niveau
  8. Vigtige pointer

Lektion omskrevet den 3. november 2026. Den tidligere version beskrev en fiktiv guardrails-parameter (en ordbog med enabled), ikke-eksisterende kategorier (hate, violence), en manglende conversation.send()-metode i SDK’en og imaginære JSON-svar. Det officielle format er en liste med moderation_llm_v2-konfigurationer, og svarerne nedenfor matcher dokumentationen. Koden er verificeret mod mistralai SDK-types version 3.7.0. Kilder: Moderation & Guardrailing · mistralai Python SDK.

Princippet bag Custom Guardrails

Mistrals Custom Guardrails fungerer som et input-filter: de analyserer brugerens prompt, før den når generationsmodellen. Hvis indholdet overskrider en tærskel, du har defineret, bliver anmodningen blokeret med en HTTP 403-fejl. Modellen ser aldrig den problematiske prompt.

Husk på to begrænsninger fra starten. For det første modererer guardrails kun input; de tjekker ikke, hvad modellen genererer. Det er Moderation API’ens rolle (Lektion 5). For det andet erstatter de arbejde, du ellers skulle kode selv: at kalde Moderation API’en, sammenligne scorer med dine tærskler og afvise anmodningen.

Sådan fungerer det

Når du tilføjer guardrails til en anmodning, er flowet på Mistrals side som følger:

  1. Din applikation sender anmodningen med parameteren guardrails.
  2. Klassificeren mistral-moderation-2603 scorer prompten i hver kategori.
  3. Hvis en score overskrider sin tærskel, returnerer API’en en 403-fejl, og modellen kaldes ikke.
  4. Ellers behandler modellen anmodningen normalt.
  5. Svaret indeholder et felt guardrails med de evaluerede scorer.
Flow: prompt → [mistral-moderation-2603] → score > tærskel? → 403 (blokeret)
                                           → ellers         → [LLM] → svar + scorer

Beslutningen baseres på en score sammenlignet med en tærskel, som du sætter kategori for kategori mellem 0 og 1. En lav tærskel blokerer mere indhold; en tærskel på 1 deaktiverer eksplicit kategorien.

Formatet for parameteren guardrails

Parameteren er en liste. Hvert element er et objekt, der indeholder en moderation_llm_v2-konfiguration og ved siden af den indstillingen block_on_error:

guardrails = [
    {
        "block_on_error": True,          # bloker hvis selve moderationen fejler
        "moderation_llm_v2": {
            "custom_category_thresholds": {
                "jailbreaking": 0.3,
                "criminal": 0.2,
            },
            "ignore_other_categories": False,
            "action": "block",
        },
    }
]
NøglePlaceringRolle
custom_category_thresholdsinde i moderation_llm_v2Tærskel fra 0 til 1 per kategori; 1 deaktiverer kategorien
ignore_other_categoriesinde i moderation_llm_v2True: kun listede kategorier evalueres
actioninde i moderation_llm_v2"block" for at afvise anmodningen, hvis en tærskel overskrides
model_nameinde i moderation_llm_v2, valgfriModerationsmodel anden end standarden mistral-moderation-2603
block_on_errorved siden af moderation_llm_v2True: anmodningen blokeres, hvis evalueringen fejler

Du kan placere flere objekter i listen: anmodningen blokeres, så snart én af dem udløses. Hvert objekt indeholder kun én moderation_llm_v2-konfiguration. En ældre konfiguration, moderation_llm_v1, findes stadig i SDK’en med kategorier fra den forældede model mistral-moderation-2411 (forældet 31. marts 2026): brug den ikke til nye projekter.

De elleve kategorier

Nøglerne i custom_category_thresholds er fastlåste; en anden nøgle, såsom violence eller hate, svarer til ingenting:

NøgleHvad den registrerer
sexualEksplicit seksuelt indhold
hate_and_discriminationHad eller diskrimination baseret på beskyttede egenskaber
violence_and_threatsBeskrevet, herliggjort eller truet fysisk vold
dangerousEkstremt farlige adfærdsmønstre
criminalUlovlige aktiviteter
selfharmSelvskade, selvmord, spiseforstyrrelser
healthAnmodninger om detaljeret eller personlig lægelig rådgivning
financialAnmodninger om detaljeret eller personlig finansiel rådgivning
lawAnmodninger om detaljeret eller personlig juridisk rådgivning
piiPersonlige data, der anmodes om eller deles
jailbreakingForsøg på at omgå modellens regler

Lektion 6 gennemgår hver af disse og diskuterer valget af tærskler.

De tre anvendelsesniveauer

Den samme parameter accepteres tre steder. Dit valg bestemmer, hvor din sikkerhedspolitik lever, og hvem der måske glemmer at anvende den.

Niveau 1: En Chat Completions-anmodning

Du sender guardrails i kaldet chat.complete(). Hver anmodning bærer sine egne regler: praktisk til udforskning, men risikabelt i stor skala, da et enkelt kald uden parameteren slipper igennem ukontrolleret.

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)

Anvendelsestilfælde: Prototyping, engangskald, finjustering af tærskler.

Niveau 2: En samtale

Med Conversations API’en sender du guardrails ved opstart i 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)

Efterfølgende beskeder sendes med client.beta.conversations.append(conversation_id=conversation.conversation_id, inputs=...). Denne metode accepterer ikke en guardrails-parameter i SDK 3.7.0, og dokumentationen specificerer ikke, om guardrails fra opstart gælder for efterfølgende ture. For garanteret beskyttelse ved hver tur skal du knytte guardrails til en agent.

Anvendelsestilfælde: Engangssamtale uden en agent, eller overskrivelse af en agents guardrails til en specifik anmodning.

Niveau 3: En agent

Guardrails sendt til client.beta.agents.create() bliver en del af agentens definition. Ifølge dokumentationen arver alle samtaler, der bruger denne agent, dem uden behov for at gentage dem. En samtaleanmodning kan dog overskrive dem ved at sende sine egne 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!")

Anvendelsestilfælde: Produktion, når flere hold eller tjenester kalder den samme assistent.

Hvad guardrails returnerer

Når anmodningen består, inkluderer API-svaret – ud over standardfelter – et felt guardrails: en liste med ét resultat per guardrail. Her er dette felt fra dokumentationseksemplet:

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

Med ignore_other_categories sat til True vises kun de kategorier, der er listet i dine tærskler, i dette resultat. I Python SDK’en eksponerer et samtale-svar dette felt (conversation.guardrails). Svaret fra chat.complete() har derimod intet dedikeret felt til det i SDK 3.7.0: det går tabt her. Hvis du vil logge scorer – og det er nyttigt senere at vide, om dine tærskler er for løse eller for stramme – så brug samtaler eller læs det rå HTTP-svar.

Når en tærskel overskrides, returnerer API’en en 403-fejl, hvis body detaljerer beslutningen kategori for kategori:

{
  "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’en rejser derefter errors.SDKError, hvor status_code er 403, og body indeholder denne 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}")

Denne payload giver dig mulighed for at forklare en blokering under en appel: hvilken kategori, hvilken score, hvilken tærskel.

Endelig er der det degraderede tilfælde. Hvis selve evalueringen fejler, og block_on_error er True, afvises anmodningen med fejlkode 3201 og beskeden Request blocked due to error in guardrail evaluation and block_on_error is set to True. Dette er fail-safe-tilstand: ved tvivl, bloker. Med block_on_error sat til False (dens standardværdi i SDK’en), ville anmodningen passere ukontrolleret.

Valg af det rigtige niveau

KriteriumChat CompletionsSamtaleAgent
Hvor guardrails erklæresI hvert kaldVed opstart (start)Ved oprettelse af agent
ArvIngenUdokumenteret for efterfølgende tureAlle agent-samtaler
Kan overskrives——Ja, via en samtaleanmodning
AnvendelsestilfældeTest, finjustering af tærsklerEngangssamtaleProduktion

I praksis finjusterer du dine tærskler på Chat Completions-anmodninger ved hjælp af rigtige tilfælde og flytter derefter politikken til en agent, så snart koden forlader din maskine: så vil der ikke være flere glemte kald.

Vigtige pointer

  • Guardrails blokerer prompts før modellen via en 403-fejl; de tjekker ikke output
  • Parameteren er en liste med objekter {"block_on_error": ..., "moderation_llm_v2": {...}}, ikke en ordbog med enabled
  • Elleve kategorier med faste navne (hate_and_discrimination, violence_and_threats, …), hver med en tærskel fra 0 til 1; 1 deaktiverer
  • Tre niveauer: chat.complete(), conversations.start(), agents.create(); agenter giver deres guardrails videre til alle deres samtaler
  • block_on_error=True sikrer fail-safe-adfærd (fejl 3201)