API Moderation firmy OpenAI
Na tej stronie
Zaktualizowano 3 listopada 2026 r. na podstawie przewodnika Moderation firmy OpenAI: dodano kategorię
illicit(orazillicit/violent), której brakowało w tabeli, wraz z kategoriami mającymi zastosowanie do obrazów. Źródło: Moderation.
Wbudowane narzędzie do moderacji
OpenAI udostępnia darmowe API Moderation, które analizuje tekst w celu wykrycia potencjalnie szkodliwych treści. Jest to pierwsza linia obrony, którą powinieneś zintegrować z każdą aplikacją wykorzystującą modele OpenAI, i nie ograniczasz się tylko do tego przypadku użycia: ponieważ API przyjmuje surowy tekst jako dane wejściowe, możesz go również użyć do filtrowania danych wejściowych przeznaczonych dla innych modeli. Fakt, że jest ono darmowe, zmienia sposób myślenia o tym problemie. Zwykłe kompromisy – czy moderować każde żądanie, czy tylko podejrzane? – tracą na znaczeniu, ponieważ jedynym pozostałym kosztem jest opóźnienie (latencja).
Co zwraca API
Podstawowe wywołanie mieści się w jednej linii; to odpowiedź wymaga uwagi. API zwraca trzy odrębne elementy: wartość logiczną flagged odzwierciedlającą decyzję OpenAI, listę faktycznie uruchomionych kategorii oraz, co najważniejsze, ciągłe wyniki (scores) dla każdej kategorii. To właśnie te wyniki robią różnicę w środowisku produkcyjnym, ponieważ pozwalają Ci samodzielnie zdecydować, gdzie wyznaczyć granicę, zamiast dziedziczyć próg zaprojektowany do ogólnego użytku.
from openai import OpenAI
client = OpenAI()
def moderate_content(text: str) -> dict:
"""Analizuje tekst za pomocą API Moderation firmy 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
},
}
# Testowanie z różnymi typami treści
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())}")
Trzy przykłady testowe nie są przypadkowe: pierwszy powinien przejść, drugi powinien zostać zablokowany, a trzeci – całkowicie legitne pytanie techniczne – pokazuje Ci, jak zachowuje się Twój potok (pipeline) w obliczu słownictwa związanego z bezpieczeństwem. To dokładnie ten rodzaj żądania, z którym zespół cyberbezpieczeństwa radzi sobie na co dzień.
Wykrywane kategorie
API klasyfikuje problematyczne treści wzdłuż kilku osi, z których każda odpowiada odrębnemu rodzajowi szkody.
| 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żda kategoria posiada również podkategorie (np. harassment/threatening, illicit/violent, violence/graphic) umożliwiające dokładniejsze filtrowanie. W przypadku modelu omni-moderation-latest tylko kategoria self-harm i jej warianty, sexual oraz violence (z violence/graphic) mają również zastosowanie do obrazów; pozostałe kategorie dotyczą wyłącznie tekstu. Ta ziarnistość uwalnia Cię od konieczności podejmowania grubych kompromisów: platforma moderująca forum może chcieć zablokować harassment/threatening, tolerując jednocześnie zwykłe harassment, co obejmuje wiele zwykłych sporów.
Gdy musisz przetwarzać duże wolumeny – na przykład retrospektywna analiza historii rozmowy – API przyjmuje listę i zwraca wynik dla każdego elementu, unikając wielokrotnych rund komunikacji sieciowej.
def moderate_batch(messages: list[str]) -> list[dict]:
"""Moderuje wiele wiadomości w jednym wywołaniu."""
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
Moderowanie obu końców potoku
Częstym błędem jest moderowanie tylko danych wejściowych. Opiera się to na fałszywej intuicji: jeśli przychodząca wiadomość jest akceptowalna, odpowiedź również będzie. Tymczasem model może wygenerować problematyczne treści na podstawie neutralnego żądania, zwłaszcza gdy opiera się na pobranych dokumentach, których treści nikt nie zweryfikował. Poniższa klasa stosuje zatem takie samo traktowanie w obu kierunkach, dodając niestandardowy próg, który zaostrza domyślną decyzję API.
class ModerationPipeline:
"""Potok moderacji danych wejściowych i wyjściowych dla aplikacji 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 wiadomość PRZED wysłaniem jej do 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 odpowiedź modelu PRZED wysłaniem jej do użytkownika."""
return self.moderate_input(response)
def process_message(self, user_message: str, system_prompt: str) -> str:
"""Pełny potok: moderacja wejścia, LLM, moderacja wyjścia."""
# Krok 1: moderacja danych wejściowych
input_blocked, details = self.moderate_input(user_message)
if input_blocked:
return "Your message cannot be processed. Please rephrase it."
# Krok 2: wywołanie 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: moderacja danych wyjściowych
output_blocked, _ = self.moderate_output(model_response)
if output_blocked:
return "The response was filtered for non-compliance."
return model_response
# Użycie
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)
Czego to API nie robi
Jego najważniejszym ograniczeniem, które jest jednocześnie najbardziej niezrozumianym, jest fakt, że nie wykrywa ono iniekcji promptów (prompt injection). Uprzejma wiadomość, która jest całkowicie nieszkodliwa z perspektywy treści, ale prosi model o zignorowanie jego instrukcji, przejdzie bez uruchamiania żadnej kategorii. Oczekiwanie, że ochroni ona przed manipulacją, jest jak instalacja czujki dymu w nadziei, że powstrzyma włamywaczy.
Fałszywe pozytywy to drugie ograniczenie, szczególnie dotkliwe w kontekstach bezpieczeństwa lub medycznych, gdzie opisywanie zagrożeń jest częścią pracy. Do każdego żądania dodawane jest dodatkowe wywołanie sieciowe, co ma znaczenie, gdy zależy Ci na odpowiedziach w czasie rzeczywistym. Wykrywanie pozostaje bardziej niezawodne w języku angielskim niż w innych językach, co jest ślepą plamą, o której atakujący wiedzą doskonale. Wreszcie, kategorie i progi ewoluują wraz z aktualizacjami: zestaw kalibracyjny sprzed sześciu miesięcy zasługuje na ponowną weryfikację.
Te ograniczenia dyktują sposób używania tego narzędzia. Moderuj w obu kierunkach, dostosowuj progi kategoria po kategorii, a nie globalnie, i systematycznie łącz to z innymi warstwami – wykrywaniem iniekcji, filtrowaniem logiki biznesowej – które szczegółowo opisują kolejne lekcje. Loguj wyniki, ponieważ obserwowanie własnych fałszywych pozytywów to sposób na naukę, gdzie przesunąć suwaki. I zaplanuj sytuację, w której API jest niedostępne: zdecyduj teraz, gdy panuje spokój, czy Twoja aplikacja powinna domyślnie blokować ruch, czy go przepuszczać, zamiast odkrywać to zachowanie podczas incydentu.
Kluczowe wnioski
- API Moderation jest darmowe, szybkie i proste do zintegrowania
- Wykrywa treści obraźliwe, ale nie iniekcje ani jailbreaki
- Potok wejście-model-wyjście musi być moderowany na obu końcach
- Domyślne progi rzadko pasują – dostosuj je do swojego kontekstu
- Jest to jedna z wielu warstw, nigdy jedyna linia obrony