Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Custom Guardrails: Blocca prima del modello

Lezione 2 di 12 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Il principio dei Custom Guardrails
  2. Come funziona
  3. Il formato del parametro guardrails
  4. Le undici categorie
  5. I tre livelli di applicazione
  6. Cosa restituiscono i Guardrails
  7. Scegliere il livello giusto
  8. Punti chiave

Lezione riscritta il 3 novembre 2026. La versione precedente descriveva un parametro guardrails fittizio (un dizionario con enabled), categorie inesistenti (hate, violence), un metodo conversation.send() mancante nell’SDK e risposte JSON immaginarie. Il formato ufficiale è una lista di configurazioni moderation_llm_v2 e le risposte qui sotto corrispondono alla documentazione. Il codice è stato verificato rispetto ai tipi dell’SDK mistralai versione 3.7.0. Fonti: Moderation & Guardrailing · mistralai Python SDK.

Il principio dei Custom Guardrails

I Custom Guardrails di Mistral agiscono come un filtro in ingresso: analizzano il prompt dell’utente prima che raggiunga il modello di generazione. Se il contenuto supera una qualsiasi soglia che hai impostato, la richiesta viene bloccata con un errore HTTP 403. Il modello non vede mai il prompt problematico.

Tieni a mente fin da subito due limitazioni. Innanzitutto, i guardrails moderano solo l’input; non controllano ciò che il modello genera. Questo è il ruolo dell’API di Moderazione (Lezione 5). In secondo luogo, sostituiscono un lavoro che altrimenti dovresti codificare tu stesso: chiamare l’API di Moderazione, confrontare i punteggi con le tue soglie e rifiutare la richiesta.

Come funziona

Quando aggiungi i guardrails a una richiesta, il flusso lato Mistral è il seguente:

  1. La tua applicazione invia la richiesta con il parametro guardrails.
  2. Il classificatore mistral-moderation-2603 assegna un punteggio al prompt in ogni categoria.
  3. Se un punteggio supera la sua soglia, l’API restituisce un errore 403 e il modello non viene chiamato.
  4. Altrimenti, il modello elabora la richiesta normalmente.
  5. La risposta include un campo guardrails contenente i punteggi valutati.
Flow: prompt → [mistral-moderation-2603] → score > threshold? → 403 (blocked)
                                           → else             → [LLM] → response + scores

La decisione si basa su un punteggio confrontato con una soglia impostata da te, categoria per categoria, tra 0 e 1. Una soglia bassa blocca più contenuti; una soglia di 1 disabilita esplicitamente la categoria.

Il formato del parametro guardrails

Il parametro è una lista. Ogni elemento è un oggetto contenente una configurazione moderation_llm_v2 e, accanto ad essa, l’opzione block_on_error:

guardrails = [
    {
        "block_on_error": True,          # blocca se la moderazione stessa fallisce
        "moderation_llm_v2": {
            "custom_category_thresholds": {
                "jailbreaking": 0.3,
                "criminal": 0.2,
            },
            "ignore_other_categories": False,
            "action": "block",
        },
    }
]
ChiavePosizioneRuolo
custom_category_thresholdsdentro moderation_llm_v2Soglia da 0 a 1 per categoria; 1 disabilita la categoria
ignore_other_categoriesdentro moderation_llm_v2True: vengono valutate solo le categorie elencate
actiondentro moderation_llm_v2"block" per rifiutare la richiesta se una soglia viene superata
model_namedentro moderation_llm_v2, opzionaleModello di moderazione diverso dal default mistral-moderation-2603
block_on_erroraccanto a moderation_llm_v2True: la richiesta viene bloccata se la valutazione fallisce

Puoi inserire più oggetti nella lista: la richiesta viene bloccata non appena uno di essi si attiva. Ogni oggetto contiene una sola configurazione moderation_llm_v2. Esiste ancora una configurazione più vecchia, moderation_llm_v1, nell’SDK con categorie del modello deprecato mistral-moderation-2411 (deprecato il 31 marzo 2026): non usarla per nuovi progetti.

Le undici categorie

Le chiavi in custom_category_thresholds sono fisse; un’altra chiave, come violence o hate, non corrisponde a nulla:

ChiaveCosa rileva
sexualContenuti sessuali espliciti
hate_and_discriminationOdio o discriminazione basata su caratteristiche protette
violence_and_threatsViolenza fisica descritta, glorificata o minacciata
dangerousComportamenti estremamente pericolosi
criminalAttività illegali
selfharmAutolesionismo, suicidio, disturbi alimentari
healthRichieste di consigli medici dettagliati o personalizzati
financialRichieste di consigli finanziari dettagliati o personalizzati
lawRichieste di consigli legali dettagliati o personalizzati
piiDati personali richiesti o condivisi
jailbreakingTentativi di aggirare le regole del modello

La Lezione 6 riprende ciascuna di queste e discute la selezione delle soglie.

I tre livelli di applicazione

Lo stesso parametro è accettato in tre luoghi. La tua scelta determina dove risiede la tua politica di sicurezza e chi potrebbe dimenticare di applicarla.

Livello 1: Una richiesta Chat Completions

Passi guardrails nella chiamata chat.complete(). Ogni richiesta porta le proprie regole: pratico per l’esplorazione, ma rischioso su larga scala, poiché una singola chiamata senza il parametro passa incontrollata.

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)

Caso d’uso: Prototipazione, chiamate una tantum, messa a punto delle soglie.

Livello 2: Una Conversazione

Con l’API Conversations, passi guardrails all’avvio, in 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)

I messaggi successivi vengono inviati con client.beta.conversations.append(conversation_id=conversation.conversation_id, inputs=...). Questo metodo non accetta un parametro guardrails nell’SDK 3.7.0 e la documentazione non specifica se i guardrails di avvio si applichino ai turni successivi. Per una protezione garantita su ogni turno, allega i guardrails a un agente.

Caso d’uso: Conversazione una tantum senza agente, o sovrascrittura dei guardrails di un agente per una richiesta specifica.

Livello 3: Un Agente

I guardrails passati a client.beta.agents.create() diventano parte della definizione dell’agente. Secondo la documentazione, tutte le conversazioni che utilizzano questo agente li ereditano senza bisogno di ripeterli. Tuttavia, una richiesta di conversazione può sovrascriverli passando i propri 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!")

Caso d’uso: Produzione, quando più team o servizi chiamano lo stesso assistente.

Cosa restituiscono i Guardrails

Quando la richiesta passa, la risposta dell’API include, accanto ai campi standard, un campo guardrails: una lista con un risultato per guardrail. Ecco quel campo dall’esempio della documentazione:

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

Con ignore_other_categories impostato su True, solo le categorie elencate nelle tue soglie appaiono in questo risultato. Nell’SDK Python, una risposta di conversazione espone questo campo (conversation.guardrails). La risposta di chat.complete(), invece, non ha un campo dedicato per esso nell’SDK 3.7.0: lì va perso. Se vuoi registrare i punteggi — ed è utile sapere in seguito se le tue soglie sono troppo lasche o troppo strette — usa le conversazioni o leggi la risposta HTTP grezza.

Quando una soglia viene superata, l’API restituisce un errore 403 il cui corpo dettaglia la decisione, categoria per categoria:

{
  "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 solleva quindi errors.SDKError, dove status_code è 403 e body contiene questo 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}")

Questo payload ti permette di spiegare un blocco durante un appello: quale categoria, quale punteggio, quale soglia.

Infine, c’è il caso degradato. Se la valutazione stessa fallisce e block_on_error è True, la richiesta viene rifiutata con il codice di errore 3201 e il messaggio Request blocked due to error in guardrail evaluation and block_on_error is set to True. Questa è la modalità fail-safe: in caso di dubbio, blocca. Con block_on_error impostato su False (il suo valore predefinito nell’SDK), la richiesta passerebbe incontrollata.

Scegliere il livello giusto

CriterioChat CompletionsConversazioneAgente
Dove sono dichiarati i guardrailsIn ogni chiamataAll’avvio (start)Alla creazione dell’agente
EreditarietàNessunaNon documentata per i turni successiviTutte le conversazioni dell’agente
Sovrascrivibile——Sì, da una richiesta di conversazione
Caso d’usoTest, messa a punto delle soglieConversazione una tantumProduzione

In pratica, metti a punto le tue soglie sulle richieste Chat Completions usando casi reali, poi sposta la politica su un agente non appena il codice lascia la tua macchina: non ci saranno più chiamate dimenticate.

Punti chiave

  • I Guardrails bloccano i prompt prima del modello tramite un errore 403; non controllano l’output
  • Il parametro è una lista di oggetti {"block_on_error": ..., "moderation_llm_v2": {...}}, non un dizionario con enabled
  • Undici categorie con nomi fissi (hate_and_discrimination, violence_and_threats, …), ognuna con una soglia da 0 a 1; 1 disabilita
  • Tre livelli: chat.complete(), conversations.start(), agents.create(); gli agenti passano i loro guardrails a tutte le loro conversazioni
  • block_on_error=True garantisce un comportamento fail-safe (errore 3201)