Moderovanie obsahu pomocou API
Na tejto strane
Aktualizované 3. novembra 2026 na základe príručky Moderation od OpenAI: kategórie
illicitaillicit/violentpre modelomni-moderation-latestchýbali v zozname a kóde. Zdroj: Moderation.
Moderovanie obsahu pomocou API
API pre moderovanie od OpenAI automaticky deteguje nevhodný obsah. Je to bezplatný a nevyhnutný nástroj pre každú aplikáciu, ktorá prijíma obsah generovaný používateľmi. Predchádzajúca lekcia ti ukázala, ako písať vlastné filtre; táto ti poskytuje trénovaný klasifikátor, ktorý odhalí to, čo pravidelné výrazy nikdy nezachytia – zastreté vyhrážky, nepriame urážky a implicitné formulácie.
API pre moderovanie
Volanie je zámerne minimalistické: jeden model, jeden text a výsledok, ktorý sa redukuje na boolean hodnotu. Pole flagged odpovedá na binárnu otázku: „Porušuje tento obsah zásady používania?“, zatiaľ čo categories špecifikuje, ktoré konkrétne. Keďže je tento koncový bod bezplatný, neexistuje ekonomický dôvod ho vynechať, ani pri vysokých objemoch.
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, ...)
Kategórie moderovania
Za boolean hodnotou sa skrýva jemne granulóvaná mriežka. Model vráti rozhodnutie pre každú kategóriu – obťažovanie, vyhrážky obťažovaním, nenávisť, vyhrážky nenávisťou, pokyny k nedovoleným činom (s násilím alebo bez neho), sebapoškodzovanie s jeho variantmi (pokyny a úmysel), sexuálny obsah, sexuálny obsah zahŕňajúci maloletých, násilie a grafické násilie – spolu s hodnotou spoľahlivosti medzi 0,0 a 1,0 pre každú z nich.
Tieto skóre sú dôležitejšie než binárne rozhodnutie, keď chceš kalibrovať svoju politiku. Profesionálna fórová platforma môže chcieť blokovať pri hodnote 0,3 pre obťažovanie, zatiaľ čo služba zameraná na beletriu môže akceptovať 0,7 pre násilie. Nižšie uvedená funkcia odhaľuje obe úrovne vhľadu: skutočne spustené kategórie a surové skóre pre tvoje vlastné prahové hodnoty.
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']}")
Kompletný pipeline moderovania
Moderovanie vstupov používateľov
Zabaľme toto volanie do opakovane použiteľného komponentu. ContentModerator vracia explicitný pár – prijateľné alebo nie, s dôvodom – namiesto surového objektu, ktorý by musel každý volajúci znovu interpretovať. Preklad kategórií do jasného jazyka je dôležitý: toto je slovník, ktorý sa objaví vo tvojom rozhraní a logoch, a musí byť zrozumiteľný pre tím ľudských moderátorov, ktorý preberá 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}")
Integrácia do pipeline API
Moderovanie rámkuje volanie na oboch stranách. Filtrovanie vstupu ti zabráni platiť za generovanie obsahu, ktorý by si aj tak zamietol; filtrovanie výstupu chráni pred prípadmi, keď model, šikovne provokovaný, sám vyprodukuje niečo neprijateľné. Všimni si rozdiel v zaobchádzaní: pri vstupe môžeš používateľovi povedať, čo bolo detegované, keďže je autorom obsahu; pri výstupe zostáva správa vágna, pretože jej detailné opisovanie by znamenalo popisovať to, čo model práve vyprodukoval.
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?"))
Dávkové moderovanie
Toto dvojité volanie pridáva latenciu, čo je v konverzácii prijateľné, ale stáva sa neúnosným, keď potrebuješ spracovať desaťtisíc recenzií zákazníkov importovaných zo súboru. Na efektívne moderovanie veľkých objemov odovzdaj priamo pole: API spracuje všetky texty v jednej požiadavke a vráti výsledky v rovnakom poradí, čo ti umožní ich znovu priradiť podľa indexu.
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)
Logovanie moderovania
Rozhodnutie o moderovaní ovplyvňuje používateľa a skôr či neskôr ho budeš musieť odôvodniť – či už zákazníkovi, ktorý napadne blokovanie, alebo regulátorovi. Preto systematicky loguj verdikt, ID používateľa, skóre a úryvok textu. Úroveň logu rozlišuje dva prípady: warning pre označený obsah, ktorý si zaslúži ľudskú kontrolu, a info pre zvyšok, ktorý slúži na tvoje štatistiky.
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")
Ešte jedno posledné varovanie predtým, než pôjdeme ďalej: moderovanie klasifikuje obsah; nerozumie úmyslu. Dokonale zdvorilá správa, ktorá sa pokúša obísť tvojho asistenta (jailbreak), prejde všetkými týmito filtrami bez toho, aby bola jediný raz označená. To je predmetom nasledujúcej lekcie.
Kľúčové poznatky
- API pre moderovanie je bezplatné – používaj ho systematicky
- Moderuj zarówno vstupy (obsah od používateľov), ako aj výstupy (odpovede modelu)
- Model
omni-moderation-latestpokrýva všetky kategórie obsahu - Loguj všetky rozhodnutia o moderovaní pre účely auditu
- Používaj dávkové spracovanie na efektívne moderovanie veľkých objemov
- Moderovanie dopĺňa systémové inštrukcie; nenahrádza ich