Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Punteggi e soglie di moderazione

Lezione 7 di 12 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Interpretare i punteggi di moderazione
  2. Definire le tue soglie: la matrice decisionale
  3. Sistema di classificazione multilivello
  4. Esempio pratico: analizzare e decidere
  5. Regolare le soglie dinamicamente
  6. Errori da evitare
  7. Punti chiave

Aggiornato il 3 novembre 2026. I profili di soglia facevano precedentemente riferimento a categorie inesistenti (hate, violence, unpredictable); ora sono allineati alle undici chiavi di mistral-moderation-2603, inclusa dangerous. La guida all’interpretazione dei punteggi è fornita come riferimento formativo, poiché Mistral non ne pubblica una. Il monitor sollevava precedentemente un KeyError per qualsiasi categoria mancante nel profilo e utilizzava datetime.utcnow(), deprecato da Python 3.12. Fonti: Moderation & Guardrailing · datetime.utcnow.

Interpretare i punteggi di moderazione

Ogni categoria restituisce un punteggio compreso tra 0.0 e 1.0. Ma cosa significano realmente questi numeri? E come imposti le soglie decisionali per la tua applicazione? Questa lezione ti fornisce le chiavi per trasformare i punteggi grezzi in decisioni automatizzate, passando dalla misurazione alla politica di utilizzo.

Comprendi innanzitutto che Mistral non presenta questi punteggi come probabilità calibrate. Un punteggio di 0.6 non significa “sei possibilità su dieci che questo testo sia pericoloso”; è un segnale forte dal classificatore. La documentazione evidenzia due punti utili. I booleani categories nella risposta applicano soglie scelte da Mistral per prestazioni ottimali sul suo set di test interno; puoi usarle, oppure partire dai punteggi grezzi e impostare le tue. Su quel set di test, la precisione per categoria varia da 0.8 a 1.0 e il recall da 0.7 a 1.0: si verificano sia falsi positivi che contenuti mancati, ecco perché le soglie sintonizzate manualmente sono fondamentali.

La griglia seguente non è pubblicata da Mistral: è un riferimento iniziale da validare rispetto alle tue metriche.

IntervalloInterpretazione
0.0 - 0.1Contenuto chiaramente sicuro, nessun segnale rilevato
0.1 - 0.3Segnale debole, potenzialmente benigno ma ambiguo
0.3 - 0.5Segnale moderato, contenuto potenzialmente problematico
0.5 - 0.7Segnale forte, contenuto molto probabilmente problematico
0.7 - 1.0Segnale molto forte, contenuto manifestamente pericoloso

Definire le tue soglie: la matrice decisionale

Scegliere una soglia è un compromesso tra sicurezza (bloccare il più possibile) e usabilità (minimizzare i falsi positivi). Nessuna impostazione vince su entrambi i fronti, e affermare il contrario porta a discussioni infinite. Il metodo di lavoro consiste nel definire tre profili espliciti e mappare ciascuna applicazione su uno di essi.

Il profilo rigoroso mira a un’applicazione consumer dove potrebbero essere presenti minori; il profilo bilanciato si adatta a un’applicazione professionale B2B con utenti identificati; il profilo permissivo è riservato a uno strumento interno gestito da esperti che sanno cosa stanno chiedendo.

# Tre profili di soglia
PROFILES = {
    "strict": {
        # Applicazione consumer, possibili bambini
        "sexual": 0.1,
        "hate_and_discrimination": 0.1,
        "violence_and_threats": 0.1,
        "dangerous": 0.1,
        "criminal": 0.1,
        "selfharm": 0.1,
        "health": 0.2,
        "financial": 0.2,
        "law": 0.2,
        "pii": 0.1,
        "jailbreaking": 0.1,
    },
    "balanced": {
        # Applicazione professionale B2B
        "sexual": 0.2,
        "hate_and_discrimination": 0.15,
        "violence_and_threats": 0.25,
        "dangerous": 0.15,
        "criminal": 0.15,
        "selfharm": 0.15,
        "health": 0.4,
        "financial": 0.4,
        "law": 0.4,
        "pii": 0.2,
        "jailbreaking": 0.15,
    },
    "permissive": {
        # Strumento interno per esperti
        "sexual": 0.3,
        "hate_and_discrimination": 0.2,
        "violence_and_threats": 0.4,
        "dangerous": 0.2,
        "criminal": 0.2,
        "selfharm": 0.2,
        "health": 0.7,
        "financial": 0.7,
        "law": 0.7,
        "pii": 0.3,
        "jailbreaking": 0.2,
    },
}

Confronta la colonna health tra i profili: 0.2, poi 0.4, poi 0.7. Lo stesso scambio sul dosaggio verrà bloccato nel primo caso e accettato nell’ultimo. Decide il contesto d’uso, non la natura del testo.

Sistema di classificazione multilivello

Bloccare o accettare è una visione eccessivamente semplificata della realtà. Tra i contenuti manifestamente sicuri e quelli manifestamente violatori esiste una zona grigia dove la decisione giusta è visualizzare segnalando. La funzione seguente introduce questo terzo stato: sopra la soglia, blocca; sopra il 60% della soglia, avvisa e registra; al di sotto, lascia passare.

from enum import Enum

class RiskLevel(Enum):
    SAFE = "safe"          # Verde: contenuto sicuro
    WARNING = "warning"    # Arancione: contenuto da monitorare
    BLOCKED = "blocked"    # Rosso: contenuto bloccato

def classify_content(scores: dict, thresholds: dict) -> dict:
    """Classifica i contenuti in 3 livelli di rischio."""
    blocking_violations = []
    warnings = []

    for category, threshold in thresholds.items():
        score = scores.get(category, 0)

        if score > threshold:
            blocking_violations.append({
                "category": category,
                "score": round(score, 3)
            })
        elif score > threshold * 0.6:
            # Zona di avviso: 60% della soglia
            warnings.append({
                "category": category,
                "score": round(score, 3)
            })

    if blocking_violations:
        return {
            "level": RiskLevel.BLOCKED,
            "violations": blocking_violations,
            "action": "block_and_log"
        }
    elif warnings:
        return {
            "level": RiskLevel.WARNING,
            "warnings": warnings,
            "action": "display_and_log"
        }
    else:
        return {
            "level": RiskLevel.SAFE,
            "action": "display"
        }

Il valore della zona arancione è tanto operativo quanto educativo: ti mostra cosa sfiora le tue soglie. Se una categoria genera molti avvisi senza mai superare la linea, sai che una regolazione di pochi centesimi sposterebbe un volume significativo di traffico.

Esempio pratico: analizzare e decidere

L’assemblaggio si riduce a una funzione: chiama il classificatore, applica il profilo, prendi la decisione. Il confronto seguente serve da dimostrazione: un dosaggio di paracetamolo viene bloccato nel profilo rigoroso sotto health e accettato nel profilo permissivo, senza cambiare una singola riga di testo.

from mistralai.client import Mistral
import os

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

def moderate_and_decide(text: str, profile: str = "balanced") -> dict:
    """Modera il testo e prende una decisione basata sul profilo."""
    # Chiamata all'API di moderazione
    response = client.classifiers.moderate(
        model="mistral-moderation-2603",
        inputs=[text]
    )
    scores = response.results[0].category_scores or {}

    # Applica le soglie del profilo
    thresholds = PROFILES[profile]
    classification = classify_content(scores, thresholds)

    return {
        "text": text[:80],
        "profile": profile,
        "raw_scores": {k: round(v, 3) for k, v in scores.items()},
        "decision": classification
    }

# Test con diversi profili
text = "Take 2 paracetamol tablets every 6 hours"

# Profilo rigoroso: probabilmente bloccato (health)
result_strict = moderate_and_decide(text, "strict")

# Profilo permissivo: probabilmente accettato
result_permissive = moderate_and_decide(text, "permissive")

Regolare le soglie dinamicamente

In produzione, le tue soglie devono evolversi, e guidi questa evoluzione con i dati. Il monitor seguente scrive ogni decisione in un file JSONL e mantiene contatori per blocchi, avvisi e passaggi, categoria per categoria. Il report risultante ti fornisce un tasso di blocco per categoria: l’unica metrica che ti dice se una soglia è troppo bassa.

import json
from datetime import datetime, timezone

class ModerationMonitor:
    """Raccoglie le metriche di moderazione per regolare le soglie."""

    def __init__(self, log_file: str = "moderation_logs.jsonl"):
        self.log_file = log_file
        self.stats = {cat: {"blocked": 0, "warned": 0, "passed": 0}
                     for cat in PROFILES["balanced"].keys()}

    def log_decision(self, scores: dict, thresholds: dict, decision: str):
        """Registra una decisione di moderazione."""
        entry = {
            "timestamp": datetime.now(timezone.utc).isoformat(),
            "scores": scores,
            "thresholds": thresholds,
            "decision": decision
        }
        with open(self.log_file, "a") as f:
            f.write(json.dumps(entry) + "\n")

        # Aggiorna i contatori
        for cat, threshold in thresholds.items():
            score = scores.get(cat, 0.0)
            self.stats.setdefault(cat, {"blocked": 0, "warned": 0, "passed": 0})
            if score > threshold:
                self.stats[cat]["blocked"] += 1
            elif score > threshold * 0.6:
                self.stats[cat]["warned"] += 1
            else:
                self.stats[cat]["passed"] += 1

    def report(self) -> dict:
        """Genera un report per regolare le soglie."""
        report = {}
        for cat, stats in self.stats.items():
            total = sum(stats.values())
            if total > 0:
                report[cat] = {
                    "block_rate": round(stats["blocked"] / total, 3),
                    "warning_rate": round(stats["warned"] / total, 3),
                    "total": total
                }
        return report

Errori da evitare

Il primo errore è applicare un’unica soglia a tutte le categorie. Ogni categoria ha la propria distribuzione di punteggi: una soglia di 0.3 per hate_and_discrimination non significa la stessa cosa di 0.3 per health, dove i contenuti legittimi risiedono naturalmente più in alto sulla scala. Regola ogni categoria individualmente, anche se questo significa prendere undici decisioni invece di una.

Il secondo è ignorare i falsi positivi. Un alto tasso di blocco erode la fiducia degli utenti molto più velocemente di un incidente isolato, perché colpisce persone che agiscono in buona fede. Traccia il tasso di blocco per categoria e alza le soglie quando i dati lo giustificano.

Il terzo, più insidioso, è non registrare le decisioni. Senza log, non puoi regolare le tue soglie in modo informato e torni a discussioni basate sulle opinioni. Registra sistematicamente punteggi, soglie applicate e decisioni prese: questo corpus è ciò che renderà la prossima revisione rapida e inconfutabile.

Punti chiave

  • I punteggi vanno da 0.0 a 1.0; non sono probabilità calibrate e Mistral incoraggia a impostare le proprie soglie
  • Definisci profili di soglia adattati al tuo contesto (rigoroso, bilanciato, permissivo)
  • Implementa un sistema a 3 livelli: sicuro, avviso, bloccato
  • Registra tutte le decisioni per regolare continuamente le tue soglie
  • Ogni categoria richiede la propria soglia: nessun valore unico va bene per tutte