Модериране на съдържание чрез API
На тази страница
Обновено на 3 ноември 2026 г. въз основа на ръководството за Moderation на OpenAI: категориите
illicitиillicit/violentза моделаomni-moderation-latestлипсваха от списъка и кода. Източник: Moderation.
Модериране на съдържание чрез API
API за модериране на OpenAI автоматично открива неуместно съдържание. Това е безплатен и основен инструмент за всяко приложение, което приема съдържание, генерирано от потребители. Предходният урок Ви показа как да пишете собствени филтри; този Ви предоставя обучен класификатор, който открива онова, което регулярните изрази никога няма да уловят – прикрити заплахи, косвени обиди и имплицитни формулировки.
API за модериране
Извикването е умишлено минималистично: един модел, един текст и резултат, свеждащ се до булева стойност. Полето flagged отговаря на бинарния въпрос: „Нарушава ли това съдържание правилата за употреба?“, докато categories детайлизират кои точно категории са засегнати. Тъй като тази крайна точка е безплатна, няма икономическа причина да я пропускате, дори при големи обеми.
from openai import OpenAI
client = OpenAI()
# The Moderation API is FREE
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}")
# Result:
# Content flagged: False
# Categories: Categories(harassment=False, hate=False, ...)
Категории за модериране
Зад булевата стойност се крие фина мрежа от критерии. Моделът връща решение за всяка категория – тормоз, заплашителен тормоз, омраза, заплашителна омраза, инструкции за незаконни действия (със или без насилие), самоувреждане с неговите варианти (инструкции и намерение), сексуално съдържание, сексуално съдържание, включващо непълнолетни, насилие и графично насилие – заедно с оценка за увереност между 0.0 и 1.0 за всяка от тях.
Тези оценки са по-важни от бинарното решение, когато искате да калибрирате своята политика. Професионална форумна платформа може да поиска блокиране при праг от 0.3 за тормоз, докато услуга за художествена литература може да приеме 0.7 за насилие. Функцията по-долу разкрива и двете нива на информация: действително задействаните категории и суровите оценки за Вашите собствени прагове.
def analyze_moderation(text: str) -> dict:
"""Detailed moderation analysis."""
moderation = client.moderations.create(
model="omni-moderation-latest",
input=text
)
result = moderation.results[0]
# Available categories
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,
}
# Confidence scores (0.0 to 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']}")
Пълен конвейер за модериране
Модериране на потребителски входове
Нека обвием това извикване в многократно използваем компонент. ContentModerator връща явна двойка – приемливо или не, с причината – вместо суров обект, който всеки извикващ трябва да преинтерпретира. Превеждането на категориите на ясен език е от значение: това е речникът, който ще се появи във Вашия интерфейс и дневници, и той трябва да бъде разбираем за екипа за човешко модериране, който поема контрола.
class ContentModerator:
"""Content moderator for applications."""
def __init__(self, custom_threshold: float = 0.5):
self.client = OpenAI()
self.threshold = custom_threshold
def moderate(self, text: str) -> tuple[bool, dict]:
"""Moderates text. Returns (is_acceptable, details)."""
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("harassment")
if result.categories.hate:
categories.append("hate speech")
if result.categories.sexual:
categories.append("sexual content")
if result.categories.violence:
categories.append("violence")
if result.categories.self_harm:
categories.append("self-harm")
return False, {
"reason": "Inappropriate content detected",
"categories": categories
}
return True, {"reason": "Content acceptable"}
def moderate_conversation(self, messages: list[str]) -> list[dict]:
"""Moderates a list of messages."""
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
# Usage
moderator = ContentModerator()
acceptable, details = moderator.moderate("Hello, how can I help you?")
print(f"Acceptable: {acceptable}")
print(f"Details: {details}")
Интегриране в API конвейера
Модерирането рамкира извикването от двете страни. Филтрирането на входа избягва плащането за генериране на съдържание, което така или иначе бихте отхвърлили; филтрирането на изхода предпазва от случаи, в които моделът, умело провокиран, сам произвежда нещо неприемливо. Отбележете разликата в обработката: при входа можете да кажете на потребителя какво е открито, тъй като той го е авторирал; при изхода съобщението остава неясно, защото детайлизирането му би означавало описание на онова, което моделът току-що е произвел.
def moderated_chatbot(user_input: str) -> str:
"""Chatbot with moderation of both inputs AND outputs."""
moderator = ContentModerator()
# 1. Moderate input
input_ok, input_details = moderator.moderate(user_input)
if not input_ok:
return (f"Your message was blocked: "
f"{', '.join(input_details['categories'])}")
# 2. Generate response
response = client.responses.create(
model="gpt-5.6-terra",
instructions="Respond in a professional and safe manner.",
input=user_input
)
# 3. Moderate output
output_ok, output_details = moderator.moderate(response.output_text)
if not output_ok:
return "I am unable to provide that response."
return response.output_text
# Test
print(moderated_chatbot("What is the capital of France?"))
Пакетно модериране
Това двойно извикване добавя латентност, което е приемливо в разговор, но става непоносимо, когато трябва да обработите десет хиляди потребителски отзива, импортирани от файл. За ефективно модериране на големи обеми, предайте масив директно: API обработва всички текстове в една заявка и връща резултатите в същия ред, позволявайки Ви да ги свържете отново по индекс.
def moderate_batch(texts: list[str]) -> list[dict]:
"""Moderates multiple texts in a single request."""
results = []
# The API accepts an array of inputs
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
# Usage
texts = [
"Hello, how are you?",
"Great product, I recommend it!",
"Customer service is excellent.",
]
results = moderate_batch(texts)
Регистриране на модерирането
Решението за модериране засяга потребител и рано или късно ще трябва да го обосновете – било пред клиент, оспорващ блокиране, или пред регулатор. Затова систематично записвайте във дневника присъдата, потребителския ID, оценките и откъс от текста. Нивото на日志 разграничава двата случая: warning за маркирано съдържание, което заслужава човешки преглед, и info за останалото, което подхранва Вашата статистика.
import json
import logging
from datetime import datetime
logger = logging.getLogger("moderation")
def moderate_with_log(text: str, user_id: str = "anonymous") -> bool:
"""Moderates and logs the result for auditing."""
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
# Usage
is_ok = moderate_with_log("Test message", user_id="user-123")
Едно последно предупреждение, преди да продължите: модерирането класифицира съдържанието; то не разбира намерението. Напълно учтиво съобщение, опитващо се да „разбие“ Вашия асистент (jailbreak), ще премине през всички тези филтри, без да бъде маркирано нито веднъж. Това е темата на следващия урок.
Ключови изводи
- API за модериране е безплатен – използвайте го систематично
- Модерирайте както входовете (потребителско съдържание), така и изходите (отговори на модела)
- Моделът
omni-moderation-latestобхваща всички категории съдържание - Записвайте всички решения за модериране за одит
- Използвайте пакетна обработка за ефективно модериране на големи обеми
- Модерирането допълва системните инструкции; то не ги замества