Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Moderazione dei contenuti con l'API

Lezione 19 di 22 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Moderazione dei contenuti con l’API
  2. L’API di Moderazione
  3. Categorie di moderazione
  4. Pipeline completa di moderazione
  5. Moderazione in batch
  6. Registrazione (Logging) della moderazione
  7. Punti chiave

Aggiornato il 3 novembre 2026 sulla base della guida Moderation di OpenAI: le categorie illicit e illicit/violent per il modello omni-moderation-latest mancavano dall’elenco e dal codice. Fonte: Moderation.

Moderazione dei contenuti con l’API

L’API di Moderazione di OpenAI rileva automaticamente i contenuti inappropriati. È uno strumento gratuito ed essenziale per qualsiasi applicazione che accetta contenuti generati dagli utenti. La lezione precedente ti ha mostrato come scrivere filtri personalizzati; questa ti offre un classificatore addestrato in grado di individuare ciò che le espressioni regolari non cattureranno mai: minacce velate, insulti indiretti e formulazioni implicite.

L’API di Moderazione

La chiamata è volutamente minimale: un modello, un testo e un risultato che si riduce a un booleano. Il campo flagged risponde alla domanda binaria: «Questo contenuto viola le policy d’uso?», mentre categories specifica quali. Poiché questo endpoint è gratuito, non esiste alcuna ragione economica per saltarlo, anche ad alti volumi.

from openai import OpenAI
client = OpenAI()

# L'API di Moderazione è GRATUITA
moderation = client.moderations.create(
    model="omni-moderation-latest",
    input="Hello, how are you?"
)

result = moderation.results[0]
print(f"Content flagged: {result.flagged}")
print(f"Categories: {result.categories}")

# Result:
# Content flagged: False
# Categories: Categories(harassment=False, hate=False, ...)

Categorie di moderazione

Dietro al booleano si nasconde una grana fine. Il modello restituisce una decisione per categoria: molestie, molestie minacciose, odio, odio minaccioso, istruzioni per atti illeciti (con o senza violenza), autolesionismo con le sue varianti (istruzioni e intento), contenuti sessuali, contenuti sessuali che coinvolgono minori, violenza e violenza grafica, insieme a un punteggio di confidenza compreso tra 0,0 e 1,0 per ciascuna.

Questi punteggi contano più della decisione binaria quando desideri calibrare la tua policy. Una piattaforma forum professionale potrebbe voler bloccare a 0,3 per le molestie, mentre un servizio di narrativa potrebbe accettare 0,7 per la violenza. La funzione seguente espone entrambi i livelli di insight: le categorie effettivamente attivate e i punteggi grezzi per le tue soglie personalizzate.

def analyze_moderation(text: str) -> dict:
    """Analisi dettagliata della moderazione."""
    moderation = client.moderations.create(
        model="omni-moderation-latest",
        input=text
    )

    result = moderation.results[0]

    # Categorie disponibili
    categories = {
        "harassment": result.categories.harassment,
        "harassment_threatening": result.categories.harassment_threatening,
        "hate": result.categories.hate,
        "hate_threatening": result.categories.hate_threatening,
        "illicit": result.categories.illicit,
        "illicit_violent": result.categories.illicit_violent,
        "self_harm": result.categories.self_harm,
        "self_harm_instructions": result.categories.self_harm_instructions,
        "self_harm_intent": result.categories.self_harm_intent,
        "sexual": result.categories.sexual,
        "sexual_minors": result.categories.sexual_minors,
        "violence": result.categories.violence,
        "violence_graphic": result.categories.violence_graphic,
    }

    # Punteggi di confidenza (da 0.0 a 1.0)
    scores = {
        "harassment": result.category_scores.harassment,
        "hate": result.category_scores.hate,
        "self_harm": result.category_scores.self_harm,
        "sexual": result.category_scores.sexual,
        "violence": result.category_scores.violence,
    }

    return {
        "flagged": result.flagged,
        "detected_categories": [k for k, v in categories.items() if v],
        "main_scores": {k: round(v, 4) for k, v in scores.items()},
    }

# Test
result = analyze_moderation("Hello everyone!")
print(f"Flagged: {result['flagged']}")
print(f"Scores: {result['main_scores']}")

Pipeline completa di moderazione

Moderazione degli input utente

Incastoniamo questa chiamata in un componente riutilizzabile. ContentModerator restituisce una coppia esplicita—accettabile o meno, con il motivo—piuttosto che un oggetto grezzo che ogni chiamante dovrebbe reinterpretare. Tradurre le categorie in un linguaggio chiaro è fondamentale: questo è il vocabolario che apparirà nella tua interfaccia e nei log, e deve essere comprensibile dal team di moderazione umana che subentra.

class ContentModerator:
    """Moderatore di contenuti per applicazioni."""

    def __init__(self, custom_threshold: float = 0.5):
        self.client = OpenAI()
        self.threshold = custom_threshold

    def moderate(self, text: str) -> tuple[bool, dict]:
        """Modera il testo. Restituisce (is_acceptable, details)."""
        moderation = self.client.moderations.create(
            model="omni-moderation-latest",
            input=text
        )

        result = moderation.results[0]

        if result.flagged:
            categories = []
            if result.categories.harassment:
                categories.append("harassment")
            if result.categories.hate:
                categories.append("hate speech")
            if result.categories.sexual:
                categories.append("sexual content")
            if result.categories.violence:
                categories.append("violence")
            if result.categories.self_harm:
                categories.append("self-harm")

            return False, {
                "reason": "Inappropriate content detected",
                "categories": categories
            }

        return True, {"reason": "Content acceptable"}

    def moderate_conversation(self, messages: list[str]) -> list[dict]:
        """Modera un elenco di messaggi."""
        results = []
        for msg in messages:
            acceptable, details = self.moderate(msg)
            results.append({
                "message": msg[:50] + "..." if len(msg) > 50 else msg,
                "acceptable": acceptable,
                **details
            })
        return results

# Utilizzo
moderator = ContentModerator()
acceptable, details = moderator.moderate("Hello, how can I help you?")
print(f"Acceptable: {acceptable}")
print(f"Details: {details}")

Integrazione nella pipeline API

La moderazione incornicia la chiamata su entrambi i lati. Filtrare l’input evita di pagare per la generazione su contenuti che avresti comunque rifiutato; filtrare l’output protegge dai casi in cui il modello, abilmente provocato, produce qualcosa di inaccettabile. Nota la differenza di gestione: per l’input, puoi dire all’utente cosa è stato rilevato, poiché ne è l’autore; per l’output, il messaggio rimane vago, perché dettagliarlo significherebbe descrivere ciò che il modello ha appena prodotto.

def moderated_chatbot(user_input: str) -> str:
    """Chatbot con moderazione sia degli input che degli output."""
    moderator = ContentModerator()

    # 1. Modera l'input
    input_ok, input_details = moderator.moderate(user_input)
    if not input_ok:
        return (f"Your message was blocked: "
                f"{', '.join(input_details['categories'])}")

    # 2. Genera la risposta
    response = client.responses.create(
        model="gpt-5.6-terra",
        instructions="Respond in a professional and safe manner.",
        input=user_input
    )

    # 3. Modera l'output
    output_ok, output_details = moderator.moderate(response.output_text)
    if not output_ok:
        return "I am unable to provide that response."

    return response.output_text

# Test
print(moderated_chatbot("What is the capital of France?"))

Moderazione in batch

Questa doppia chiamata aggiunge latenza, cosa accettabile in una conversazione ma proibitiva quando devi elaborare diecimila recensioni di clienti importate da un file. Per moderare grandi volumi in modo efficiente, passa direttamente un array: l’API elabora tutti i testi in una singola richiesta e restituisce i risultati nello stesso ordine, permettendoti di riassociarli per indice.

def moderate_batch(texts: list[str]) -> list[dict]:
    """Modera più testi in una singola richiesta."""
    results = []

    # L'API accetta un array di input
    moderation = client.moderations.create(
        model="omni-moderation-latest",
        input=texts
    )

    for i, result in enumerate(moderation.results):
        results.append({
            "index": i,
            "text_preview": texts[i][:50],
            "flagged": result.flagged,
        })

    flagged_count = sum(1 for r in results if r["flagged"])
    print(f"Moderated {len(texts)} texts: {flagged_count} flagged")

    return results

# Utilizzo
texts = [
    "Hello, how are you?",
    "Great product, I recommend it!",
    "Customer service is excellent.",
]
results = moderate_batch(texts)

Registrazione (Logging) della moderazione

Una decisione di moderazione influisce su un utente e prima o poi dovrai giustificarla—che sia per un cliente che contesta un blocco o per un regolatore. Pertanto, registra sistematicamente il verdetto, l’ID utente, i punteggi e un estratto del testo. Il livello di log distingue i due casi: warning per i contenuti segnalati, che meritano una revisione umana, e info per il resto, che alimenta le tue statistiche.

import json
import logging
from datetime import datetime

logger = logging.getLogger("moderation")

def moderate_with_log(text: str, user_id: str = "anonymous") -> bool:
    """Modera e registra il risultato per l'audit."""
    moderation = client.moderations.create(
        model="omni-moderation-latest",
        input=text
    )

    result = moderation.results[0]

    log_entry = {
        "timestamp": datetime.now().isoformat(),
        "user_id": user_id,
        "flagged": result.flagged,
        "text_preview": text[:100],
        "scores": {
            "harassment": round(result.category_scores.harassment, 4),
            "hate": round(result.category_scores.hate, 4),
            "violence": round(result.category_scores.violence, 4),
        }
    }

    if result.flagged:
        logger.warning(json.dumps(log_entry))
    else:
        logger.info(json.dumps(log_entry))

    return not result.flagged

# Utilizzo
is_ok = moderate_with_log("Test message", user_id="user-123")

Un ultimo avvertimento prima di procedere: la moderazione classifica i contenuti; non comprende l’intento. Un messaggio perfettamente educato che tenta di aggirare il tuo assistente supererà tutti questi filtri senza essere segnalato nemmeno una volta. Questo è l’argomento della prossima lezione.

Punti chiave

  • L’API di Moderazione è gratuita: usala sistematicamente
  • Modera sia gli input (contenuti utente) che gli output (risposte del modello)
  • Il modello omni-moderation-latest copre tutte le categorie di contenuti
  • Registra tutte le decisioni di moderazione per l’audit
  • Usa l’elaborazione in batch per moderare grandi volumi in modo efficiente
  • La moderazione integra le istruzioni di sistema; non le sostituisce