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

Sisällön moderointi rajapinnan avulla

Oppitunti 19 / 22 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Sisällön moderointi rajapinnan avulla
  2. Moderointirajapinta
  3. Moderointikategoriat
  4. Täydellinen moderointiputki
  5. Erämoderointi
  6. Moderointilokit
  7. Keskeiset asiat

Päivitetty 3. marraskuuta 2026 OpenAI:n Moderation-oppaan perusteella: illicit- ja illicit/violent-kategoriat puuttuivat luettelosta ja koodista omni-moderation-latest-mallin osalta. Lähde: Moderation.

Sisällön moderointi rajapinnan avulla

OpenAI:n Moderation API havaitsee automaattisesti sopimatonta sisältöä. Se on ilmainen ja välttämätön työkalu kaikille sovelluksille, jotka hyväksyvät käyttäjien tuottamaa sisältöä. Edellisessä oppitunnissa opit kirjoittamaan omia suodattimia; tämä oppitunti tarjoaa sinulle koulutetun luokittelijan, joka tunnistaa sellaista, mitä säännölliset lausekkeet eivät koskaan huomaa – peitellyt uhkaukset, epäsuorat loukkaukset ja implisiittiset ilmaisutavat.

Moderointirajapinta

Kutsu on tarkoituksellisen minimalistinen: yksi malli, yksi teksti ja tulos, joka tiivistyy totuusarvoon. flagged-kenttä vastaa binääriseen kysymykseen “Rikooko tämä sisältö käyttöehtoja?”, kun taas categories-kenttä erittelee, mitkä kategoriat ovat kyseessä. Koska tämä päätepiste on ilmainen, sen ohittamiseen ei ole taloudellista syytä edes suurissa volyymeissä.

from openai import OpenAI
client = OpenAI()

# Moderation API on ILMAINEN
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}")

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

Moderointikategoriat

Totuusarvon takana piilee hienojakoinen ruudukko. Malli palauttaa päätöksen kullekin kategorialle – häirintä, uhkaava häirintä, vihapuhe, uhkaava vihapuhe, ohjeet laittomiin tekoihin (väkivallan kanssa tai ilman), itsetuhoisuus muunnelmineen (ohjeet ja aikomus), seksuaalinen sisältö, alaikäisiin kohdistuva seksuaalinen sisältö, väkivalta ja graafinen väkivalta – sekä luottamuspisteytyksen välillä 0,0–1,0 kullekin kategorialle.

Nämä pisteet ovat tärkeämpiä kuin binäärinen päätös, kun haluat säätää käytäntöjäsi. Ammattimainen foorumialusta saattaa haluta estää sisällön jo 0,3:n rajalla häirinnän osalta, kun taas fiktiopalvelu saattaa hyväksyä 0,7:n rajan väkivallalle. Alla oleva funktio tarjoaa molemmat näkökulmat: todellisuudessa laukaistut kategoriat ja raakatulokset omia kynnysarvojasi varten.

def analyze_moderation(text: str) -> dict:
    """Yksityiskohtainen moderointianalyysi."""
    moderation = client.moderations.create(
        model="omni-moderation-latest",
        input=text
    )

    result = moderation.results[0]

    # Käytettävissä olevat kategoriat
    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,
    }

    # Luottamuspisteet (0.0 - 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()},
    }

# Testi
result = analyze_moderation("Hello everyone!")
print(f"Flagged: {result['flagged']}")
print(f"Scores: {result['main_scores']}")

Täydellinen moderointiputki

Käyttäjän syötteiden moderointi

Kääritään tämä kutsu uudelleenkäytettäväksi komponentiksi. ContentModerator palauttaa eksplisiittisen parin – hyväksyttävä vai ei, ja miksi – raaka-objektin sijaan, jota jokaisen kutsujan pitäisi tulkita uudelleen. Kategorioiden kääntäminen selkeäksi kieleksi on tärkeää: tämä on sanasto, joka näkyy käyttöliittymässäsi ja lokeissa, ja sen on oltava ymmärrettävää ihmismoderaattoreille, jotka ottavat asian hoitaakseen.

class ContentModerator:
    """Sovellusten sisällönmoderaattori."""

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

    def moderate(self, text: str) -> tuple[bool, dict]:
        """Moderoi tekstin. Palauttaa (on_hyväksyttävä, tiedot)."""
        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": "Sopimatonta sisältöä havaittu",
                "categories": categories
            }

        return True, {"reason": "Sisältö hyväksyttävä"}

    def moderate_conversation(self, messages: list[str]) -> list[dict]:
        """Moderoi listan viestejä."""
        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

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

Integrointi API-putkeen

Moderointi kehystää kutsun molemmilta puolilta. Syötteen suodattaminen estää maksamasta generoinnista sisällöstä, jonka hylkäisit joka tapauksessa; tulosteen suodattaminen suojaa tilanteilta, joissa malli, taitavasti provosoituna, tuottaa itse jotain hyväksymätöntä. Huomaa käsittelyn ero: syötteen kohdalla voit kertoa käyttäjälle, mitä havaittiin, koska hän on sen kirjoittanut; tulosteen kohdalla viesti pysyy epämääräisenä, koska sen yksityiskohtainen kuvaaminen tarkoittaisi juuri tuotetun sisällön toistamista.

def moderated_chatbot(user_input: str) -> str:
    """Chatbot, jossa moderoidaan sekä syötteet että tulosteet."""
    moderator = ContentModerator()

    # 1. Syötteen moderointi
    input_ok, input_details = moderator.moderate(user_input)
    if not input_ok:
        return (f"Viestisi estettiin: "
                f"{', '.join(input_details['categories'])}")

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

    # 3. Tulosteen moderointi
    output_ok, output_details = moderator.moderate(response.output_text)
    if not output_ok:
        return "En voi antaa tuota vastausta."

    return response.output_text

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

Erämoderointi

Tämä kaksoiskutsu lisää viivettä, mikä on hyväksyttävää keskustelussa, mutta muuttuu kohtuuttomaksi, kun sinun on käsiteltävä kymmeniätuhansia asiakasarvioita tiedostosta tuotuna. Suurten volyymien tehokkaaseen moderointiin välitä taulukko suoraan: rajapinta käsittelee kaikki tekstit yhdessä pyynnössä ja palauttaa tulokset samassa järjestyksessä, jolloin voit yhdistää ne uudelleen indeksin perusteella.

def moderate_batch(texts: list[str]) -> list[dict]:
    """Moderoi useita tekstejä yhdessä pyynnössä."""
    results = []

    # Rajapinta hyväksyy syötteiden taulukon
    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

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

Moderointilokit

Moderointipäätös vaikuttaa käyttäjään, ja ennemmin tai myöhemmin sinun on perusteltava se – olipa kyseessä sitten esto kiistävä asiakas tai valvontaviranomainen. Siksi kirjaa järjestelmällisesti tuomio, käyttäjätunnus, pisteet ja tekstikatkelma. Lokitaso erottaa kaksi tapausta: warning merkitylle sisällölle, joka ansaitsee ihmisen tarkastelun, ja info muulle, joka syöttää tilastojasi.

import json
import logging
from datetime import datetime

logger = logging.getLogger("moderation")

def moderate_with_log(text: str, user_id: str = "anonymous") -> bool:
    """Moderoi ja kirjaa tuloksen tarkastusta varten."""
    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

# Käyttö
is_ok = moderate_with_log("Test message", user_id="user-123")

Yksi viimeinen varoitus ennen jatkamista: moderointi luokittelee sisältöä; se ei ymmärrä aikomusta. Täysin kohtelias viesti, joka yrittää murtaa assistenttisi suojauksen, pääsee kaikkien näiden suodattimien läpi ilman merkintää. Se on seuraavan oppitunnin aihe.

Keskeiset asiat

  • Moderation API on ilmainen – käytä sitä järjestelmällisesti
  • Moderoi sekä syötteet (käyttäjän sisältö) että tulosteet (mallin vastaukset)
  • omni-moderation-latest-malli kattaa kaikki sisältökategoriat
  • Kirjaa kaikki moderointipäätökset tarkastusta varten
  • Käytä eräprosessointia suurten volyymien tehokkaaseen moderointiin
  • Moderointi täydentää järjestelmäohjeita; se ei korvaa niitä