Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Moderování obsahu pomocí API

Lekce 19 z 22 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Moderování obsahu pomocí API
  2. API pro moderování
  3. Kategorie moderování
  4. Kompletní pipeline moderování
  5. Dávkové moderování
  6. Logování moderování
  7. Klíčové poznatky

Aktualizováno 3. listopadu 2026 na základě příručky Moderation od OpenAI: kategorie illicit a illicit/violent pro model omni-moderation-latest chyběly v seznamu a kódu. Zdroj: Moderation.

Moderování obsahu pomocí API

API pro moderování od OpenAI automaticky detekuje nevhodný obsah. Je to bezplatný a nezbytný nástroj pro jakoukoli aplikaci, která přijímá obsah generovaný uživateli. Předchozí lekce ti ukázala, jak psát vlastní filtry; tato ti poskytuje trénovaný klasifikátor, který odhalí to, co regulární výrazy nikdy nezachytí – zastřené hrozby, nepřímé urážky a implicitní formulace.

API pro moderování

Volání je záměrně minimalistické: jeden model, jeden text a výsledek, který se redukuje na boolean hodnotu. Pole flagged odpovídá na binární otázku „Porušuje tento obsah zásady používání?“, zatímco categories upřesňuje, které konkrétně. Protože je tento koncový bod zdarma, neexistuje žádný ekonomický důvod jej vynechávat, ani při vysokých objemech.

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, ...)

Kategorie moderování

Za boolean hodnotou se skrývá jemně zrnitá mřížka. Model vrací rozhodnutí pro každou kategorii – obtěžování, vyhrožující obtěžování, nenávist, vyhrožující nenávist, pokyny k nedovoleným činům (s násilím i bez něj), sebepoškozování s jeho variantami (pokyny a záměr), sexuální obsah, sexuální obsah zahrnující nezletilé, násilí a grafické násilí – spolu s hodnotou spolehlivosti mezi 0,0 a 1,0 pro každou z nich.

Tyto hodnoty jsou důležitější než binární rozhodnutí, když chceš kalibrovat svou politiku. Profesionální fórová platforma může chtít blokovat při hodnotě 0,3 pro obtěžování, zatímco služba pro beletrii může akceptovat 0,7 pro násilí. Níže uvedená funkce odhaluje obě úrovně vhledu: skutečně spuštěné kategorie a surová skóre pro tvé vlastní prahy.

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']}")

Kompletní pipeline moderování

Moderování uživatelských vstupů

Zabalme toto volání do znovu použitelné komponenty. ContentModerator vrací explicitní dvojici – přijatelné či nikoli, s důvodem – namísto surového objektu, který by musel každý volající znovu interpretovat. Překlad kategorií do srozumitelného jazyka matters: toto je slovník, který se objeví ve tvém rozhraní a logách, a musí být srozumitelný pro lidský tým moderátorů, který převezme kontrolu.

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}")

Integrace do pipeline API

Moderování rámuje volání na obou stranách. Filtrování vstupu zabraňuje placení za generování obsahu, který bys stejně zamítl; filtrování výstupu chrání před případy, kdy model, šikovně provocován, sám vyprodukuje něco nepřijatelného. Všimni si rozdílu v zacházení: u vstupu můžeš uživateli sdělit, co bylo detekováno, protože to on autor; u výstupu zůstává zpráva vágní, protože její detailní popis by znamenal popisovat to, co model právě vyprodukoval.

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?"))

Dávkové moderování

Toto dvojí volání přidává latenci, což je v konverzaci přijatelné, ale stává se neúnosným, když potřebuješ zpracovat deset tisíc recenzí zákazníků importovaných ze souboru. Pro efektivní moderování velkých objemů předej pole přímo: API zpracuje všechny texty v jediném požadavku a vrátí výsledky ve stejném pořadí, což ti umožní je znovu přiřadit podle indexu.

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)

Logování moderování

Rozhodnutí o moderování ovlivňuje uživatele a dříve či později budeš muset toto rozhodnutí obhájit – ať už zákazníkovi, který napadne blokování, nebo regulátorovi. Proto systematicky loguj verdikt, ID uživatele, skóre a úryvek textu. Úroveň logu rozlišuje dva případy: warning pro označený obsah, který si zaslouží lidskou revizi, a info pro zbytek, který napájí tvé statistiky.

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")

Ještě jedno varování, než pokračujeme dál: moderování klasifikuje obsah; nerozumí záměru. Zcela zdvořilá zpráva, která se pokouší obejít tvého asistenta (jailbreak), projde všemi těmito filtry, aniž by byla jedinkrát označena. To je tématem příští lekce.

Klíčové poznatky

  • API pro moderování je zdarma – používej jej systematicky
  • Moderuj jak vstupy (obsah od uživatelů), tak výstupy (odpovědi modelu)
  • Model omni-moderation-latest pokrývá všechny kategorie obsahu
  • Loguj všechna rozhodnutí o moderování pro účely auditu
  • Používej dávkové zpracování pro efektivní moderování velkých objemů
  • Moderování doplňuje systémové instrukce; nenahrazuje je