Moderarea conținutului cu API-ul
Pe această pagină
Actualizat la 3 noiembrie 2026 pe baza ghidului Moderation de la OpenAI: categoriile
illicitșiillicit/violentpentru modelulomni-moderation-latestlipseau din listă și din cod. Sursă: Moderation.
Moderarea conținutului cu API-ul
API-ul de Moderare de la OpenAI detectează automat conținutul inadecvat. Este un instrument gratuit și esențial pentru orice aplicație care acceptă conținut generat de utilizatori. Lecția anterioară v-a arătat cum să scrieți filtre personalizate; aceasta vă oferă un clasificator antrenat care identifică ceea ce expresiile regulate nu vor prinde niciodată—amenințări voalate, insulte indirecte și formulări implicite.
API-ul de Moderare
Apelul este intenționat minimal: un model, un text și un rezultat care se reduce la un boolean. Câmpul flagged răspunde la întrebarea binară: „Acest conținut încalcă politicile de utilizare?“, în timp ce categories detaliază care dintre ele. Deoarece acest endpoint este gratuit, nu există niciun motiv economic să îl omiteți, chiar și la volume mari.
from openai import OpenAI
client = OpenAI()
# API-ul de Moderare este GRATUIT
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, ...)
Categorii de moderare
Î spatele valorii booleene se ascunde o grilă fină. Modelul returnează o decizie per categorie—hărțuire, hărțuire amenințătoare, ură, ură amenințătoare, instrucțiuni pentru acte ilicite (cu sau fără violență), auto-vătămare cu variantele sale (instrucțiuni și intenție), conținut sexual, conținut sexual implicând minori, violență și violență grafică—alături de un scor de încredere între 0.0 și 1.0 pentru fiecare.
Aceste scoruri contează mai mult decât decizia binară atunci când doriți să vă calibrați politica. O platformă de forum profesională ar putea dori să blocheze la 0.3 pentru hărțuire, în timp ce un serviciu de ficțiune ar putea accepta 0.7 pentru violență. Funcția de mai jos expune ambele niveluri de insight: categoriile declanșate efectiv și scorurile brute pentru propriile dumneavoastră praguri.
def analyze_moderation(text: str) -> dict:
"""Analiză detaliată a moderării."""
moderation = client.moderations.create(
model="omni-moderation-latest",
input=text
)
result = moderation.results[0]
# Categorii disponibile
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,
}
# Scoruri de încredere (0.0 la 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']}")
Flux complet de moderare
Moderarea input-urilor utilizatorilor
Să încapsulăm acest apel într-o componentă reutilizabilă. ContentModerator returnează o pereche explicită—acceptabil sau nu, cu motivul—în loc de un obiect brut pe care fiecare apelant ar trebui să-l reinterpreteze. Traducerea categoriilor într-un limbaj clar contează: acesta este vocabularul care va apărea în interfața și jurnalele dumneavoastră, iar acesta trebuie să fie inteligibil pentru echipa de moderare umană care preia controlul.
class ContentModerator:
"""Moderator de conținut pentru aplicații."""
def __init__(self, custom_threshold: float = 0.5):
self.client = OpenAI()
self.threshold = custom_threshold
def moderate(self, text: str) -> tuple[bool, dict]:
"""Moderare text. Returnează (este_acceptabil, detalii)."""
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": "Conținut inadecvat detectat",
"categories": categories
}
return True, {"reason": "Conținut acceptabil"}
def moderate_conversation(self, messages: list[str]) -> list[dict]:
"""Moderare o listă de mesaje."""
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
# Utilizare
moderator = ContentModerator()
acceptable, details = moderator.moderate("Hello, how can I help you?")
print(f"Acceptable: {acceptable}")
print(f"Details: {details}")
Integrarea în fluxul API
Moderarea încadrează apelul pe ambele părți. Filtrarea input-ului evită plata pentru generarea de conținut pe care l-ați respinge oricum; filtrarea output-ului protejează împotriva cazurilor în care modelul, provocat abil, produce el însuși ceva inacceptabil. Rețineți diferența de gestionare: pentru input, puteți spune utilizatorului ce a fost detectat, deoarece el l-a authored; pentru output, mesajul rămâne vag, deoarece detalierea lui ar însemna descrierea a ceea ce modelul tocmai a produs.
def moderated_chatbot(user_input: str) -> str:
"""Chatbot cu moderare atât a input-urilor, cât și a output-urilor."""
moderator = ContentModerator()
# 1. Moderare input
input_ok, input_details = moderator.moderate(user_input)
if not input_ok:
return (f"Mesajul dumneavoastră a fost blocat: "
f"{', '.join(input_details['categories'])}")
# 2. Generare răspuns
response = client.responses.create(
model="gpt-5.6-terra",
instructions="Respond in a professional and safe manner.",
input=user_input
)
# 3. Moderare output
output_ok, output_details = moderator.moderate(response.output_text)
if not output_ok:
return "Nu pot furniza acel răspuns."
return response.output_text
# Test
print(moderated_chatbot("What is the capital of France?"))
Moderare în lot (Batch)
Acest dublu apel adaugă latență, ceea ce este acceptabil în conversație, dar devine prohibitiv atunci când trebuie să procesați zece mii de recenzii ale clienților importate dintr-un fișier. Pentru a modera volume mari eficient, transmiteți un array direct: API-ul procesează toate textele într-o singură cerere și returnează rezultatele în aceeași ordine, permițându-vă să le reasociați după index.
def moderate_batch(texts: list[str]) -> list[dict]:
"""Moderare multiple texte într-o singură cerere."""
results = []
# API-ul acceptă un array de input-uri
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
# Utilizare
texts = [
"Hello, how are you?",
"Great product, I recommend it!",
"Customer service is excellent.",
]
results = moderate_batch(texts)
Jurnalizarea moderării
O decizie de moderare afectează un utilizator și, mai devreme sau mai târziu, va trebui să o justificați—fie unui client care contestă un blocaj, fie unui regulator. Prin urmare, jurnalizați sistematic verdictul, ID-ul utilizatorului, scorurile și un extras din text. Nivelul de log distinge cele două cazuri: warning pentru conținutul flagrat, care merită revizuire umană, și info pentru restul, care alimentează statisticile dumneavoastră.
import json
import logging
from datetime import datetime
logger = logging.getLogger("moderation")
def moderate_with_log(text: str, user_id: str = "anonymous") -> bool:
"""Moderare și jurnalizare rezultat pentru 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
# Utilizare
is_ok = moderate_with_log("Test message", user_id="user-123")
O ultimă avertizare înainte de a continua: moderarea clasifică conținutul; nu înțelege intenția. Un mesaj perfect politicos care încearcă să facă jailbreak asistentului dumneavoastră va trece de toate aceste filtre fără a fi flagrat nici măcar o dată. Acesta este subiectul lecției următoare.
Puncte cheie
- API-ul de Moderare este gratuit—utilizați-l sistematic
- Moderați atât input-urile (conținut utilizator), cât și output-urile (răspunsuri model)
- Modelul
omni-moderation-latestacoperă toate categoriile de conținut - Jurnalizați toate deciziile de moderare pentru audit
- Utilizați procesarea în lot pentru a modera volume mari eficient
- Moderarea completează instrucțiunile de sistem; nu le înlocuiește