Custom Guardrails: Blocca prima del modello
In questa pagina
Lezione riscritta il 3 novembre 2026. La versione precedente descriveva un parametro
guardrailsfittizio (un dizionario conenabled), categorie inesistenti (hate,violence), un metodoconversation.send()mancante nell’SDK e risposte JSON immaginarie. Il formato ufficiale è una lista di configurazionimoderation_llm_v2e le risposte qui sotto corrispondono alla documentazione. Il codice è stato verificato rispetto ai tipi dell’SDKmistralaiversione 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:
- La tua applicazione invia la richiesta con il parametro
guardrails. - Il classificatore
mistral-moderation-2603assegna un punteggio al prompt in ogni categoria. - Se un punteggio supera la sua soglia, l’API restituisce un errore
403e il modello non viene chiamato. - Altrimenti, il modello elabora la richiesta normalmente.
- La risposta include un campo
guardrailscontenente 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",
},
}
]
| Chiave | Posizione | Ruolo |
|---|---|---|
custom_category_thresholds | dentro moderation_llm_v2 | Soglia da 0 a 1 per categoria; 1 disabilita la categoria |
ignore_other_categories | dentro moderation_llm_v2 | True: vengono valutate solo le categorie elencate |
action | dentro moderation_llm_v2 | "block" per rifiutare la richiesta se una soglia viene superata |
model_name | dentro moderation_llm_v2, opzionale | Modello di moderazione diverso dal default mistral-moderation-2603 |
block_on_error | accanto a moderation_llm_v2 | True: 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:
| Chiave | Cosa rileva |
|---|---|
sexual | Contenuti sessuali espliciti |
hate_and_discrimination | Odio o discriminazione basata su caratteristiche protette |
violence_and_threats | Violenza fisica descritta, glorificata o minacciata |
dangerous | Comportamenti estremamente pericolosi |
criminal | Attività illegali |
selfharm | Autolesionismo, suicidio, disturbi alimentari |
health | Richieste di consigli medici dettagliati o personalizzati |
financial | Richieste di consigli finanziari dettagliati o personalizzati |
law | Richieste di consigli legali dettagliati o personalizzati |
pii | Dati personali richiesti o condivisi |
jailbreaking | Tentativi 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
| Criterio | Chat Completions | Conversazione | Agente |
|---|---|---|---|
| Dove sono dichiarati i guardrails | In ogni chiamata | All’avvio (start) | Alla creazione dell’agente |
| Ereditarietà | Nessuna | Non documentata per i turni successivi | Tutte le conversazioni dell’agente |
| Sovrascrivibile | — | — | Sì, da una richiesta di conversazione |
| Caso d’uso | Test, messa a punto delle soglie | Conversazione una tantum | Produzione |
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 conenabled - Undici categorie con nomi fissi (
hate_and_discrimination,violence_and_threats, …), ognuna con una soglia da 0 a 1;1disabilita - Tre livelli:
chat.complete(),conversations.start(),agents.create(); gli agenti passano i loro guardrails a tutte le loro conversazioni block_on_error=Truegarantisce un comportamento fail-safe (errore3201)