Vai al contenuto principale
Italiano— Scegli una lingua
Menu

L'API di Moderazione di OpenAI

Lezione 5 di 14 Aggiornata il 3 novembre 2026 Avanzato
In questa pagina
  1. Uno strumento di moderazione integrato
  2. Cosa restituisce l’API
  3. Categorie rilevate
  4. Moderare entrambe le estremità della pipeline
  5. Cosa questa API non fa
  6. Punti chiave

Aggiornato il 3 novembre 2026 sulla base della guida Moderation di OpenAI: aggiunta la categoria illicit (e illicit/violent), mancante nella tabella, insieme alle categorie applicabili alle immagini. Fonte: Moderation.

Uno strumento di moderazione integrato

OpenAI mette a disposizione gratuitamente un’API di Moderazione che analizza il testo per rilevare contenuti potenzialmente dannosi. Questa è la prima linea di difesa da integrare in qualsiasi applicazione che utilizzi i modelli OpenAI, ma non sei limitato a questo solo caso d’uso: poiché accetta testo grezzo in input, puoi usarla anche per filtrare input destinati ad altri modelli. Il fatto che sia gratuita cambia il modo in cui affronti il problema. I consueti compromessi—dovremmo moderare ogni richiesta o solo quelle sospette?—perdono peso, dato che l’unico costo residuo è la latenza.

Cosa restituisce l’API

La chiamata base sta in una riga; è la risposta che richiede attenzione. L’API restituisce tre elementi distinti: un booleano flagged che riflette la decisione di OpenAI, l’elenco delle categorie effettivamente attivate e, soprattutto, punteggi continui per categoria. Sono questi punteggi a fare la differenza in produzione, perché ti permettono di decidere dove tracciare tu stesso la linea di confine invece di ereditare una soglia progettata per un uso generico.

from openai import OpenAI

client = OpenAI()

def moderate_content(text: str) -> dict:
    """Analizza il testo tramite l'API di Moderazione di OpenAI."""
    response = client.moderations.create(input=text)
    result = response.results[0]

    return {
        "blocked": result.flagged,
        "categories": {
            cat: flagged
            for cat, flagged in result.categories.__dict__.items()
            if flagged
        },
        "scores": {
            cat: round(score, 4)
            for cat, score in result.category_scores.__dict__.items()
            if score > 0.01
        },
    }

# Test con diversi tipi di contenuto
examples = [
    "How do I bake a chocolate cake?",
    "I will kill you if you don't answer me",
    "Explain how AES encryption works",
]

for text in examples:
    result = moderate_content(text)
    status = "BLOCKED" if result["blocked"] else "OK"
    print(f"{status} : {text[:50]}...")
    if result["categories"]:
        print(f"  Categories : {list(result['categories'].keys())}")

I tre esempi di test non sono casuali: il primo dovrebbe passare, il secondo dovrebbe essere bloccato e il terzo—una domanda tecnica perfettamente legittima—ti mostra come si comporta la tua pipeline di fronte a vocabolario legato alla sicurezza. Questo è esattamente il tipo di richiesta che un team di cybersecurity gestisce quotidianamente.

Categorie rilevate

L’API classifica i contenuti problematici lungo diversi assi, ciascuno corrispondente a un tipo distinto di danno.

Category Description
harassment Harassment, threats, intimidation
hate Hate speech based on identity
illicit Advice or instructions for committing illicit acts
self-harm Self-harm, suicide
sexual Explicit sexual content
violence Graphic violence, threats

Ogni categoria ha anche delle sottocategorie (ad esempio harassment/threatening, illicit/violent, violence/graphic) per un filtraggio più fine. Con omni-moderation-latest, solo self-harm e le sue varianti, sexual e violence (con violence/graphic) si applicano anche alle immagini; le altre categorie si applicano solo al testo. Questa granularità ti evita di fare compromessi grossolani: una piattaforma di moderazione per forum potrebbe voler bloccare harassment/threatening tollerando al contempo il semplice harassment, che copre molte dispute ordinarie.

Quando devi elaborare grandi volumi—ad esempio un’analisi retrospettiva di una cronologia di conversazioni—l’API accetta una lista e restituisce un risultato per ogni elemento, evitando molteplici round-trip di rete.

def moderate_batch(messages: list[str]) -> list[dict]:
    """Modera più messaggi in un'unica chiamata."""
    response = client.moderations.create(input=messages)
    results = []
    for i, result in enumerate(response.results):
        results.append({
            "index": i,
            "text": messages[i][:50],
            "blocked": result.flagged,
            "max_score": max(
                score
                for score in result.category_scores.__dict__.values()
            ),
        })
    return results

Moderare entrambe le estremità della pipeline

Un errore comune è moderare solo gli input. Questo si basa su un’intuizione errata: se il messaggio in arrivo è accettabile, anche la risposta lo sarà. Eppure un modello può produrre contenuti problematici partendo da una richiesta neutra, specialmente quando si basa su documenti recuperati il cui contenuto nessuno ha verificato. La classe seguente applica quindi lo stesso trattamento in entrambe le direzioni, aggiungendo una soglia personalizzata che rende più severa la decisione predefinita dell’API.

class ModerationPipeline:
    """Pipeline di moderazione input + output per un'applicazione LLM."""

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

    def moderate_input(self, message: str) -> tuple[bool, dict]:
        """Modera il messaggio PRIMA dell'invio al modello."""
        result = self.client.moderations.create(input=message).results[0]
        scores = result.category_scores.__dict__
        high_categories = {
            cat: score for cat, score in scores.items() if score > self.threshold
        }
        blocked = result.flagged or bool(high_categories)
        return blocked, {"flagged_api": result.flagged, "custom_categories": high_categories}

    def moderate_output(self, response: str) -> tuple[bool, dict]:
        """Modera la risposta del modello PRIMA dell'invio all'utente."""
        return self.moderate_input(response)

    def process_message(self, user_message: str, system_prompt: str) -> str:
        """Pipeline completa: moderazione input, LLM, moderazione output."""
        # Passo 1: moderazione input
        input_blocked, details = self.moderate_input(user_message)
        if input_blocked:
            return "Your message cannot be processed. Please rephrase it."

        # Passo 2: chiamata al modello
        response = self.client.chat.completions.create(
            model="gpt-5.6-sol",
            messages=[
                {"role": "system", "content": system_prompt},
                {"role": "user", "content": user_message},
            ],
        )
        model_response = response.choices[0].message.content

        # Passo 3: moderazione output
        output_blocked, _ = self.moderate_output(model_response)
        if output_blocked:
            return "The response was filtered for non-compliance."

        return model_response

# Utilizzo
pipeline = ModerationPipeline(custom_threshold=0.5)
response = pipeline.process_message(
    "How do I protect my application against SQL injections?",
    "You are an expert in defensive cybersecurity."
)
print(response)

Cosa questa API non fa

Il suo limite più importante è anche il più frainteso: non rileva il prompt injection. Un messaggio educato, perfettamente innocuo dal punto di vista del contenuto, ma che chiede al modello di ignorare le sue istruzioni, passerà senza attivare alcuna categoria. Aspettarsi che protegga dalla manipolazione è come installare un rilevatore di fumo sperando che fermi i ladri.

I falsi positivi sono il secondo limite, particolarmente sensibili in contesti di sicurezza o medici, dove descrivere una minaccia fa parte del lavoro. Viene aggiunta una chiamata di rete supplementare a ogni richiesta, il che conta quando miri a risposte in tempo reale. Il rilevamento rimane più affidabile in inglese rispetto ad altre lingue, un punto cieco che gli attaccanti conoscono perfettamente. Infine, categorie e soglie evolvono con gli aggiornamenti: un set di calibrazione vecchio di sei mesi merita una nuova verifica.

Questi limiti dettano come usare lo strumento. Modera in entrambe le direzioni, adatta le soglie categoria per categoria invece che globalmente e combinala sistematicamente con altri livelli—rilevamento di injection, filtraggio della logica di business—che le lezioni seguenti dettagliano. Registra i risultati, perché osservare i tuoi stessi falsi positivi è il modo per imparare dove spostare i cursori. E pianifica il caso in cui l’API non sia disponibile: decidi ora, mentre le acque sono calme, se la tua applicazione debba bloccare per default o lasciar passare il traffico, invece di scoprire quel comportamento durante un incidente.

Punti chiave

  • L’API di Moderazione è gratuita, veloce e semplice da integrare
  • Rileva contenuti offensivi ma non injection o jailbreak
  • La pipeline input-modello-output deve essere moderata a entrambe le estremità
  • Le soglie predefinite raramente sono adatte: adattale al tuo contesto
  • È uno strato tra gli altri, mai l’unica linea di difesa