OpenAI Moderation API
Na tejto strane
Aktualizované 3. novembra 2026 na základe príručky Moderation od OpenAI: pridaná kategória
illicit(aillicit/violent), ktorá v tabuľke chýbala, spolu s kategóriami platnými pre obrázky. Zdroj: Moderation.
Vstavaný nástroj na moderovanie
OpenAI poskytuje bezplatné Moderation API, ktoré analyzuje text a odhaľuje potenciálne škodlivý obsah. Toto je prvá línia obrany, ktorú by ste mali integrovať do každej aplikácie využívajúcej modely OpenAI, a nie ste obmedzení len na tento prípad použitia: keďže API prijíma ako vstup surový text, môžete ho využiť aj na filtrovanie vstupov určených pre iné modely. Fakt, že je služba bezplatná, mení váš pohľad na celý problém. Obvyklé kompromisy – či moderovať každú požiadavku, alebo len podozrivé – strácajú na váhe, keďže jedinými zostávajúcimi nákladmi je latencia.
Čo API vracia
Základné volanie sa zmestí do jedného riadku; pozornosť si však vyžaduje odpoveď. API vracia tri odlišné veci: boolovskú hodnotu flagged反映ujúcu rozhodnutie OpenAI, zoznam skutočne spustených kategórií a čo je najdôležitejšie, priebežné skóre pre každú kategóriu. Práve tieto skóre robia v produkcii rozdiel, pretože vám umožňujú sami rozhodnúť, kde nastavíte hranicu, namiesto toho, aby ste dedili prahovú hodnotu určenú pre všeobecné použitie.
from openai import OpenAI
client = OpenAI()
def moderate_content(text: str) -> dict:
"""Analyzuje text prostredníctvom 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ôznymi typmi 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())}")
Tri testovacie príklady nie sú náhodné: prvý by mal prejsť, druhý by mal byť zablokovaný a tretí – úplne legitímna technická otázka – vám ukáže, ako sa váš pipeline správa, keď narazí na bezpečnostnú terminológiu. Presne toto je typ požiadavky, ktorú bezpečnostný tím rieši denne.
Detegované kategórie
API klasifikuje problematický obsah podľa viacerých osí, pričom každá zodpovedá odlišnému typu ujmy.
| 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á kategória má aj podkategórie (napr. harassment/threatening, illicit/violent, violence/graphic) pre jemnejšie filtrovanie. Pri modeli omni-moderation-latest sa kategórie self-harm a jej varianty, sexual a violence (s violence/graphic) vzťahujú aj na obrázky; ostatné kategórie platia len pre text. Táto granularita vás zbavuje potreby robiť hrubé kompromisy: platforma na moderovanie fóra môže chcieť blokovať harassment/threatening, zatiaľ čo toleruje jednoduché harassment, ktoré pokrýva mnoho bežných sporov.
Keď potrebujete spracovať veľké objemy – napríklad retrospektívnu analýzu histórie konverzácie – API prijíma zoznam a vráti výsledok pre každý prvok, čím sa vyhnete viacerým sieťovým požiadavkám tam a späť.
def moderate_batch(messages: list[str]) -> list[dict]:
"""Moderuje viacero správ v rámci jedného volania."""
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
Moderovanie oboch koncov pipeline
Častou chybou je moderovanie iba vstupov. Spolieha sa na falošnú intuíciu: ak je prichádzajúca správa prijateľná, bude aj odpoveď. Model však môže vygenerovať problematický obsah aj na neutrálnu požiadavku, najmä ak sa spolieha na načítané dokumenty, ktorých obsah nikto neoveril. Nižšie uvedená trieda preto aplikuje rovnaké zaobchádzanie v oboch smeroch a pridáva vlastný prah, ktorý sprísňuje predvolené rozhodnutie API.
class ModerationPipeline:
"""Pipeline na moderovanie vstupov aj výstupov pre LLM aplikáciu."""
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 správu PRED odoslaní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 odpoveď modelu PRED odoslaním používateľovi."""
return self.moderate_input(response)
def process_message(self, user_message: str, system_prompt: str) -> str:
"""Kompletný pipeline: moderovanie vstupu, LLM, moderovanie výstupu."""
# Krok 1: moderovanie vstupu
input_blocked, details = self.moderate_input(user_message)
if input_blocked:
return "Your message cannot be processed. Please rephrase it."
# Krok 2: volanie 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: moderovanie výstupu
output_blocked, _ = self.moderate_output(model_response)
if output_blocked:
return "The response was filtered for non-compliance."
return model_response
# Použitie
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)
Čo toto API nerobí
Jeho najdôležitejším obmedzením, ktoré je zároveň najčastejšie nepochopené, je fakt, že neodhaľuje prompt injection. Zdvorilá správa, ktorá je z hľadiska obsahu úplne neškodná, ale žiada model, aby ignoroval svoje inštrukcie, prejde bez spustenia akejkoľvek kategórie. Očakávať, že vás ochráni pred manipuláciou, je ako inštalovať detektor dymu a dúfať, že zastaví vlámanie.
Falošne pozitívne výsledky sú druhým obmedzením, čo je obzvlášť citlivé v bezpečnostnom alebo zdravotníckom kontexte, kde je opis hrozby súčasťou práce. Ku každej požiadavke sa pridáva ďalšie sieťové volanie, čo záleží, ak cielite na odpovede v reálnom čase. Detekcia zostáva spoľahlivejšia v angličtine než v iných jazykoch, čo je slepá miesta, ktorú útočníci dokonale poznajú. Nakoniec, kategórie a prahové hodnoty sa s aktualizáciami vyvíjajú: kalibračná sada stará šesť mesiacov si zaslúži opätovné overenie.
Tieto limity diktuju, ako nástroj používať. Moderujte v oboch smeroch, upravujte prahové hodnoty kategóriu po kategórii namiesto globálneho nastavenia a systematicky ho kombinujte s ďalšími vrstvami – detekciou injection, filtrovaním business logiky –, ktoré detailne rozoberajú nasledujúce lekcie. Logujte výsledky, pretože pozorovanie vlastných falošne pozitívnych výsledkov je spôsob, ako sa naučíte, kam posunúť posuvníky. A naplánujte si prípad, keď API nebude dostupné: rozhodnite sa teraz, keď je pokoj, či má vaša aplikácia v predvolenom nastavení blokovať, alebo pustiť prevádzku ďalej, namiesto toho, aby ste toto správanie objavili až počas incidentu.
Kľúčové poznatky
- Moderation API je bezplatné, rýchle a jednoduché na integráciu
- Odhaľuje urážlivý obsah, ale nie injectiony alebo jailbreaky
- Pipeline vstup-model-výstup musí byť moderovaný na oboch koncoch
- Predvolené prahové hodnoty zriedka sedia – prispôsobte ich svojmu kontextu
- Je to jedna z viacerých vrstiev, nikdy nie jediná línia obrany