OpenAI Moderation API
Na této stránce
Aktualizováno 3. listopadu 2026 na základě příručky Moderation od OpenAI: doplněna kategorie
illicit(aillicit/violent), která v tabulce chyběla, spolu s kategoriemi platnými pro obrázky. Zdroj: Moderation.
Vestavěný nástroj pro moderaci
OpenAI poskytuje bezplatné Moderation API, které analyzuje text a odhaluje potenciálně škodlivý obsah. Toto je první obranná linie, kterou byste měli integrovat do jakékoli aplikace využívající modely OpenAI, a nejste omezeni pouze na tento případ použití: protože API přijímá jako vstup surový text, můžete jej využít i k filtrování vstupů určených pro jiné modely. Fakt, že je služba zdarma, mění váš pohled na celý problém. Obvyklé kompromisy – moderovat každý požadavek, nebo jen ty podezřelé? – ztrácejí na váze, protože jedinou zbývající cenou je latence.
Co API vrací
Základní volání se vejde na jeden řádek; pozornost si však zasluhuje odpověď. API vrací tři odlišné věci: booleanovskou hodnotu flagged odrážející rozhodnutí OpenAI, seznam skutečně spuštěných kategorií a co je nejdůležitější, průběžná skóre pro každou kategorii. Právě tato skóre dělají v produkčním prostředí rozdíl, protože vám umožňují sami určit hranici, místo abyste dědili práh navržený pro obecné použití.
from openai import OpenAI
client = OpenAI()
def moderate_content(text: str) -> dict:
"""Analyzuje text prostřednictvím Moderation API od OpenAI."""
response = client.moderations.create(input=text)
result = response.results[0]
return {
"blocked": result.flagged,
"categories": {
cat: flagged
for cat, flagged in result.categories.__dict__.items()
if flagged
},
"scores": {
cat: round(score, 4)
for cat, score in result.category_scores.__dict__.items()
if score > 0.01
},
}
# Test s různými typy obsahu
examples = [
"How do I bake a chocolate cake?",
"I will kill you if you don't answer me",
"Explain how AES encryption works",
]
for text in examples:
result = moderate_content(text)
status = "BLOCKED" if result["blocked"] else "OK"
print(f"{status} : {text[:50]}...")
if result["categories"]:
print(f" Categories : {list(result['categories'].keys())}")
Tři testovací příklady nejsou náhodné: první by měl projít, druhý by měl být zablokován a třetí – zcela legitimní technická otázka – vám ukáže, jak se vaše pipeline chová při setkání s bezpečnostní terminologií. Přesně tento typ požadavku řeší týmy kybernetické bezpečnosti denně.
Detekované kategorie
API klasifikuje problematický obsah podél několika os, z nichž každá odpovídá odlišnému typu újmy.
| Category | Description |
|---|---|
| harassment | Harassment, threats, intimidation |
| hate | Hate speech based on identity |
| illicit | Advice or instructions for committing illicit acts |
| self-harm | Self-harm, suicide |
| sexual | Explicit sexual content |
| violence | Graphic violence, threats |
Každá kategorie má také podkategorie (např. harassment/threatening, illicit/violent, violence/graphic) pro jemnější filtrování. U modelu omni-moderation-latest se pouze self-harm a jeho varianty, sexual a violence (s violence/graphic) vztahují také na obrázky; ostatní kategorie platí pouze pro text. Tato granularita vás zbavuje nutnosti dělat hrubé kompromisy: platforma pro moderaci fóra může chtít blokovat harassment/threatening, zatímco toleruje prosté harassment, což pokrývá mnoho běžných sporů.
Když potřebujete zpracovávat velké objemy – například retrospektivní analýzu historie konverzace – API přijímá seznam a vrací výsledek pro každý prvek, čímž se vyhnete více síťovým往返 (round trips).
def moderate_batch(messages: list[str]) -> list[dict]:
"""Moderuje více zpráv v jediném volání."""
response = client.moderations.create(input=messages)
results = []
for i, result in enumerate(response.results):
results.append({
"index": i,
"text": messages[i][:50],
"blocked": result.flagged,
"max_score": max(
score
for score in result.category_scores.__dict__.values()
),
})
return results
Moderace na obou koncích pipeline
Častou chybou je moderovat pouze vstupy. To vychází z mylné intuice: pokud je příchozí zpráva přijatelná, bude v pořádku i odpověď. Model však může vygenerovat problematický obsah i na základě neutrálního požadavku, zejména když spoléhá na načtené dokumenty, jejichž obsah nikdo neověřil. Níže uvedená třída proto aplikuje stejné zacházení oběma směry a přidává vlastní práh, který zpřísňuje výchozí rozhodnutí API.
class ModerationPipeline:
"""Pipeline pro moderaci vstupů i výstupů v aplikaci s LLM."""
def __init__(self, custom_threshold: float = 0.7):
self.client = OpenAI()
self.threshold = custom_threshold
def moderate_input(self, message: str) -> tuple[bool, dict]:
"""Moderuje zprávu PŘED odesláním modelu."""
result = self.client.moderations.create(input=message).results[0]
scores = result.category_scores.__dict__
high_categories = {
cat: score for cat, score in scores.items() if score > self.threshold
}
blocked = result.flagged or bool(high_categories)
return blocked, {"flagged_api": result.flagged, "custom_categories": high_categories}
def moderate_output(self, response: str) -> tuple[bool, dict]:
"""Moderuje odpověď modelu PŘED odesláním uživateli."""
return self.moderate_input(response)
def process_message(self, user_message: str, system_prompt: str) -> str:
"""Celá pipeline: moderace vstupu, LLM, moderace výstupu."""
# Krok 1: moderace vstupu
input_blocked, details = self.moderate_input(user_message)
if input_blocked:
return "Your message cannot be processed. Please rephrase it."
# Krok 2: volání modelu
response = self.client.chat.completions.create(
model="gpt-5.6-sol",
messages=[
{"role": "system", "content": system_prompt},
{"role": "user", "content": user_message},
],
)
model_response = response.choices[0].message.content
# Krok 3: moderace výstupu
output_blocked, _ = self.moderate_output(model_response)
if output_blocked:
return "The response was filtered for non-compliance."
return model_response
# Použití
pipeline = ModerationPipeline(custom_threshold=0.5)
response = pipeline.process_message(
"How do I protect my application against SQL injections?",
"You are an expert in defensive cybersecurity."
)
print(response)
Co toto API nedělá
Jeho nejdůležitější limitace je zároveň tou nejčastěji nepochopenou: nedetekuje prompt injection. Zdvořilá zpráva, která je z hlediska obsahu zcela neškodná, ale žádá model, aby ignoroval své instrukce, projde bez spuštění jakékoli kategorie. Očekávat, že vás ochrání před manipulací, je jako instalovat detektor kouře a doufat, že zastaví vloupání.
Falešně pozitivní výsledky jsou druhou limitací, obzvláště citlivou v bezpečnostním nebo lékařském kontextu, kde je popis hrozby součástí práce. Ke každému požadavku se přidává další síťové volání, což záleží, pokud cílíte na odpovědi v reálném čase. Detekce zůstává spolehlivější v angličtině než v jiných jazycích – to je slepé místo, které útočníci dokonale znají. Nakonec se kategorie a prahy vyvíjejí s aktualizacemi: kalibrační sada stará šest měsíců si zaslouží opětovné ověření.
Tyto limity diktují, jak nástroj používat. Moderujte oběma směry, upravujte prahy kategorii po kategorii místo globálně a systematicky jej kombinujte s dalšími vrstvami – detekcí injection, filtrováním business logiky – které detailně rozebírají následující lekce. Logujte výsledky, protože pozorování vlastních falešně pozitivních výsledků je způsob, jak se naučit, kam posunout jezdce. A naplánujte si případ, kdy API není dostupné: rozhodněte se nyní, zatímco je klid, zda má vaše aplikace ve výchozím nastavení blokovat, nebo propouštět provoz, místo abyste toto chování objevili až během incidentu.
Klíčové poznatky
- Moderation API je zdarma, rychlé a snadno se integruje
- Detekuje urážlivý obsah, ale nikoli injection nebo jailbreaky
- Pipeline vstup-model-výstup musí být moderována na obou koncích
- Výchozí prahy zřídka sedí – přizpůsobte je svému kontextu
- Je to jedna z mnoha vrstev, nikdy jediná obranná linie