API di Moderazione di Mistral
In questa pagina
Aggiornato il 3 novembre 2026. L’esempio di risposta includeva precedentemente chiavi inesistenti (
hate,violence,unpredictable); ora riflette le undici categorie dimistral-moderation-2603. La pipeline finale utilizzava in precedenza un formato di guardrail inventato (enabled) e rilevava i blocchi cercando “403” nel messaggio di errore: ora segue il formato ufficiale e controllae.status_code. La presentazione del modello aderisce alla sua scheda tecnica ufficiale e la lezione introduce Shieldstral 1.0, il modello di moderazione in anteprima pubblica dall’agosto 2026. Codice verificato rispetto ai tipi SDKmistralaiversione 3.7.0. Fonti: Moderation & Guardrailing · Mistral Moderation 2 · Shieldstral 1.0.
Classificare i contenuti dopo la generazione
I guardrail filtrano i prompt in input. Ma che dire dei contenuti generati dal modello? Un prompt innocente può produrre una risposta problematica: la domanda di uno studente delle medie sulla Seconda Guerra Mondiale potrebbe generare una descrizione che non vuoi mostrare senza avvertenze. Questo è il ruolo dell’API di Moderazione: analizzare i contenuti a posteriori e assegnare punteggi di rischio per categoria.
L’API di Moderazione è la tua seconda linea di difesa: completa i guardrail per creare un’architettura di sicurezza completa, con una differenza fondamentale: non blocca nulla di sua iniziativa, ti informa semplicemente.
Il modello Mistral Moderation 2
Il modello dedicato alla moderazione si chiama mistral-moderation-2603 (Mistral Moderation 2, versione di marzo 2026). È un classificatore specializzato, distinto dai modelli di generazione: non scrive testo, assegna punteggi. La sua scheda tecnica ufficiale evidenzia una finestra di contesto di 128.000 token, il rilevamento di jailbreak e prestazioni elevate su contenuti multilingue complessi, incluse conversazioni lunghe. Sostituisce mistral-moderation-2411, deprecato il 31 marzo 2026.
Assegna un punteggio a ciascun testo su 11 categorie, con un valore da 0.0 a 1.0 per categoria. Accetta due modalità di input, testo semplice o conversazionale, e la scelta tra queste influisce sulla qualità dei risultati più di quanto potresti pensare.
Esiste un secondo modello di moderazione dal 4 agosto 2026, in anteprima pubblica: Shieldstral 1.0. Funziona in modo diverso: compatto (3,8 miliardi di parametri) e multimodale, classifica testo e immagini sulla base di domande sulle policy formulate in linguaggio naturale, rispondendo sì o no. I suoi pesi sono pubblicati sotto licenza Apache 2.0, consentendo l’auto-hosting. Finché rimarrà in anteprima, mistral-moderation-2603 resterà il modello di produzione ed è quello utilizzato per i guardrail.
L’endpoint /v1/moderations
La modalità testo semplice è la più elementare: invii uno o più testi da classificare, senza contesto aggiuntivo.
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Moderare testo semplice
response = client.classifiers.moderate(
model="mistral-moderation-2603",
inputs=["Text to analyze for moderation"]
)
# Accedere ai risultati
for result in response.results:
print(f"Categories: {result.categories}")
print(f"Scores: {result.category_scores}")
Per moderare scambi completi, prompt e risposta insieme, la modalità conversazionale fornisce al classificatore ciò che gli mancava: il filo del discorso.
# Moderare una conversazione completa
response = client.classifiers.moderate_chat(
model="mistral-moderation-2603",
inputs=[
[
{"role": "user", "content": "How do I treat a headache?"},
{"role": "assistant", "content": "Take 1g of paracetamol..."}
]
]
)
# Il classificatore valuta il contesto completo
for result in response.results:
print(f"Health score: {(result.category_scores or {}).get('health', 0)}")
La modalità conversazionale, che chiama l’endpoint /v1/chat/moderations, è quella raccomandata da Mistral per uno scambio: il modello è addestrato a classificare l’ultimo turno della conversazione alla luce di quelli precedenti. Per moderare la risposta del tuo assistente, posizionala per ultima. La lista di liste nell’esempio consente di inviare più conversazioni contemporaneamente; per una singola conversazione basta una semplice lista di messaggi. Lo stesso testo può quindi ricevere un punteggio diverso a seconda che risponda a una domanda legittima o malevola: un dosaggio citato in risposta a una richiesta informativa non ha lo stesso status dello stesso dosaggio inserito in uno scambio sull’automedicazione rischiosa.
Struttura della risposta
Per ogni testo analizzato, la risposta contiene due blocchi paralleli: categories, booleani calcolati con soglie impostate da Mistral in base al suo set di test interno, e category_scores, i punteggi grezzi da 0.0 a 1.0. L’esempio seguente è illustrativo, con valori arrotondati; alcuni esempi della documentazione mostrano ancora le nove categorie del vecchio modello, dove dangerous_and_criminal_content combinava dangerous e criminal. Utilizzerai queste ultime perché ti permettono di stabilire i tuoi confini.
{
"id": "mod-abc123",
"model": "mistral-moderation-2603",
"results": [
{
"categories": {
"sexual": false,
"hate_and_discrimination": false,
"violence_and_threats": false,
"dangerous": false,
"criminal": false,
"selfharm": false,
"health": true,
"financial": false,
"law": false,
"pii": false,
"jailbreaking": false
},
"category_scores": {
"sexual": 0.01,
"hate_and_discrimination": 0.02,
"violence_and_threats": 0.03,
"dangerous": 0.02,
"criminal": 0.01,
"selfharm": 0.01,
"health": 0.72,
"financial": 0.05,
"law": 0.08,
"pii": 0.02,
"jailbreaking": 0.01
}
}
]
}
In questo esempio, solo health è marcato come true, con 0.72. Un assistente rivolto ai consumatori lo vedrebbe come un segnale di blocco; uno strumento destinato ai farmacisti lo lascerebbe passare senza esitazione. Lo stesso punteggio, due decisioni opposte, ed è proprio per questo che lavori con i punteggi piuttosto che con i booleani.
Moderare più testi in batch
L’API accetta più testi in una singola richiesta, il che cambia tutto per l’elaborazione in batch: analizzare retroattivamente una cronologia di conversazioni o un database di commenti diventa un’operazione ragionevole in termini di numero di chiamate.
# Moderare più testi in una singola richiesta
texts = [
"First text to analyze",
"Second text to analyze",
"Third text to analyze"
]
response = client.classifiers.moderate(
model="mistral-moderation-2603",
inputs=texts
)
# Ogni testo ha il proprio risultato
for i, result in enumerate(response.results):
scores = result.category_scores or {}
max_cat = max(scores, key=lambda c: scores[c])
max_score = scores[max_cat]
print(f"Text {i+1}: max score = {max_score:.2f} ({max_cat})")
Guardrail vs API di Moderazione: quando usare cosa
| Aspetto | Guardrail Personalizzati | API di Moderazione |
|---|---|---|
| Tempistica | PRIMA della generazione | DOPO la generazione |
| Azione | Blocca automaticamente (403) | Restituisce punteggi (decidi tu) |
| Controllo | Le tue soglie per categoria, applicate da Mistral | Punteggi grezzi, logica libera |
| Chiamata | Parametro della richiesta di generazione | Chiamata separata a /v1/moderations |
| Caso d’uso | Filtrare prompt pericolosi | Classificare le risposte |
Esempio: pipeline completa
La pipeline seguente mostra la sequenziazione dei due meccanismi. La generazione è protetta da un guardrail focalizzato sul jailbreaking; la risposta viene poi classificata insieme alla domanda che l’ha prodotta e interviene una decisione personalizzata non appena un punteggio supera 0.5. Nota che i due passaggi restituiscono stati distinti—blocked_input e blocked_output—così i tuoi log indicano chiaramente dove si è fermata la richiesta.
from mistralai.client import errors
from mistralai.client.models import GuardrailConfigTypedDict
GUARDRAIL_JAILBREAK: list[GuardrailConfigTypedDict] = [
{
"block_on_error": True,
"moderation_llm_v2": {
"custom_category_thresholds": {"jailbreaking": 0.1},
"action": "block",
},
}
]
def secure_pipeline(user_message: str) -> dict:
"""Pipeline con guardrail (input) e moderazione (output)."""
# Passaggio 1: generazione con guardrail
try:
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": user_message}],
guardrails=GUARDRAIL_JAILBREAK,
)
except errors.SDKError as e:
if e.status_code == 403:
return {"status": "blocked_input", "content": None}
raise
generated = response.choices[0].message.content
if not isinstance(generated, str):
return {"status": "error", "content": None}
# Passaggio 2: moderare l'output, nel contesto della domanda
moderation = client.classifiers.moderate_chat(
model="mistral-moderation-2603",
inputs=[
{"role": "user", "content": user_message},
{"role": "assistant", "content": generated},
],
)
scores = moderation.results[0].category_scores or {}
if max(scores.values(), default=0.0) > 0.5:
return {"status": "blocked_output", "scores": scores}
return {"status": "ok", "content": generated, "scores": scores}
Punti chiave
- L’API di Moderazione utilizza il modello
mistral-moderation-2603per classificare i contenuti - Due modalità disponibili: testo semplice e conversazionale
- I punteggi vanno da 0.0 a 1.0: definisci tu le tue soglie decisionali
- La modalità conversazionale è più accurata perché tiene conto del contesto
- Combina guardrail (input) + moderazione (output) per una difesa a strati