Moderazione dei contenuti su larga scala
In questa pagina
Lezione aggiornata il 3 novembre 2026 sulla base della documentazione OpenAI:
temperatureetop_psono accettati solo con uno sforzo di ragionamento pari anone, mentre i modelli GPT-5.6 ragionano per impostazione predefinita (medium). Le chiamate che impostano questi parametri devono quindi specificarereasoning={"effort": "none"}(API Responses) oreasoning_effort="none"(Chat Completions). Fonti: Utilizzo di GPT-6 · GPT-5.6 Terra.
Proteggere i tuoi utenti in produzione
Non appena la tua applicazione va online, devi gestire i contenuti inappropriati, sia in ingresso (prompt malevoli) che in uscita (risposte problematiche). Questo requisito bidirezionale coglie spesso i team alla sprovvista. La maggior parte delle persone pensa prima di tutto a filtrare ciò che gli utenti inviano, ma il rischio reputazionale si concentra su ciò che la tua applicazione pubblica a tuo nome. Un modello ben allineato genera raramente contenuti scioccanti di sua spontanea volontà, ma può farlo se sollecitato, e il tuo brand appare in cima allo screenshot.
Passeremo da una singola chiamata API a una pipeline asincrona ad alto throughput, scalando passo dopo passo.
Il primo strato: l’API Moderations
L’API Moderations classifica il testo in diverse categorie di rischio e restituisce sia un verdetto binario che punteggi dettagliati. È veloce e gratuita, rendendola il filtro naturale iniziale per qualsiasi applicazione pubblica. La funzione sottostante espone solo le categorie con punteggi superiori a 0,3, una soglia volutamente bassa. In questa fase, vuoi vedere cosa si avvicina alla linea, non solo cosa la oltrepassa.
import openai
client = openai.OpenAI()
def moderate_content(text: str) -> dict:
"""Controlla se il testo contiene contenuti inappropriati."""
response = client.moderations.create(
model="omni-moderation-latest",
input=text,
)
result = response.results[0]
return {
"flagged": result.flagged,
"categories": {
cat: score
for cat, score in result.category_scores.__dict__.items()
if score > 0.3
},
}
# Esempio
result = moderate_content("How do I bake a chocolate cake?")
print(f"Flagged: {result['flagged']}")
In produzione, un verdetto binario non è sufficiente. A seconda del contenuto e del contesto, potresti volerlo consentire, riscriverlo, bloccarlo o escalare la questione a un essere umano: quattro decisioni distinte che dovresti nominare esplicitamente nel codice invece di improvvisare con booleani. La pipeline sottostante formalizza queste azioni, applica soglie per categoria e aggiunge un secondo strato per il rilevamento dell’iniezione di prompt.
from enum import Enum
from dataclasses import dataclass
class ModerationAction(Enum):
ALLOW = "allow"
MODIFY = "modify"
BLOCK = "block"
ESCALATE = "escalate"
@dataclass
class ModerationResult:
action: ModerationAction
reason: str | None = None
modified_content: str | None = None
class ModerationPipeline:
"""Pipeline di moderazione multistrato."""
def __init__(self, thresholds: dict | None = None):
self.thresholds = thresholds or {
"harassment": 0.7,
"hate": 0.7,
"self-harm": 0.5,
"sexual": 0.7,
"violence": 0.7,
}
def moderate_input(self, text: str) -> ModerationResult:
"""Modera il contenuto in ingresso (prompt dell'utente)."""
moderation = client.moderations.create(
model="omni-moderation-latest",
input=text,
)
result = moderation.results[0]
if result.flagged:
problematic_categories = [
cat for cat, flagged in result.categories.__dict__.items()
if flagged
]
return ModerationResult(
action=ModerationAction.BLOCK,
reason=f"Contenuto inappropriato: {', '.join(problematic_categories)}",
)
# Rilevamento iniezione di prompt
if self._detect_injection(text):
return ModerationResult(
action=ModerationAction.BLOCK,
reason="Tentativo di iniezione di prompt rilevato",
)
return ModerationResult(action=ModerationAction.ALLOW)
def moderate_output(self, response: str) -> ModerationResult:
"""Modera il contenuto in uscita (risposta LLM)."""
moderation = client.moderations.create(
model="omni-moderation-latest",
input=response,
)
if moderation.results[0].flagged:
return ModerationResult(
action=ModerationAction.BLOCK,
reason="La risposta generata contiene contenuti inappropriati",
)
return ModerationResult(action=ModerationAction.ALLOW)
def _detect_injection(self, text: str) -> bool:
"""Rileva tentativi di iniezione di prompt."""
markers = [
"ignore previous instructions",
"ignore your instructions",
"forget your guidelines",
"you are now",
"new role",
"system prompt",
"jailbreak",
]
text_lower = text.lower()
return any(m in text_lower for m in markers)
La soglia di 0,5 per self-harm, più severa rispetto allo 0,7 usato per altre categorie, illustra il ragionamento che dovresti applicare a ogni soglia. Qui, il costo di un falso positivo non è minimamente paragonabile al costo di un falso negativo, quindi abbassi l’asticella. Effettua questo compromesso categoria per categoria, in base al tuo pubblico, invece di applicare un valore uniforme.
Il rilevamento delle iniezioni basato su marcatori comporta una riserva. Cattura i tentativi ingenui, che rappresentano la maggior parte del volume, e nient’altro: una formulazione leggermente diversa o una versione tradotta lo supera. Trattalo come un filtro del rumore, non come una difesa. La vera protezione contro le iniezioni è architetturale: non dare mai al modello capacità che un prompt dirottato potrebbe sfruttare.
Gestire il carico
In un’applicazione ad alto traffico, la moderazione sincrona diventa un collo di bottiglia: ogni messaggio attende il suo verdetto prima di essere elaborato. Un moderatore asincrono disaccoppia questi passaggi accodando i contenuti per il consumo da parte di più worker, tracciando allo stesso tempo statistiche utili.
import asyncio
class AsyncModerator:
"""Modera i contenuti in modo asincrono per un alto throughput."""
def __init__(self, num_workers: int = 10):
self.pipeline = ModerationPipeline()
self.queue: asyncio.Queue = asyncio.Queue()
self.num_workers = num_workers
self.stats = {"allowed": 0, "blocked": 0, "escalated": 0}
async def worker(self):
while True:
task = await self.queue.get()
try:
result = self.pipeline.moderate_input(task["text"])
task["callback"](result)
match result.action:
case ModerationAction.ALLOW:
self.stats["allowed"] += 1
case ModerationAction.BLOCK:
self.stats["blocked"] += 1
case ModerationAction.ESCALATE:
self.stats["escalated"] += 1
finally:
self.queue.task_done()
async def start(self):
for _ in range(self.num_workers):
asyncio.create_task(self.worker())
def report(self) -> str:
total = sum(self.stats.values())
if total == 0:
return "Nessun contenuto moderato."
return (
f"Totale: {total} | "
f"Consentiti: {self.stats['allowed']} ({self.stats['allowed']/total:.1%}) | "
f"Bloccati: {self.stats['blocked']} ({self.stats['blocked']/total:.1%})"
)
Il tasso di blocco prodotto da report è la tua metrica di calibrazione primaria. Se salta improvvisamente al 15% dopo aver operato allo 0,5%, esistono solo due spiegazioni: sei sotto un attacco coordinato o hai appena rotto le tue soglie. In entrambi i casi, vuoi saperlo entro un’ora, non alla prossima revisione mensile.
Un’ultima limitazione merita una menzione: l’API Moderations non sa nulla del tuo business. Un messaggio perfettamente accettabile in generale potrebbe violare le tue regole specifiche, come richiedere consigli medici a un assistente bancario, cercare di ottenere una tariffa fuori rete o aggirare una procedura. La moderazione contestuale aggiunge questo strato inviando il messaggio a un modello con le tue regole esplicite, ma solo dopo che il filtro standard lo ha lasciato passare.
def contextual_moderation(
text: str,
app_context: str,
business_rules: list[str],
) -> ModerationResult:
"""Moderazione consapevole del contesto, su misura per l'applicazione."""
pipeline = ModerationPipeline()
standard_result = pipeline.moderate_input(text)
if standard_result.action == ModerationAction.BLOCK:
return standard_result
verification_prompt = (
f"Contesto dell'applicazione: {app_context}\n\n"
f"Regole aziendali da verificare:\n"
+ "\n".join(f"- {r}" for r in business_rules)
+ f"\n\nMessaggio utente: {text}\n\n"
"Il messaggio è conforme a tutte le regole? "
"Rispondi sì o no con una breve giustificazione."
)
response = client.responses.create(
model="gpt-5.6-terra",
reasoning={"effort": "none"}, # temperature richiede effort none
input=verification_prompt,
max_output_tokens=100,
temperature=0.0,
)
if "no" in response.output_text.lower()[:10]:
return ModerationResult(
action=ModerationAction.BLOCK,
reason=response.output_text,
)
return ModerationResult(action=ModerationAction.ALLOW)
L’ordine di questi due controlli è fondamentale. Il filtro gratuito e veloce viene eseguito per primo e la chiamata al modello a pagamento avviene solo per i messaggi che lo superano. Sul traffico reale, questo copre quasi tutti i messaggi. Fare l’inverso, pagando per una chiamata al modello su contenuti che l’API Moderations avrebbe rifiutato in millisecondi, sarebbe uno spreco.
Mantenere un registro difendibile
Una decisione di moderazione è una decisione di cui dovrai rispondere, in un modo o nell’altro. Hai bisogno di un registro, ma uno che non diventi esso stesso un problema. Il commento nel codice evidenzia la riga più importante del file: registra l’azione, il motivo e la lunghezza, mai il testo grezzo. Archiviare i messaggi degli utenti in un file di log ti espone a obblighi di protezione dei dati ben più pesanti del servizio fornito.
import json
import time
from pathlib import Path
class ModerationLog:
"""Registra tutte le decisioni di moderazione a fini di audit."""
def __init__(self, log_path: str = "logs/moderation.jsonl"):
self.path = Path(log_path)
self.path.parent.mkdir(parents=True, exist_ok=True)
def record(
self,
text: str,
result: ModerationResult,
source: str = "input",
):
entry = {
"timestamp": time.time(),
"source": source,
"action": result.action.value,
"reason": result.reason,
"text_length": len(text),
# NON registrare il testo grezzo per la privacy
}
with open(self.path, "a") as f:
f.write(json.dumps(entry) + "\n")
Se devi comunque essere in grado di recuperare un messaggio specifico durante una controversia, registra un hash del testo invece del testo stesso. Questo ti permette di confermare che un determinato contenuto corrisponde a una decisione registrata senza conservare il contenuto dalla tua parte.
Punti chiave
- Modera sia gli input (prompt) che gli output (risposte)
- Usa l’API Moderations come primo strato, veloce e gratuito
- Regola le soglie categoria per categoria in base al costo reale di un falso negativo
- Aggiungi il rilevamento delle iniezioni sapendo che cattura solo i tentativi ingenui
- Registra tutte le decisioni per l’audit senza archiviare contenuti grezzi