Content-Moderation über die API
Auf dieser Seite
Aktualisiert am 3. November 2026 basierend auf OpenAIs Moderation-Guide: Die Kategorien
illicitundillicit/violentfür das Modellomni-moderation-latestfehlten in der Liste und im Code. Quelle: Moderation.
Content-Moderation über die API
Die Moderations-API von OpenAI erkennt automatisch unangemessene Inhalte. Es handelt sich um ein kostenloses, essenzielles Werkzeug für jede Anwendung, die nutzergenerierte Inhalte akzeptiert. Die vorherige Lektion zeigte Ihnen, wie Sie benutzerdefinierte Filter schreiben; diese Lektion stellt Ihnen einen trainierten Klassifikator zur Verfügung, der Dinge erkennt, die reguläre Ausdrücke niemals fangen würden: verschleierte Drohungen, indirekte Beleidigungen und implizite Formulierungen.
Die Moderations-API
Der Aufruf ist absichtlich minimal: ein Modell, ein Text und ein Ergebnis, das sich auf einen booleschen Wert reduziert. Das Feld flagged beantwortet die binäre Frage: „Verstößt dieser Inhalt gegen die Nutzungsrichtlinien?“, während categories die spezifischen Kategorien auflistet. Da dieser Endpunkt kostenlos ist, gibt es aus wirtschaftlicher Sicht keinen Grund, ihn auch bei hohen Volumina zu überspringen.
from openai import OpenAI
client = OpenAI()
# Die Moderations-API ist KOSTENLOS
moderation = client.moderations.create(
model="omni-moderation-latest",
input="Hallo, wie geht es Ihnen?"
)
result = moderation.results[0]
print(f"Inhalt markiert: {result.flagged}")
print(f"Kategorien: {result.categories}")
# Ergebnis:
# Inhalt markiert: False
# Kategorien: Categories(harassment=False, hate=False, ...)
Moderationskategorien
Hinter dem booleschen Wert verbirgt sich ein feingliedriges Raster. Das Modell gibt pro Kategorie eine Entscheidung ab – Belästigung, drohende Belästigung, Hass, drohender Hass, Anleitungen für illegale Handlungen (mit oder ohne Gewalt), Selbstgefährdung mit ihren Varianten (Anleitungen und Absicht), sexuelle Inhalte, sexuelle Inhalte mit Minderjährigen, Gewalt und grafische Gewalt – jeweils mit einem Vertrauensscore zwischen 0,0 und 1,0.
Diese Scores sind bei der Kalibrierung Ihrer Richtlinien wichtiger als die binäre Entscheidung. Eine professionelle Forenplattform könnte beispielsweise bei 0,3 für Belästigung blockieren, während ein Fiktionsservice bei 0,7 für Gewalt akzeptabel sein könnte. Die folgende Funktion macht beide Ebenen der Einsicht zugänglich: die tatsächlich ausgelösten Kategorien und die rohen Scores für Ihre eigenen Schwellenwerte.
def analyze_moderation(text: str) -> dict:
"""Detaillierte Moderationsanalyse."""
moderation = client.moderations.create(
model="omni-moderation-latest",
input=text
)
result = moderation.results[0]
# Verfügbare Kategorien
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,
}
# Vertrauensscores (0,0 bis 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("Hallo alle zusammen!")
print(f"Markiert: {result['flagged']}")
print(f"Scores: {result['main_scores']}")
Komplettierender Moderations-Pipeline
Moderation von Benutzereingaben
Verpacken wir diesen Aufruf in eine wiederverwendbare Komponente. ContentModerator gibt ein explizites Paar zurück – akzeptabel oder nicht, mit dem Grund – anstatt eines rohen Objekts, das jeder Aufrufer neu interpretieren müsste. Die Übersetzung von Kategorien in klare Sprache ist wichtig: Dies ist das Vokabular, das in Ihrer Schnittstelle und Ihren Protokollen erscheint, und es muss vom menschlichen Moderationsteam verstanden werden, das die Arbeit übernimmt.
class ContentModerator:
"""Content-Moderator für Anwendungen."""
def __init__(self, custom_threshold: float = 0.5):
self.client = OpenAI()
self.threshold = custom_threshold
def moderate(self, text: str) -> tuple[bool, dict]:
"""Moderiert Text. Gibt (ist_akzeptabel, Details) zurück."""
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("Belästigung")
if result.categories.hate:
categories.append("Hassrede")
if result.categories.sexual:
categories.append("sexuelle Inhalte")
if result.categories.violence:
categories.append("Gewalt")
if result.categories.self_harm:
categories.append("Selbstgefährdung")
return False, {
"reason": "Unangemessene Inhalte erkannt",
"categories": categories
}
return True, {"reason": "Inhalt akzeptabel"}
def moderate_conversation(self, messages: list[str]) -> list[dict]:
"""Moderiert eine Liste von Nachrichten."""
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
# Nutzung
moderator = ContentModerator()
acceptable, details = moderator.moderate("Hallo, wie kann ich Ihnen helfen?")
print(f"Akzeptabel: {acceptable}")
print(f"Details: {details}")
Integration in die API-Pipeline
Die Moderation rahmt den Aufruf auf beiden Seiten ein. Das Filtern von Eingaben vermeidet Kosten für die Generierung von Inhalten, die Sie sowieso ablehnen würden; das Filtern von Ausgaben schützt vor Fällen, in denen das Modell, geschickt provoziert, selbst etwas Unannehmliches produziert. Beachten Sie den Unterschied in der Handhabung: Bei Eingaben können Sie dem Benutzer mitteilen, was erkannt wurde, da dieser den Inhalt erstellt hat; bei Ausgaben bleibt die Nachricht vage, da eine detaillierte Beschreibung bedeuten würde, was das Modell gerade produziert hat.
def moderated_chatbot(user_input: str) -> str:
"""Chatbot mit Moderation von Eingaben UND Ausgaben."""
moderator = ContentModerator()
# 1. Moderation der Eingabe
input_ok, input_details = moderator.moderate(user_input)
if not input_ok:
return (f"Ihre Nachricht wurde blockiert: "
f"{', '.join(input_details['categories'])}")
# 2. Generierung der Antwort
response = client.responses.create(
model="gpt-5.6-terra",
instructions="Antworten Sie auf professionelle und sichere Weise.",
input=user_input
)
# 3. Moderation der Ausgabe
output_ok, output_details = moderator.moderate(response.output_text)
if not output_ok:
return "Ich kann diese Antwort nicht bereitstellen."
return response.output_text
# Test
print(moderated_chatbot("Was ist die Hauptstadt Frankreichs?"))
Batch-Moderation
Dieser doppelte Aufruf fügt Latenz hinzu, was in Gesprächen akzeptabel ist, aber bei der Verarbeitung von zehntausend aus einer Datei importierten Kundenbewertungen unzumutbar wird. Um große Volumina effizient zu moderieren, übergeben Sie ein Array direkt: Die API verarbeitet alle Texte in einer einzigen Anfrage und gibt die Ergebnisse in derselben Reihenfolge zurück, sodass Sie sie über den Index wieder zuordnen können.
def moderate_batch(texts: list[str]) -> list[dict]:
"""Moderiert mehrere Texte in einer einzigen Anfrage."""
results = []
# Die API akzeptiert ein Array von Eingaben
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"{len(texts)} Texte moderiert: {flagged_count} markiert")
return results
# Nutzung
texts = [
"Hallo, wie geht es Ihnen?",
"Großartiges Produkt, ich empfehle es!",
"Der Kundenservice ist hervorragend.",
]
results = moderate_batch(texts)
Moderationsprotokollierung
Eine Moderationsentscheidung betrifft einen Benutzer, und Sie werden früher oder später den Grund dafür benötigen – sei es gegenüber einem Kunden, der einen Block bestreitet, oder gegenüber einem Regulierungsbehörden. Protokollieren Sie daher systematisch das Urteil, die Benutzer-ID, die Scores und einen Textauszug. Das Protokoll-Level unterscheidet die beiden Fälle: warning für markierte Inhalte, die einer menschlichen Prüfung bedürfen, und info für den Rest, der Ihre Statistiken speist.
import json
import logging
from datetime import datetime
logger = logging.getLogger("moderation")
def moderate_with_log(text: str, user_id: str = "anonymous") -> bool:
"""Moderiert und protokolliert das Ergebnis zur Prüfung."""
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
# Nutzung
is_ok = moderate_with_log("Testnachricht", user_id="user-123")
Eine letzte Warnung vor dem Weitergehen: Die Moderation klassifiziert Inhalte; sie versteht keine Absicht. Eine höflichste Nachricht, die versucht, Ihren Assistenten zu jailbreak, wird alle diese Filter passieren, ohne einmal markiert zu werden. Das ist das Thema der nächsten Lektion.
Kernaussagen
- Die Moderations-API ist kostenlos – nutzen Sie sie systematisch
- Moderieren Sie sowohl Eingaben (Benutzerinhalte) ALS AUCH Ausgaben (Modellantworten)
- Das Modell
omni-moderation-latestdeckt alle Inhaltskategorien ab - Protokollieren Sie alle Moderationsentscheidungen zur Prüfung
- Nutzen Sie Batch-Verarbeitung, um große Volumina effizient zu moderieren
- Die Moderation ergänzt Systemanweisungen; sie ersetzt sie nicht