Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Il-Moderazzjoni tal-Kontenut bl-API

Lezzjoni 19 / 22 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Il-Moderazzjoni tal-Kontenut bl-API
  2. L-API tal-Moderazzjoni
  3. Kategoriji tal-Moderazzjoni
  4. Pipeline Sħiħa tal-Moderazzjoni
  5. Moderazzjoni f’Lotti (Batch)
  6. Reġistrazzjoni tal-Moderazzjoni (Logging)
  7. Punti Ewlenin

Aġġornat fit-3 ta’ Novembru, 2026 abbażi tal-gwida tal-Moderazzjoni ta’ OpenAI: il-kategoriji illicit u illicit/violent għall-mudell omni-moderation-latest kienu nieqsa mil-lista u mill-kodiċi. Sors: Moderazzjoni.

Il-Moderazzjoni tal-Kontenut bl-API

L-API tal-Moderazzjoni ta’ OpenAI tiskopri awtomatikament kontenut mhux xieraq. Dan huwa għodda bla ħlas u essenzjali għal kwalunkwe applikazzjoni li taċċetta kontenut iġġenerat mill-utenti. Il-lezzjoni preċedenti wrietek kif tikteb filtri custom; din tingħatik klassifikatur imħarreġ li jinduna b’dak li l-espressjonijiet regolari qatt ma jaqbdu—theddidiet moħbija, insulti indiretti, u frażijiet impliċiti.

L-API tal-Moderazzjoni

Is-sejħa hija intenzjonalment minima: mudell wieħed, test wieħed, u riżultat li jinġabar f’boolean wieħed. Il-qasam flagged iwieġeb il-mistoqsija binarja, “Dan il-kontenut jikser il-politiki tal-użu?”, filwaqt li categories jiddettalja liema minnhom. Peress li dan l-endpoint huwa bla ħlas, m’hemm l-ebda raġuni ekonomika biex taqbiżu, anke f’volumi għoljin.

from openai import OpenAI
client = OpenAI()

# L-API tal-Moderazzjoni hija B'XEJN
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}")

# Riżultat:
# Content flagged: False
# Categories: Categories(harassment=False, hate=False, ...)

Kategoriji tal-Moderazzjoni

Wara l-boolean hemm gradilja fina. Il-mudell jirritorna deċiżjoni għal kull kategorija—fastidju (harassment), fastidju b’theddida, mibegħda, mibegħda b’theddida, struzzjonijiet għal atti illeċiti (bi jew mingħajr vjolenza), awto-ħsara bil-varjanti tagħha (struzzjonijiet u intenzjoni), kontenut sesswali, kontenut sesswali li jinvolvi minuri, vjolenza, u vjolenza grafika—flimkien ma’ punteġġ ta’ kunfidenza bejn 0.0 u 1.0 għal kull waħda.

Dawn il-punteġġi huma aktar importanti mid-deċiżjoni binarja meta trid tikkalibra l-politika tiegħek. Pjattaforma professjonali ta’ forum tista’ tirriżerva ruħha li timblokka f’0.3 għall-fastidju, filwaqt li servizz ta’ finzjoni jista’ jaċċetta 0.7 għall-vjolenza. Il-funzjoni hawn taħt tesponi ż-żewġ livelli ta’ għarfien: il-kategoriji attwalment attivati, u l-punteġġi raw għas-soglie tiegħek stess.

def analyze_moderation(text: str) -> dict:
    """Analiżi dettaljata tal-moderazzjoni."""
    moderation = client.moderations.create(
        model="omni-moderation-latest",
        input=text
    )

    result = moderation.results[0]

    # Kategoriji disponibbli
    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,
    }

    # Punteġġi ta' kunfidenza (0.0 sa 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']}")

Pipeline Sħiħa tal-Moderazzjoni

Il-Moderazzjoni tal-Inputs tal-Utenti

Ejja npoġġu din is-sejħa f’komponent li jista’ jerġa’ jintuża. ContentModerator jirritorna par espliċitu—aċċettabbli jew le, bir-raġuni—minflok oġġett raw li kull sejjaħ ikollu jerġa’ jinterpreta. It-traduzzjoni tal-kategoriji f’lingwaġġ ċar hija importanti: dan huwa l-vokabolarju li jidher fl-interfaċċa u fil-logs tiegħek, u jrid ikun mifhum mit-tim tal-moderazzjoni umana li jieħu f’idejh il-każ.

class ContentModerator:
    """Moderatur tal-kontenut għall-applikazzjonijiet."""

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

    def moderate(self, text: str) -> tuple[bool, dict]:
        """Jimmodera t-test. Jirritorna (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]:
        """Jimmodera lista ta' messaġġi."""
        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

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

Integrazzjoni fil-Pipeline tal-API

Il-moderazzjoni tgħaqqad is-sejħa miż-żewġ naħat. Il-filtrar tal-input jevita li tħallas għall-ġenerazzjoni fuq kontenut li kieku kienet tirrifjuta; il-filtrar tal-output jipproteġi kontra każijiet fejn il-mudell, ipprovokat b’mod abbli, jipproduċi xi ħaġa inaċċettabbli huwa stess. Innota d-differenza fit-trattament: għall-input, tista’ tgħid lill-utent x’instab, peress li huwa l-awtur tiegħu; għall-output, il-messaġġ jibqa’ vag, għax li tiddettaljah ifisser li tiddeskrivi eżattament dak li l-mudell għadu kemm ipproduċa.

def moderated_chatbot(user_input: str) -> str:
    """Chatbot bil-moderazzjoni tal-inputs U tal-outputs."""
    moderator = ContentModerator()

    # 1. Modera l-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. Iġġenera r-rispons
    response = client.responses.create(
        model="gpt-5.6-terra",
        instructions="Respond in a professional and safe manner.",
        input=user_input
    )

    # 3. Modera l-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?"))

Moderazzjoni f’Lotti (Batch)

Din is-sejħa doppja żżid latenza, li hija aċċettabbli fil-konversazzjoni iżda ssir projbittiva meta jkollok bżonn tipproċessa għaxart elef reviżjoni tal-klijenti importati minn fajl. Biex timmodera volumi kbar b’mod effiċjenti, għaddi array direttament: l-API tipproċessa t-testijiet kollha f’talba waħda u tirritorna r-riżultati fl-istess ordni, u tippermettilek terġa’ tgħaqqadhom bl-indiċi.

def moderate_batch(texts: list[str]) -> list[dict]:
    """Timmodera testi multipli f'talba waħda."""
    results = []

    # L-API taċċetta array ta' 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

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

Reġistrazzjoni tal-Moderazzjoni (Logging)

Deċiżjoni ta’ moderazzjoni taffettwa utent, u qabel jew wara se jkollok bżonn tiġġustifikaha—kemm jekk għal klijent li jikkontesta blokk kif ukoll għal regolatur. Għalhekk, irreġistra sistematikament il-verdett, l-ID tal-utent, il-punteġġi, u estratt mit-test. Il-livell tal-log jiddistingwi ż-żewġ każijiet: warning għal kontenut immarkat (flagged), li jixraq reviżjoni umana, u info għall-bqija, li jħalli l-istatistika tiegħek.

import json
import logging
from datetime import datetime

logger = logging.getLogger("moderation")

def moderate_with_log(text: str, user_id: str = "anonymous") -> bool:
    """Jimmodera u jirreġistra r-riżultat għall-awditjar."""
    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

# Użu
is_ok = moderate_with_log("Test message", user_id="user-123")

Twissija finali qabel ma nimxu ‘l quddiem: il-moderazzjoni tikklassifika l-kontenut; ma tifhimx l-intenzjoni. Messaġġ perfettament polit li jipprova jagħmel jailbreak tal-assistent tiegħek jgħaddi minn dawn il-filtri kollha mingħajr ma jiġi mmarkat darba. Dak huwa s-suġġett tal-lezzjoni li jmiss.

Punti Ewlenin

  • L-API tal-Moderazzjoni hija bla ħlas—użaha sistematikament
  • Modera kemm l-inputs (kontenut tal-utent) KIF UKOLL l-outputs (risponsi tal-mudell)
  • Il-mudell omni-moderation-latest ikopri l-kategoriji kollha tal-kontenut
  • Irreġistra d-deċiżjonijiet kollha tal-moderazzjoni għall-awditjar
  • Uża l-ipproċessar f’lotti (batch) biex timmodera volumi kbar b’mod effiċjenti
  • Il-moderazzjoni tikkomplementa l-istruzzjonijiet tas-sistema; ma tissostitwixxihomx