Moderacja treści za pomocą API
Na tej stronie
Zaktualizowano 3 listopada 2026 r. na podstawie przewodnika Moderation od OpenAI: kategorie
illicitiillicit/violentdla modeluomni-moderation-latestbrakowało na liście i w kodzie. Źródło: Moderation.
Moderacja treści za pomocą API
API Moderation od OpenAI automatycznie wykrywa niewłaściwe treści. Jest to darmowe, niezbędne narzędzie dla każdej aplikacji przyjmującej treści generowane przez użytkowników. Poprzednia lekcja pokazała Ci, jak pisać własne filtry; ta dostarcza wytrenowany klasyfikator, który wyłapuje to, czego wyrażenia regularne nigdy nie wykryją – ukryte groźby, pośrednie obrazy i niejasne sformułowania.
API Moderation
Wywołanie jest celowo minimalistyczne: jeden model, jeden tekst i wynik sprowadzający się do wartości logicznej. Pole flagged odpowiada na binarne pytanie: „Czy ta treść narusza zasady użytkowania?“, podczas gdy categories szczegółowo wskazuje, które z nich. Ponieważ ten punkt końcowy jest darmowy, nie ma ekonomicznego powodu, aby go pomijać, nawet przy dużych wolumenach.
from openai import OpenAI
client = OpenAI()
# API Moderation jest DARMOWE
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}")
# Wynik:
# Content flagged: False
# Categories: Categories(harassment=False, hate=False, ...)
Kategorie moderacji
Za wartością logiczną kryje się szczegółowa siatka kategorii. Model zwraca decyzję dla każdej z nich – nękanie, groźby nękania, mowa nienawiści, groźby nienawiści, instrukcje dotyczące czynów niedozwolonych (z przemocą lub bez), samookaleczenia z wariantami (instrukcje i zamiar), treści seksualne, treści seksualne z udziałem nieletnich, przemoc oraz przemoc graficzna – wraz z wynikiem pewności od 0,0 do 1,0 dla każdej z nich.
Te wyniki są ważniejsze niż decyzja binarna, gdy chcesz skalibrować swoją politykę. Profesjonalna platforma forum może chcieć blokować treści przy wyniku 0,3 dla nękania, podczas gdy serwis fiction może zaakceptować 0,7 dla przemocy. Poniższa funkcja udostępnia oba poziomy wglądu: faktycznie uruchomione kategorie oraz surowe wyniki dla Twoich własnych progów.
def analyze_moderation(text: str) -> dict:
"""Szczegółowa analiza moderacji."""
moderation = client.moderations.create(
model="omni-moderation-latest",
input=text
)
result = moderation.results[0]
# Dostępne kategorie
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,
}
# Wyniki pewności (od 0.0 do 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']}")
Kompleksowy proces moderacji
Moderacja danych wejściowych od użytkowników
Oprawmy to wywołanie w wielokrotnego użytku komponent. ContentModerator zwraca wyraźną parę – akceptowalne lub nie, wraz z powodem – zamiast surowego obiektu, który każdy wywołujący musiałby reinterpretować. Tłumaczenie kategorii na jasny język ma znaczenie: to słownictwo pojawi się w Twoim interfejsie i logach i musi być zrozumiałe dla zespołu ludzkiej moderacji, który przejmie sprawę.
class ContentModerator:
"""Moderator treści dla aplikacji."""
def __init__(self, custom_threshold: float = 0.5):
self.client = OpenAI()
self.threshold = custom_threshold
def moderate(self, text: str) -> tuple[bool, dict]:
"""Moderuje tekst. Zwraca (czy_akceptowalne, szczegóły)."""
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("nękanie")
if result.categories.hate:
categories.append("mowa nienawiści")
if result.categories.sexual:
categories.append("treści seksualne")
if result.categories.violence:
categories.append("przemoc")
if result.categories.self_harm:
categories.append("samookaleczenie")
return False, {
"reason": "Wykryto niewłaściwą treść",
"categories": categories
}
return True, {"reason": "Treść akceptowalna"}
def moderate_conversation(self, messages: list[str]) -> list[dict]:
"""Moderuje listę wiadomości."""
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
# Użycie
moderator = ContentModerator()
acceptable, details = moderator.moderate("Hello, how can I help you?")
print(f"Acceptable: {acceptable}")
print(f"Details: {details}")
Integracja z potokiem API
Moderacja otacza wywołanie z obu stron. Filtrowanie danych wejściowych pozwala uniknąć płacenia za generowanie treści, które i tak byś odrzucił; filtrowanie danych wyjściowych chroni przed przypadkami, gdy model, umiejętnie sprowokowany, sam wygeneruje coś niedopuszczalnego. Zwróć uwagę na różnicę w obsłudze: w przypadku danych wejściowych możesz powiedzieć użytkownikowi, co wykryto, ponieważ to on jest autorem; w przypadku danych wyjściowych wiadomość pozostaje ogólna, ponieważ szczegółowe opisanie jej oznaczałoby powtórzenie tego, co właśnie wygenerował model.
def moderated_chatbot(user_input: str) -> str:
"""Chatbot z moderacją zarówno danych wejściowych, jak i wyjściowych."""
moderator = ContentModerator()
# 1. Moderacja danych wejściowych
input_ok, input_details = moderator.moderate(user_input)
if not input_ok:
return (f"Twoja wiadomość została zablokowana: "
f"{', '.join(input_details['categories'])}")
# 2. Generowanie odpowiedzi
response = client.responses.create(
model="gpt-5.6-terra",
instructions="Respond in a professional and safe manner.",
input=user_input
)
# 3. Moderacja danych wyjściowych
output_ok, output_details = moderator.moderate(response.output_text)
if not output_ok:
return "Nie mogę udzielić takiej odpowiedzi."
return response.output_text
# Test
print(moderated_chatbot("What is the capital of France?"))
Moderacja wsadowa
To podwójne wywołanie dodaje opóźnienie, co jest akceptowalne w rozmowie, ale staje się prohibicyjne, gdy musisz przetworzyć dziesięć tysięcy opinii klientów zaimportowanych z pliku. Aby skutecznie moderować duże wolumeny, przekaż tablicę bezpośrednio: API przetwarza wszystkie teksty w jednym żądaniu i zwraca wyniki w tej samej kolejności, co pozwala na ich ponowne powiązanie według indeksu.
def moderate_batch(texts: list[str]) -> list[dict]:
"""Moderuje wiele tekstów w jednym żądaniu."""
results = []
# API akceptuje tablicę danych wejściowych
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
# Użycie
texts = [
"Hello, how are you?",
"Great product, I recommend it!",
"Customer service is excellent.",
]
results = moderate_batch(texts)
Logowanie moderacji
Decyzja moderacyjna wpływa na użytkownika i prędzej czy później będziesz musiał ją uzasadnić – czy to klientowi kwestionującemu blokadę, czy regulatorowi. Dlatego systematycznie loguj werdykt, ID użytkownika, wyniki i fragment tekstu. Poziom logowania rozróżnia dwa przypadki: warning dla treści oznaczonych flagą, które wymagają przeglądu przez człowieka, oraz info dla pozostałych, które zasilają Twoje statystyki.
import json
import logging
from datetime import datetime
logger = logging.getLogger("moderation")
def moderate_with_log(text: str, user_id: str = "anonymous") -> bool:
"""Moderuje i loguje wynik do celów audytowych."""
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
# Użycie
is_ok = moderate_with_log("Test message", user_id="user-123")
Jeszcze jedno ostrzeżenie przed przejściem dalej: moderacja klasyfikuje treści, ale nie rozumie intencji. Idealnie grzeczna wiadomość próbująca złamać zabezpieczenia Twojego asystenta przejdzie przez wszystkie te filtry bez ani jednego oznaczenia. To będzie temat następnej lekcji.
Kluczowe wnioski
- API Moderation jest darmowe – używaj go systematycznie
- Moderuj zarówno dane wejściowe (treści użytkowników), jak i wyjściowe (odpowiedzi modelu)
- Model
omni-moderation-latestobejmuje wszystkie kategorie treści - Loguj wszystkie decyzje moderacyjne do celów audytowych
- Używaj przetwarzania wsadowego, aby skutecznie moderować duże wolumeny
- Moderacja uzupełnia instrukcje systemowe, ale ich nie zastępuje