Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Sisumoderatsioon API abil

Õppetund 19 / 22 Värskendatud 3. november 2026 Arendajatele
Sellel lehel
  1. Sisumoderatsioon API abil
  2. Moderatsiooni API
  3. Moderatsiooni kategooriad
  4. Täielik moderatsioonitorustik
  5. Partii-moderatsioon
  6. Moderatsiooni logimine
  7. Peamised punktid

Uuendatud 3. novembril 2026 vastavalt OpenAI Moderation juhendile: mudeli omni-moderation-latest kategooriad illicit ja illicit/violent puudusid loendist ja koodist. Allikas: Moderation.

Sisumoderatsioon API abil

OpenAI moderatsiooni API tuvastab automaatselt sobimatu sisu. See on tasuta ja hädavajalik tööriist iga rakenduse jaoks, mis aktsepteerib kasutaja loodud sisu. Eelmises õppetunnis näitasime, kuidas kirjutada kohandatud filtreid; see annab sulle treenitud klassifikaatori, mis tabab seda, mida regulaaravaldised kunagi ei püüa – varjatud ähvardused, kaudsed solvangud ja implitsiitsed väljendid.

Moderatsiooni API

Päring on tahtlikult minimaalne: üks mudel, üks tekst ja tulemus, mis taandub boolean-väärtusele. Väli flagged vastab binaarsele küsimusele „Kas see sisu rikub kasutustingimusi?“, samas kui categories täpsustab, millised kategooriad on asjasse puutuvad. Kuna see lõpp-punkt on tasuta, pole majanduslikku põhjust seda vahele jätta, isegi mitte suurte mahtude korral.

from openai import OpenAI
client = OpenAI()

# Moderatsiooni API on TASUTA
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}")

# Tulemus:
# Content flagged: False
# Categories: Categories(harassment=False, hate=False, ...)

Moderatsiooni kategooriad

Boolean-väärtuse taga peitub peeneteraline võrestik. Mudel tagastab otsuse iga kategooria kohta – ahistamine, ähvardav ahistamine, vihakõne, ähvardav vihakõne, juhised ebaseaduslikeks tegudeks (kas koos vägivallaga või ilma), enesevigastamine koos selle variantidega (juhised ja kavatsus), seksuaalne sisu, alaealisi puudutav seksuaalne sisu, vägivald ja graafiline vägivald – ning igaühele usaldusväärsuse skoori vahemikus 0,0 kuni 1,0.

Need skoorid on olulisemad kui binaarne otsus, kui soovid oma poliitikat kalibreerida. Professionaalne foorumi platvorm võib soovida blokeerida ahistamise korral lävendil 0,3, samas kui ilukirjandusteenus võib aktsepteerida vägivalla korral 0,7. Allpool olev funktsioon toob välja mõlemad teabetasemed: tegelikult käivitunud kategooriad ja toorskoorid sinu enda lävendite jaoks.

def analyze_moderation(text: str) -> dict:
    """Üksikasjalik moderatsioonianalüüs."""
    moderation = client.moderations.create(
        model="omni-moderation-latest",
        input=text
    )

    result = moderation.results[0]

    # Saadaolevad kategooriad
    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,
    }

    # Usaldusväärsuse skoorid (0.0 kuni 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']}")

Täielik moderatsioonitorustik

Kasutaja sisendite moderatsioon

Pakendame selle väljakutse uuestikasutatavasse komponenti. ContentModerator tagastab selge paari – vastuvõetav või mitte, koos põhjusega – mitte toorest objekti, mida iga väljakutsuja peaks uuesti tõlgendama. Kategooriate selgeks keeleks tõlkimine on oluline: see on sõnavara, mis ilmub sinu liideses ja logides, ning see peab olema arusaadav inimmoderaatorite meeskonnale, kes asja üle võtab.

class ContentModerator:
    """Rakenduste sisumoderaator."""

    def __init__(self, custom_threshold: float = 0.5):
        self.client = OpenAI()
        self.threshold = custom_threshold

    def moderate(self, text: str) -> tuple[bool, dict]:
        """Modererib teksti. Tagastab (on_vastuvõetav, üksikasjad)."""
        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": "Sobimatu sisu tuvastatud",
                "categories": categories
            }

        return True, {"reason": "Sisu on vastuvõetav"}

    def moderate_conversation(self, messages: list[str]) -> list[dict]:
        """Modererib sõnumite loendit."""
        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

# Kasutamine
moderator = ContentModerator()
acceptable, details = moderator.moderate("Hello, how can I help you?")
print(f"Acceptable: {acceptable}")
print(f"Details: {details}")

Integreerimine API torustikku

Moderatsioon raamib väljakutset mõlemalt poolt. Sisendi filtreerimine hoiab ära genereerimise eest maksmise sisu eest, mille niikuinii tagasi lükkaksid; väljundi filtreerimine kaitseb juhtumite eest, kus mudel, osavalt provotseerituna, toodab ise midagi vastuvõetamatut. Pane tähele erinevust käsitlemisel: sisendi puhul saad kasutajale öelda, mida tuvastati, kuna tema on selle autor; väljundi puhul jääb sõnum ebamääraseks, sest selle detailselt kirjeldamine tähendaks seda, mida mudel just tootis, ümber jutustamist.

def moderated_chatbot(user_input: str) -> str:
    """Vestlusrobot nii sisendi KUI KA väljundi moderatsiooniga."""
    moderator = ContentModerator()

    # 1. Sisendi moderatsioon
    input_ok, input_details = moderator.moderate(user_input)
    if not input_ok:
        return (f"Sinu sõnum blokeeriti: "
                f"{', '.join(input_details['categories'])}")

    # 2. Vastuse genereerimine
    response = client.responses.create(
        model="gpt-5.6-terra",
        instructions="Respond in a professional and safe manner.",
        input=user_input
    )

    # 3. Väljundi moderatsioon
    output_ok, output_details = moderator.moderate(response.output_text)
    if not output_ok:
        return "Ma ei saa seda vastust anda."

    return response.output_text

# Test
print(moderated_chatbot("What is the capital of France?"))

Partii-moderatsioon

See topeltväljakutse lisab latentsust, mis on vestluses vastuvõetav, kuid muutub keelavaks, kui pead töötlema kümneid tuhandeid failist imporditud kliendiülevaateid. Suurte mahtude tõhusaks moderatsiooniks edasta massiiv otse: API töötleb kõiki tekste ühes päringus ja tagastab tulemused samas järjekorras, võimaldades sul need indeksi järgi uuesti seostada.

def moderate_batch(texts: list[str]) -> list[dict]:
    """Modererib mitut teksti ühes päringus."""
    results = []

    # API aktsepteerib sisendite massiivi
    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

# Kasutamine
texts = [
    "Hello, how are you?",
    "Great product, I recommend it!",
    "Customer service is excellent.",
]
results = moderate_batch(texts)

Moderatsiooni logimine

Moderatsiooniotsus mõjutab kasutajat ja varem või hiljem pead seda põhjendama – olgu siis kliendile, kes vaidlustab blokeeringu, või regulaatorile. Seetõttu logi süstemaatiliselt otsus, kasutaja ID, skoorid ja tekstilõik. Logi tase eristab kaht juhtumit: warning märgistatud sisu jaoks, mis väärib inimülevaatust, ja info ülejäänud jaoks, mis toidab sinu statistikat.

import json
import logging
from datetime import datetime

logger = logging.getLogger("moderation")

def moderate_with_log(text: str, user_id: str = "anonymous") -> bool:
    """Modererib ja logib tulemuse auditeerimiseks."""
    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

# Kasutamine
is_ok = moderate_with_log("Test message", user_id="user-123")

Viimane hoiatus enne edasiliikumist: moderatsioon klassifitseerib sisu; see ei mõista kavatsust. Täiesti viisakas sõnum, mis üritab sinu assistenti „jailbreakida“, läbib kõik need filtrid, ilma et seda kordagi märgistataks. See on järgmise õppetunni teema.

Peamised punktid

  • Moderatsiooni API on tasuta – kasuta seda süstemaatiliselt
  • Modereri nii sisendeid (kasutaja sisu) KUI KA väljundeid (mudeli vastused)
  • Mudel omni-moderation-latest hõlmab kõiki sisukategooriaid
  • Logi kõik moderatsiooniotsused auditeerimiseks
  • Kasuta partii-töötlust suurte mahtude tõhusaks moderatsiooniks
  • Moderatsioon täiendab süsteemi juhiseid; see ei asenda neid