Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Sisällön moderointi laajassa mittakaavassa

Oppitunti 19 / 20 Päivitetty 3. marraskuuta 2026 Edistynyt
Tällä sivulla
  1. Käyttäjiesi suojeleminen tuotantoympäristössä
  2. Ensimmäinen kerros: Moderations API
  3. Kuorman käsittely
  4. Puolustettavan lokin ylläpito
  5. Keskeiset asiat

Oppitunti päivitetty 3. marraskuuta 2026 OpenAI:n dokumentaation perusteella: parametrit temperature ja top_p hyväksytään vain, kun päättelytaso (reasoning effort) on none, kun taas GPT-5.6-mallit käyttävät oletusarvoisesti päättelyä (medium). Näitä parametreja asettavien kutsujen on siis määritettävä reasoning={"effort": "none"} (Responses API) tai reasoning_effort="none" (Chat Completions). Lähteet: Using GPT-6 · GPT-5.6 Terra.

Käyttäjiesi suojeleminen tuotantoympäristössä

Heti kun sovelluksesi julkaistaan, sinun on käsiteltävä sopimatonta sisältöä sekä syötteissä (haitalliset kehotteet) että tulosteissa (ongelmalliset vastaukset). Tämä kaksisuuntainen vaatimus yllättää tiimit usein. Useimmat ajattelevat ensin käyttäjien lähettämän sisällön suodattamista, mutta maineeriski keskittyy siihen, mitä sovelluksesi julkaisee nimissäsi. Hyvin linjattu malli tuottaa harvoin järkyttävää sisältöä itsestään, mutta se voi tehdä niin painostettuna – ja brändisi näkyy kuvakaappauksen yläosassa.

Siirrymme yksittäisestä API-kutsusta suuriläpimenoiseen asynkroniseen putkeen skaalaten askel askeleelta.

Ensimmäinen kerros: Moderations API

Moderations API luokittelee tekstiä useisiin riskiluokkiin ja palauttaa sekä binäärisen päätöksen että yksityiskohtaiset pisteytykset. Se on nopea ja ilmainen, mikä tekee siitä luonnollisen ensimmäisen suodattimen kaikille julkisille sovelluksille. Alla oleva funktio näyttää vain ne luokat, joiden pisteytys ylittää 0,3 – tämä on tarkoituksellisen alhainen kynnys. Tässä vaiheessa haluat nähdä, mikä lähestyy rajaa, ei vain sen, mikä ylittää sen.

import openai

client = openai.OpenAI()

def moderate_content(text: str) -> dict:
    """Tarkista, sisältääkö teksti sopimatonta sisältöä."""
    response = client.moderations.create(
        model="omni-moderation-latest",
        input=text,
    )

    result = response.results[0]
    return {
        "flagged": result.flagged,
        "categories": {
            cat: score
            for cat, score in result.category_scores.__dict__.items()
            if score > 0.3
        },
    }

# Esimerkki
result = moderate_content("How do I bake a chocolate cake?")
print(f"Flagged: {result['flagged']}")

Tuotantoympäristössä binäärinen päätös ei riitä. Sisällön ja kontekstin mukaan saatat haluta hyväksyä sen, kirjoittaa sen uudelleen, estää sen tai eskaloida sen ihmiselle – neljä erillistä päätöstä, jotka sinun tulee nimetä eksplisiittisesti koodissa sen sijaan, että improvisoisit totuusarvoilla. Alla oleva putki formalisoi nämä toiminnot, soveltaa luokkakohtaisia kynnysarvoja ja lisää toisen kerros kehotteiden injektointien havaitsemiseen.

from enum import Enum
from dataclasses import dataclass

class ModerationAction(Enum):
    ALLOW = "allow"
    MODIFY = "modify"
    BLOCK = "block"
    ESCALATE = "escalate"

@dataclass
class ModerationResult:
    action: ModerationAction
    reason: str | None = None
    modified_content: str | None = None

class ModerationPipeline:
    """Monikerroksinen moderointiputki."""

    def __init__(self, thresholds: dict | None = None):
        self.thresholds = thresholds or {
            "harassment": 0.7,
            "hate": 0.7,
            "self-harm": 0.5,
            "sexual": 0.7,
            "violence": 0.7,
        }

    def moderate_input(self, text: str) -> ModerationResult:
        """Moderoi syötesisältöä (käyttäjän kehotus)."""
        moderation = client.moderations.create(
            model="omni-moderation-latest",
            input=text,
        )

        result = moderation.results[0]
        if result.flagged:
            problematic_categories = [
                cat for cat, flagged in result.categories.__dict__.items()
                if flagged
            ]
            return ModerationResult(
                action=ModerationAction.BLOCK,
                reason=f"Inappropriate content: {', '.join(problematic_categories)}",
            )

        # Kehotteen injektion havaitseminen
        if self._detect_injection(text):
            return ModerationResult(
                action=ModerationAction.BLOCK,
                reason="Prompt injection attempt detected",
            )

        return ModerationResult(action=ModerationAction.ALLOW)

    def moderate_output(self, response: str) -> ModerationResult:
        """Moderoi tulostesisältöä (LLM-vastaus)."""
        moderation = client.moderations.create(
            model="omni-moderation-latest",
            input=response,
        )

        if moderation.results[0].flagged:
            return ModerationResult(
                action=ModerationAction.BLOCK,
                reason="Generated response contains inappropriate content",
            )

        return ModerationResult(action=ModerationAction.ALLOW)

    def _detect_injection(self, text: str) -> bool:
        """Havaitse kehotteen injektioyritykset."""
        markers = [
            "ignore previous instructions",
            "ignore your instructions",
            "forget your guidelines",
            "you are now",
            "new role",
            "system prompt",
            "jailbreak",
        ]
        text_lower = text.lower()
        return any(m in text_lower for m in markers)

Kynnysarvo 0,5 kohdalle self-harm – tiukempi kuin muissa luokissa käytetty 0,7 – havainnollistaa päättelyä, jota sinun tulee soveltaa jokaiseen kynnysarvoon. Tässä väärän positiivisen tuloksen kustannus ei ole missään nimessä verrattavissa väärän negatiivisen tuloksen kustannukseen, joten lasket rimaa. Tee tämä kompromissi luokka kerrallaan kohdeyleisösi perusteella sen sijaan, että soveltaisit yhtenäistä arvoa.

Merkkipohjaiseen injektion havaitsemiseen liittyy varaus. Se sieppaa naiivit yritykset, jotka muodostavat suurimman osan volyymista, eikä mitään muuta: hieman erilainen muotoilu tai käännetty versio pääsee läpi. Käsittele sitä kohinasuodattimena, älä puolustuksena. Todellinen suoja injektioita vastaan on arkkitehtonista – älä koskaan anna mallille valmiuksia, joita kaapattu kehotus voisi hyödyntää.

Kuorman käsittely

Suuren liikenteen sovelluksessa synkroninen moderointi muodostuu pullonkaulaksi: jokainen viesti odottaa päätöstään ennen käsittelyä. Asynkroninen moderaattori irrottaa nämä vaiheet toisistaan asettamalla sisällön jonoon useiden työntekijöiden kulutettavaksi ja samalla seuraten hyödyllisiä tilastoja matkan varrella.

import asyncio

class AsyncModerator:
    """Moderoi sisältöä asynkronisesti suurta läpimenoa varten."""

    def __init__(self, num_workers: int = 10):
        self.pipeline = ModerationPipeline()
        self.queue: asyncio.Queue = asyncio.Queue()
        self.num_workers = num_workers
        self.stats = {"allowed": 0, "blocked": 0, "escalated": 0}

    async def worker(self):
        while True:
            task = await self.queue.get()
            try:
                result = self.pipeline.moderate_input(task["text"])
                task["callback"](result)

                match result.action:
                    case ModerationAction.ALLOW:
                        self.stats["allowed"] += 1
                    case ModerationAction.BLOCK:
                        self.stats["blocked"] += 1
                    case ModerationAction.ESCALATE:
                        self.stats["escalated"] += 1
            finally:
                self.queue.task_done()

    async def start(self):
        for _ in range(self.num_workers):
            asyncio.create_task(self.worker())

    def report(self) -> str:
        total = sum(self.stats.values())
        if total == 0:
            return "No content moderated."
        return (
            f"Total: {total} | "
            f"Allowed: {self.stats['allowed']} ({self.stats['allowed']/total:.1%}) | "
            f"Blocked: {self.stats['blocked']} ({self.stats['blocked']/total:.1%})"
        )

Funktion report tuottama estoprosentti on ensisijainen kalibrointimittarisi. Jos se hyppää äkillisesti 0,5 %:sta 15 %:iin, selityksiä on vain kaksi: olet koordinoitujen hyökkäysten kohteena, tai rikoit juuri kynnysarvosi. Kummassakin tapauksessa haluat tietää asiasta tunnin sisällä, etkä seuraavassa kuukausittaisessa katsauksessa.

Yksi viimeinen rajoitus ansaitsee maininnan: Moderations API ei tiedä mitään liiketoiminnastasi. Viesti, joka on yleisesti täysin hyväksyttävä, voi rikkoa omia sääntöjäsi – kuten lääketieteellisen neuvon pyytäminen pankkiassistentilta, verkon ulkopuolisen hinnan hankkiminen tai menettelyn kiertäminen. Kontekstuaalinen moderointi lisää tämän kerroksen lähettämällä viestin mallille, jolla on eksplisiittiset sääntösi, mutta vasta sen jälkeen, kun vakiosuodatin on päästänyt sen läpi.

def contextual_moderation(
    text: str,
    app_context: str,
    business_rules: list[str],
) -> ModerationResult:
    """Sovellukseen räätälöity kontekstitietoinen moderointi."""
    pipeline = ModerationPipeline()
    standard_result = pipeline.moderate_input(text)

    if standard_result.action == ModerationAction.BLOCK:
        return standard_result

    verification_prompt = (
        f"Application context: {app_context}\n\n"
        f"Business rules to verify:\n"
        + "\n".join(f"- {r}" for r in business_rules)
        + f"\n\nUser message: {text}\n\n"
        "Does the message comply with all rules? "
        "Answer yes or no with a brief justification."
    )

    response = client.responses.create(
        model="gpt-5.6-terra",
        reasoning={"effort": "none"},  # temperature requires effort none
        input=verification_prompt,
        max_output_tokens=100,
        temperature=0.0,
    )

    if "no" in response.output_text.lower()[:10]:
        return ModerationResult(
            action=ModerationAction.BLOCK,
            reason=response.output_text,
        )

    return ModerationResult(action=ModerationAction.ALLOW)

Näiden kahden tarkistuksen järjestyksellä on väliä. Ilmainen, nopea suodatin ajetaan ensin, ja maksettu mallikutsu tapahtuu vain viesteille, jotka läpäisevät sen. Todellisessa liikenteessä tämä kattaa lähes kaikki viestit. Päinvastoin tekeminen – maksaminen mallikutsusta sisällölle, jonka Moderations API olisi hylännyt millisekunneissa – olisi tuhlausta.

Puolustettavan lokin ylläpito

Moderointipäätös on päätös, josta joudut vastaamaan tavalla tai toisella. Tarvitset lokin – mutta sellaisen, josta ei itsestään tule ongelmaa. Koodin kommentti korostaa tiedoston tärkeintä riviä: kirjaa toiminto, syy ja pituus, älä koskaan raakatekstiä. Käyttäjäviestien tallentaminen lokitiedostoon altistaa sinut tietosuojavelvoitteille, jotka ovat paljon raskaampia kuin tarjottu palvelu.

import json
import time
from pathlib import Path

class ModerationLog:
    """Lokita kaikki moderointipäätökset tarkastusta varten."""

    def __init__(self, log_path: str = "logs/moderation.jsonl"):
        self.path = Path(log_path)
        self.path.parent.mkdir(parents=True, exist_ok=True)

    def record(
        self,
        text: str,
        result: ModerationResult,
        source: str = "input",
    ):
        entry = {
            "timestamp": time.time(),
            "source": source,
            "action": result.action.value,
            "reason": result.reason,
            "text_length": len(text),
            # DO NOT log raw text for privacy
        }

        with open(self.path, "a") as f:
            f.write(json.dumps(entry) + "\n")

Jos sinun on silti pystyttävä hakemaan tietty viesti riitatilanteessa, lokita tekstin tiiviste (hash) itse tekstin sijaan. Tämä mahdollistaa sen vahvistamisen, että tietty sisältö vastaa kirjattua päätöstä, pitämättä sisältöä itselläsi.

Keskeiset asiat

  • Moderoi sekä syötteitä (kehotteet) että tulosteita (vastaukset)
  • Käytä Moderations API:ta ensimmäisenä, nopeana ja ilmaisena kerroksena
  • Säädä kynnysarvoja luokka kerrallaan väärän negatiivisen tuloksen todellisten kustannusten perusteella
  • Lisää injektion havaitseminen tietäen, että se sieppaa vain naiivit yritykset
  • Lokita kaikki päätökset tarkastusta varten tallentamatta raakasisältöä