OpenAI:n Moderation API
Tällä sivulla
Päivitetty 3. marraskuuta 2026 OpenAI:n Moderation-oppaan perusteella: taulukkoon lisättiin puuttunut
illicit-kategoria (sekäillicit/violent) sekä kuviin soveltuvat kategoriat. Lähde: Moderation.
Sisäänrakennettu moderointityökalu
OpenAI tarjoaa ilmaisen Moderation API:n, joka analysoi tekstiä tunnistaakseen mahdollisesti haitallista sisältöä. Tämä on ensimmäinen puolustuslinja, joka kannattaa integroida mihin tahansa OpenAI:n malleja hyödyntävään sovellukseen. Et kuitenkaan ole rajoittunut vain tähän käyttötarkoitukseen: koska API hyväksyy raakatekstin syötteenä, voit käyttää sitä suodattamaan myös muihin malleihin menevää syötettä. Se, että palvelu on ilmainen, muuttaa ongelman lähestymistapaa. Tavalliset kompromissit – pitäisikö meidän moderoida jokaista pyyntöä vai vain epäilyttäviä? – menettävät merkityksensä, sillä jäljelle jäävä ainoa kustannus on viive.
Mitä API palauttaa
Peruskutsu mahtuu yhdelle riville; vastaus on se, mikä vaatii huomiota. API palauttaa kolme erillistä asiaa: OpenAI:n päätöstä kuvaavan flagged-totuusarvon, luettelon aktivoituneista kategorioista ja mikä tärkeintä, jatkuvat pistemäärät kategoriaa kohden. Nämä pistemäärät tekevät eron tuotantoympäristössä, sillä niiden avulla voit itse päättää, missä vedät rajan, sen sijaan että perisit yleiskäyttöön suunnitellun kynnyksen.
from openai import OpenAI
client = OpenAI()
def moderate_content(text: str) -> dict:
"""Analysoi tekstiä OpenAI:n Moderation API:n kautta."""
response = client.moderations.create(input=text)
result = response.results[0]
return {
"blocked": result.flagged,
"categories": {
cat: flagged
for cat, flagged in result.categories.__dict__.items()
if flagged
},
"scores": {
cat: round(score, 4)
for cat, score in result.category_scores.__dict__.items()
if score > 0.01
},
}
# Testaa eri sisältötyypeillä
examples = [
"How do I bake a chocolate cake?",
"I will kill you if you don't answer me",
"Explain how AES encryption works",
]
for text in examples:
result = moderate_content(text)
status = "BLOCKED" if result["blocked"] else "OK"
print(f"{status} : {text[:50]}...")
if result["categories"]:
print(f" Categories : {list(result['categories'].keys())}")
Kolme testiesimerkkiä eivät ole satunnaisia: ensimmäisen pitäisi läpäistä suodatus, toinen pitäisi estää, ja kolmas – täysin legitiimi tekninen kysymys – näyttää, miten putkesi käyttäytyy kohdatessaan turvallisuussanastoa. Tämä on juuri sitä pyyntötyyppiä, jota kyberturvatiimi käsittelee päivittäin.
Havaitut kategoriat
API luokittelee ongelmallista sisältöä useilla akselilla, joista kukin vastaa erityyppistä haittaa.
| Category | Description |
|---|---|
| harassment | Harassment, threats, intimidation |
| hate | Hate speech based on identity |
| illicit | Advice or instructions for committing illicit acts |
| self-harm | Self-harm, suicide |
| sexual | Explicit sexual content |
| violence | Graphic violence, threats |
Jokaisella kategorialla on myös alakategorioita (esim. harassment/threatening, illicit/violent, violence/graphic) tarkempaa suodatusta varten. Mallilla omni-moderation-latest vain self-harm muunnelmineen, sexual ja violence (mukaan lukien violence/graphic) soveltuvat myös kuviin; muut kategoriat koskevat vain tekstiä. Tämä granulaarisuus säästää sinut karkeilta kompromisseilta: foorumin moderointialusta saattaa haluta estää harassment/threatening-sisällön mutta sietää pelkkää harassment-sisältöä, joka kattaa monet tavalliset kiistat.
Kun sinun tarvitsee käsitellä suuria määriä – esimerkiksi keskusteluhistorian jälkikäteisanalyysi – API hyväksyy listan ja palauttaa tuloksen jokaiselle alkiolle, mikä välttää useita verkkokutsuja.
def moderate_batch(messages: list[str]) -> list[dict]:
"""Moderoi useita viestejä yhdessä kutsussa."""
response = client.moderations.create(input=messages)
results = []
for i, result in enumerate(response.results):
results.append({
"index": i,
"text": messages[i][:50],
"blocked": result.flagged,
"max_score": max(
score
for score in result.category_scores.__dict__.values()
),
})
return results
Putken molempien päiden moderointi
Yleinen virhe on moderoida vain syötteitä. Tämä perustuu väärään intuitioon: jos saapuva viesti on hyväksyttävä, myös vastaus on sellainen. Malli voi kuitenkin tuottaa ongelmallista sisältöä neutraalista pyynnöstä, erityisesti kun se nojaa haettuihin dokumentteihin, joiden sisältöä kukaan ei ole varmistanut. Alla oleva luokka soveltaa siksi samaa käsittelyä molempiin suuntiin lisäten mukautetun kynnyksen, joka kiristää API:n oletuspäätöstä.
class ModerationPipeline:
"""Syötteen ja tulosteen moderointiputki LLM-sovellukselle."""
def __init__(self, custom_threshold: float = 0.7):
self.client = OpenAI()
self.threshold = custom_threshold
def moderate_input(self, message: str) -> tuple[bool, dict]:
"""Moderoi viestin ENNEN lähettämistä mallille."""
result = self.client.moderations.create(input=message).results[0]
scores = result.category_scores.__dict__
high_categories = {
cat: score for cat, score in scores.items() if score > self.threshold
}
blocked = result.flagged or bool(high_categories)
return blocked, {"flagged_api": result.flagged, "custom_categories": high_categories}
def moderate_output(self, response: str) -> tuple[bool, dict]:
"""Moderoi mallin vastauksen ENNEN lähettämistä käyttäjälle."""
return self.moderate_input(response)
def process_message(self, user_message: str, system_prompt: str) -> str:
"""Täysi putki: syötteen moderointi, LLM, tulosteen moderointi."""
# Vaihe 1: moderoi syöte
input_blocked, details = self.moderate_input(user_message)
if input_blocked:
return "Viestiäsi ei voida käsitellä. Muotoile se uudelleen."
# Vaihe 2: kutsu mallia
response = self.client.chat.completions.create(
model="gpt-5.6-sol",
messages=[
{"role": "system", "content": system_prompt},
{"role": "user", "content": user_message},
],
)
model_response = response.choices[0].message.content
# Vaihe 3: moderoi tuloste
output_blocked, _ = self.moderate_output(model_response)
if output_blocked:
return "Vastaus suodatettiin vaatimustenmukaisuussyistä."
return model_response
# Käyttö
pipeline = ModerationPipeline(custom_threshold=0.5)
response = pipeline.process_message(
"How do I protect my application against SQL injections?",
"You are an expert in defensive cybersecurity."
)
print(response)
Mitä tämä API ei tee
Sen tärkein rajoitus on myös väärinymmärretyin: se ei havaitse kehoteinjektioita (prompt injection). Kohtelias viesti, joka on sisällöllisesti täysin harmiton, mutta pyytää mallia ignoromaan ohjeensa, läpäisee suodatuksen laukaisematta yhtäkään kategoriaa. Sen odottaminen suojaavan manipuloinnilta on kuin asentaisi savuilmaisimen toivoen sen pysäyttävän murtovarkaat.
Väärät positiiviset tulokset ovat toinen rajoitus, mikä on erityisen arkaluonteista turvallisuus- tai lääketieteellisissä konteksteissa, joissa uhkien kuvaaminen on osa työtä. Jokaiseen pyyntöön lisätään ylimääräinen verkkokutsu, mikä on merkittävää tavoiteltaessa reaaliaikaisia vastauksia. Havaitseminen on luotettavampaa englanniksi kuin muilla kielillä, mikä on hyökkääjien hyvin tuntema sokea piste. Lopuksi kategoriat ja kynnykset kehittyvät päivitysten myötä: kuusi kuukautta sitten kalibroitu sarja ansaitsee uudelleentarkistuksen.
Nämä rajat sanelevat työkalun käytön. Moderoi molempiin suuntiin, säädä kynnysarvoja kategoria kerrallaan globaalin säädön sijaan ja yhdistä se järjestelmällisesti muihin kerroksiin – injektiodetektioon, liiketoimintalogiikan suodatukseen – joita seuraavat oppitunnit käsittelevät. Lokita tulokset, sillä omien värien positiivisten tulosten havainnointi on tapa oppia, mihin liukusäätimiä kannattaa siirtää. Suunnittele myös tilanne, jossa API ei ole saatavilla: päätä nyt, kun asiat ovat rauhallisia, pitäisikö sovelluksesi estää liikenne oletuksena vai päästää se läpi, sen sijaan että huomaisit tämän käyttäytymisen kesken häiriötilanteen.
Keskeiset asiat
- Moderation API on ilmainen, nopea ja helppo integroida
- Se havaitsee loukkaavaa sisältöä, mutta ei injektioita tai jailbreakeja
- Syöte-malli-tuloste-putki on moduloitava molemmista päistä
- Oletuskynnykset sopivat harvoin sellaisenaan – mukauta ne omaan kontekstiisi
- Se on yksi kerros muiden joukossa, ei koskaan ainoa puolustuslinja