Moderování obsahu pomocí API
Na této stránce
Aktualizováno 3. listopadu 2026 na základě příručky Moderation od OpenAI: kategorie
illicitaillicit/violentpro modelomni-moderation-latestchyběly v seznamu a kódu. Zdroj: Moderation.
Moderování obsahu pomocí API
API pro moderování od OpenAI automaticky detekuje nevhodný obsah. Je to bezplatný a nezbytný nástroj pro jakoukoli aplikaci, která přijímá obsah generovaný uživateli. Předchozí lekce ti ukázala, jak psát vlastní filtry; tato ti poskytuje trénovaný klasifikátor, který odhalí to, co regulární výrazy nikdy nezachytí – zastřené hrozby, nepřímé urážky a implicitní formulace.
API pro moderování
Volání je záměrně minimalistické: jeden model, jeden text a výsledek, který se redukuje na boolean hodnotu. Pole flagged odpovídá na binární otázku „Porušuje tento obsah zásady používání?“, zatímco categories upřesňuje, které konkrétně. Protože je tento koncový bod zdarma, neexistuje žádný ekonomický důvod jej vynechávat, ani při vysokých objemech.
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, ...)
Kategorie moderování
Za boolean hodnotou se skrývá jemně zrnitá mřížka. Model vrací rozhodnutí pro každou kategorii – obtěžování, vyhrožující obtěžování, nenávist, vyhrožující nenávist, pokyny k nedovoleným činům (s násilím i bez něj), sebepoškozování s jeho variantami (pokyny a záměr), sexuální obsah, sexuální obsah zahrnující nezletilé, násilí a grafické násilí – spolu s hodnotou spolehlivosti mezi 0,0 a 1,0 pro každou z nich.
Tyto hodnoty jsou důležitější než binární rozhodnutí, když chceš kalibrovat svou politiku. Profesionální fórová platforma může chtít blokovat při hodnotě 0,3 pro obtěžování, zatímco služba pro beletrii může akceptovat 0,7 pro násilí. Níže uvedená funkce odhaluje obě úrovně vhledu: skutečně spuštěné kategorie a surová skóre pro tvé vlastní prahy.
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 moderování
Moderování uživatelských vstupů
Zabalme toto volání do znovu použitelné komponenty. ContentModerator vrací explicitní dvojici – přijatelné či nikoli, s důvodem – namísto surového objektu, který by musel každý volající znovu interpretovat. Překlad kategorií do srozumitelného jazyka matters: toto je slovník, který se objeví ve tvém rozhraní a logách, a musí být srozumitelný pro lidský tým moderátorů, který převezme 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}")
Integrace do pipeline API
Moderování rámuje volání na obou stranách. Filtrování vstupu zabraňuje placení za generování obsahu, který bys stejně zamítl; filtrování výstupu chrání před případy, kdy model, šikovně provocován, sám vyprodukuje něco nepřijatelného. Všimni si rozdílu v zacházení: u vstupu můžeš uživateli sdělit, co bylo detekováno, protože to on autor; u výstupu zůstává zpráva vágní, protože její detailní popis by znamenal popisovat to, co model právě 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é moderování
Toto dvojí volání přidává latenci, což je v konverzaci přijatelné, ale stává se neúnosným, když potřebuješ zpracovat deset tisíc recenzí zákazníků importovaných ze souboru. Pro efektivní moderování velkých objemů předej pole přímo: API zpracuje všechny texty v jediném požadavku a vrátí výsledky ve stejném pořadí, což ti umožní je znovu přiřadit podle 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)
Logování moderování
Rozhodnutí o moderování ovlivňuje uživatele a dříve či později budeš muset toto rozhodnutí obhájit – ať už zákazníkovi, který napadne blokování, nebo regulátorovi. Proto systematicky loguj verdikt, ID uživatele, skóre a úryvek textu. Úroveň logu rozlišuje dva případy: warning pro označený obsah, který si zaslouží lidskou revizi, a info pro zbytek, který napájí tvé statistiky.
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")
Ještě jedno varování, než pokračujeme dál: moderování klasifikuje obsah; nerozumí záměru. Zcela zdvořilá zpráva, která se pokouší obejít tvého asistenta (jailbreak), projde všemi těmito filtry, aniž by byla jedinkrát označena. To je tématem příští lekce.
Klíčové poznatky
- API pro moderování je zdarma – používej jej systematicky
- Moderuj jak vstupy (obsah od uživatelů), tak výstupy (odpovědi modelu)
- Model
omni-moderation-latestpokrývá všechny kategorie obsahu - Loguj všechna rozhodnutí o moderování pro účely auditu
- Používej dávkové zpracování pro efektivní moderování velkých objemů
- Moderování doplňuje systémové instrukce; nenahrazuje je