Vai al contenuto principale
Italiano— Scegli una lingua
Menu

API di Moderazione di Mistral

Lezione 5 di 12 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Classificare i contenuti dopo la generazione
  2. Il modello Mistral Moderation 2
  3. L’endpoint /v1/moderations
  4. Struttura della risposta
  5. Moderare più testi in batch
  6. Guardrail vs API di Moderazione: quando usare cosa
  7. Esempio: pipeline completa
  8. Punti chiave

Aggiornato il 3 novembre 2026. L’esempio di risposta includeva precedentemente chiavi inesistenti (hate, violence, unpredictable); ora riflette le undici categorie di mistral-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 controlla e.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 SDK mistralai versione 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

AspettoGuardrail PersonalizzatiAPI di Moderazione
TempisticaPRIMA della generazioneDOPO la generazione
AzioneBlocca automaticamente (403)Restituisce punteggi (decidi tu)
ControlloLe tue soglie per categoria, applicate da MistralPunteggi grezzi, logica libera
ChiamataParametro della richiesta di generazioneChiamata separata a /v1/moderations
Caso d’usoFiltrare prompt pericolosiClassificare 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-2603 per 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