Moderacija sadržaja putem API-ja
Na ovoj stranici
Ažurirano 3. studenog 2026. na temelju OpenAI-jevog vodiča Moderation: kategorije
illicitiillicit/violentza modelomni-moderation-latestnedostajale su na popisu i u kodu. Izvor: Moderation.
Moderacija sadržaja putem API-ja
OpenAI-jev API za moderaciju automatski otkriva neprikladan sadržaj. Riječ je o besplatnom, ključnom alatu za svaku aplikaciju koja prihvaća sadržaj koji generiraju korisnici. Prethodna lekcija pokazala ti je kako pisati prilagođene filtre; ova ti daje trenirani klasifikator koji prepoznaje ono što regularni izrazi nikada neće uhvatiti – prikrivene prijetnje, neizravne uvrede i implicitne formulacije.
API za moderaciju
Poziv je namjerno minimalan: jedan model, jedan tekst i rezultat koji se svodi na boolean vrijednost. Polje flagged odgovara na binarno pitanje „Krši li ovaj sadržaj pravila korištenja?“, dok categories detaljno navodi koje su točno povrijeđene. Budući da je ova krajnja točka besplatna, nema ekonomskog razloga za preskakanje, čak ni pri velikim volumenima.
from openai import OpenAI
client = OpenAI()
# The Moderation API is FREE
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, ...)
Kategorije moderacije
Iza boolean vrijednosti krije se fino podešena mreža. Model vraća odluku po kategoriji – uznemiravanje, prijeteće uznemiravanje, govor mržnje, prijeteći govor mržnje, upute za nedopuštene radnje (s nasiljem ili bez), samoozljeđivanje sa svojim varijantama (upute i namjera), seksualni sadržaj, seksualni sadržaj koji uključuje maloljetnike, nasilje i grafičko nasilje – uz ocjenu pouzdanosti između 0,0 i 1,0 za svaku od njih.
Ove ocjene važnije su od binarne odluke kada želiš kalibrirati svoju politiku. Profesionalna forum platforma možda će htjeti blokirati sadržaj pri 0,3 za uznemiravanje, dok bi usluga za fikciju mogla prihvatiti 0,7 za nasilje. Donja funkcija otkriva obje razine uvida: stvarno okinute kategorije i sirove ocjene za tvoje vlastite pragove.
def analyze_moderation(text: str) -> dict:
"""Detailed moderation analysis."""
moderation = client.moderations.create(
model="omni-moderation-latest",
input=text
)
result = moderation.results[0]
# Available categories
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,
}
# Confidence scores (0.0 to 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']}")
Potpuni pipeline moderacije
Moderacija korisničkih unosa
Omotajmo ovaj poziv u komponentu koju možeš ponovno koristiti. ContentModerator vraća eksplicitan par – prihvatljivo ili ne, s razlogom – umjesto sirovog objekta koji bi svaki pozivatelj morao ponovno tumačiti. Prevođenje kategorija u jasan jezik je bitno: to je rječnik koji će se pojaviti u tvom sučelju i zapisnicima, a mora biti razumljiv ljudskom timu za moderaciju koji preuzima kontrolu.
class ContentModerator:
"""Content moderator for applications."""
def __init__(self, custom_threshold: float = 0.5):
self.client = OpenAI()
self.threshold = custom_threshold
def moderate(self, text: str) -> tuple[bool, dict]:
"""Moderates text. Returns (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]:
"""Moderates a list of messages."""
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
# Usage
moderator = ContentModerator()
acceptable, details = moderator.moderate("Hello, how can I help you?")
print(f"Acceptable: {acceptable}")
print(f"Details: {details}")
Integracija u API pipeline
Moderacija okviruje poziv s obje strane. Filtriranje unosa izbjegava plaćanje generiranja za sadržaj koji bi ionako odbio; filtriranje izlaza štiti od slučajeva gdje model, vješto provociran, sam proizvede nešto neprihvatljivo. Primijeti razliku u rukovanju: za unos možeš korisniku reći što je otkriveno jer je on to autor; za izlaz poruka ostaje neodređena jer bi detaljiranje značilo opisivanje onoga što je model upravo proizveo.
def moderated_chatbot(user_input: str) -> str:
"""Chatbot with moderation of both inputs AND outputs."""
moderator = ContentModerator()
# 1. Moderate 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. Generate response
response = client.responses.create(
model="gpt-5.6-terra",
instructions="Respond in a professional and safe manner.",
input=user_input
)
# 3. Moderate 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?"))
Grupna moderacija
Ovaj dvostruki poziv dodaje kašnjenje, što je prihvatljivo u razgovoru, ali postaje prohibitive kada trebaš obraditi deset tisuća korisničkih recenzija uvezenih iz datoteke. Za učinkovitu moderaciju velikih volumena, proslijedi polje izravno: API obrađuje sve tekstove u jednom zahtjevu i vraća rezultate istim redoslijedom, što ti omogućuje ponovno povezivanje po indeksu.
def moderate_batch(texts: list[str]) -> list[dict]:
"""Moderates multiple texts in a single request."""
results = []
# The API accepts an array of inputs
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
# Usage
texts = [
"Hello, how are you?",
"Great product, I recommend it!",
"Customer service is excellent.",
]
results = moderate_batch(texts)
Bilježenje moderacije
Odluka o moderaciji utječe na korisnika i prije ili kasnije morat ćeš je opravdati – bilo korisniku koji osporava blokadu ili regulatoru. Stoga sustavno bilježi presudu, ID korisnika, ocjene i isječak teksta. Razina zapisa razlikuje dva slučaja: warning za označeni sadržaj, koji zaslužuje ljudski pregled, i info za ostalo, što napaja tvoju statistiku.
import json
import logging
from datetime import datetime
logger = logging.getLogger("moderation")
def moderate_with_log(text: str, user_id: str = "anonymous") -> bool:
"""Moderates and logs the result for auditing."""
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
# Usage
is_ok = moderate_with_log("Test message", user_id="user-123")
Još jedno upozorenje prije nego što prijeđemo dalje: moderacija klasificira sadržaj; ne razumije namjeru. Savršeno ljubazna poruka koja pokušava probiti sigurnost tvog asistenta proći će sve ove filtre bez ijednog označavanja. To je tema sljedeće lekcije.
Ključne točke
- API za moderaciju je besplatan – koristi ga sustavno
- Moderiraj i ulaze (korisnički sadržaj) I izlaze (odgovore modela)
- Model
omni-moderation-latestpokriva sve kategorije sadržaja - Bilježi sve odluke o moderaciji radi revizije
- Koristi grupnu obradu za učinkovitu moderaciju velikih volumena
- Moderacija nadopunjava sistemske upute; ne zamjenjuje ih