Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Moderacija sadržaja putem API-ja

Lekcija 19 od 22 Ažurirano 3. studenoga 2026. Programer
Na ovoj stranici
  1. Moderacija sadržaja putem API-ja
  2. API za moderaciju
  3. Kategorije moderacije
  4. Potpuni pipeline moderacije
  5. Grupna moderacija
  6. Bilježenje moderacije
  7. Ključne točke

Ažurirano 3. studenog 2026. na temelju OpenAI-jevog vodiča Moderation: kategorije illicit i illicit/violent za model omni-moderation-latest nedostajale su na popisu i u kodu. Izvor: Moderation.

Moderacija sadržaja putem API-ja

OpenAI-jev API za moderaciju automatski otkriva neprikladan sadržaj. Riječ je o besplatnom, ključnom alatu za svaku aplikaciju koja prihvaća sadržaj koji generiraju korisnici. Prethodna lekcija pokazala ti je kako pisati prilagođene filtre; ova ti daje trenirani klasifikator koji prepoznaje ono što regularni izrazi nikada neće uhvatiti – prikrivene prijetnje, neizravne uvrede i implicitne formulacije.

API za moderaciju

Poziv je namjerno minimalan: jedan model, jedan tekst i rezultat koji se svodi na boolean vrijednost. Polje flagged odgovara na binarno pitanje „Krši li ovaj sadržaj pravila korištenja?“, dok categories detaljno navodi koje su točno povrijeđene. Budući da je ova krajnja točka besplatna, nema ekonomskog razloga za preskakanje, čak ni pri velikim volumenima.

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

Kategorije moderacije

Iza boolean vrijednosti krije se fino podešena mreža. Model vraća odluku po kategoriji – uznemiravanje, prijeteće uznemiravanje, govor mržnje, prijeteći govor mržnje, upute za nedopuštene radnje (s nasiljem ili bez), samoozljeđivanje sa svojim varijantama (upute i namjera), seksualni sadržaj, seksualni sadržaj koji uključuje maloljetnike, nasilje i grafičko nasilje – uz ocjenu pouzdanosti između 0,0 i 1,0 za svaku od njih.

Ove ocjene važnije su od binarne odluke kada želiš kalibrirati svoju politiku. Profesionalna forum platforma možda će htjeti blokirati sadržaj pri 0,3 za uznemiravanje, dok bi usluga za fikciju mogla prihvatiti 0,7 za nasilje. Donja funkcija otkriva obje razine uvida: stvarno okinute kategorije i sirove ocjene za tvoje vlastite pragove.

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

Potpuni pipeline moderacije

Moderacija korisničkih unosa

Omotajmo ovaj poziv u komponentu koju možeš ponovno koristiti. ContentModerator vraća eksplicitan par – prihvatljivo ili ne, s razlogom – umjesto sirovog objekta koji bi svaki pozivatelj morao ponovno tumačiti. Prevođenje kategorija u jasan jezik je bitno: to je rječnik koji će se pojaviti u tvom sučelju i zapisnicima, a mora biti razumljiv ljudskom timu za moderaciju koji preuzima 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}")

Integracija u API pipeline

Moderacija okviruje poziv s obje strane. Filtriranje unosa izbjegava plaćanje generiranja za sadržaj koji bi ionako odbio; filtriranje izlaza štiti od slučajeva gdje model, vješto provociran, sam proizvede nešto neprihvatljivo. Primijeti razliku u rukovanju: za unos možeš korisniku reći što je otkriveno jer je on to autor; za izlaz poruka ostaje neodređena jer bi detaljiranje značilo opisivanje onoga što je model upravo proizveo.

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

Grupna moderacija

Ovaj dvostruki poziv dodaje kašnjenje, što je prihvatljivo u razgovoru, ali postaje prohibitive kada trebaš obraditi deset tisuća korisničkih recenzija uvezenih iz datoteke. Za učinkovitu moderaciju velikih volumena, proslijedi polje izravno: API obrađuje sve tekstove u jednom zahtjevu i vraća rezultate istim redoslijedom, što ti omogućuje ponovno povezivanje po indeksu.

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)

Bilježenje moderacije

Odluka o moderaciji utječe na korisnika i prije ili kasnije morat ćeš je opravdati – bilo korisniku koji osporava blokadu ili regulatoru. Stoga sustavno bilježi presudu, ID korisnika, ocjene i isječak teksta. Razina zapisa razlikuje dva slučaja: warning za označeni sadržaj, koji zaslužuje ljudski pregled, i info za ostalo, što napaja tvoju statistiku.

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

Još jedno upozorenje prije nego što prijeđemo dalje: moderacija klasificira sadržaj; ne razumije namjeru. Savršeno ljubazna poruka koja pokušava probiti sigurnost tvog asistenta proći će sve ove filtre bez ijednog označavanja. To je tema sljedeće lekcije.

Ključne točke

  • API za moderaciju je besplatan – koristi ga sustavno
  • Moderiraj i ulaze (korisnički sadržaj) I izlaze (odgovore modela)
  • Model omni-moderation-latest pokriva sve kategorije sadržaja
  • Bilježi sve odluke o moderaciji radi revizije
  • Koristi grupnu obradu za učinkovitu moderaciju velikih volumena
  • Moderacija nadopunjava sistemske upute; ne zamjenjuje ih