Moderation

Moderation برای ارزیابی ایمنی و سیاست محتوایی متن استفاده می‌شود. این API کمک می‌کند پیش از ادامه پردازش، نمایش به کاربر یا ارسال متن به مدل‌های دیگر، ریسک‌های محتوایی را تشخیص دهید.

POST /v1/moderations

این API چه زمانی لازم است؟

از Moderation استفاده کنید وقتی محصول شما:

• ورودی آزاد از کاربر می‌گیرد.
• پاسخ مدل را بدون بازبینی انسانی نمایش می‌دهد.
• با محتوای تولیدشده کاربر کار می‌کند.
• عامل یا جریان خودکار دارد و باید جلوی ورودی پرریسک را بگیرد.
• برای سیاست محتوایی، گزارش‌پذیری و کنترل داخلی نیاز به تصمیم قابل ثبت دارد.

Moderation جای گاردریل‌ها را نمی‌گیرد. این API محتوا را ارزیابی می‌کند؛ گاردریل‌ها می‌توانند تصمیم اعمال سیاست، توقف، نشانه‌گذاری یا اصلاح را در مسیر درخواست مدیریت کنند.

شروع سریع

Python

import requests

response = requests.post(
    "https://YOUR_WORKSPACE.godarai.ir/v1/moderations",
    headers={
        "Authorization": "Bearer YOUR_GODARAI_TOKEN",
        "Content-Type": "application/json",
    },
    json={
  "model": "openai:default:omni-moderation-latest",
  "input": "این متن را از نظر محتوای پرریسک بررسی کن."
},
    timeout=60,
)

response.raise_for_status()
print(response.json())

NodeJS

const response = await fetch("https://YOUR_WORKSPACE.godarai.ir/v1/moderations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_GODARAI_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "openai:default:omni-moderation-latest",
  "input": "این متن را از نظر محتوای پرریسک بررسی کن."
}),
});

if (!response.ok) {
  throw new Error(`Request failed with status ${response.status}`);
}

const data = await response.json();
console.log(data);

REST API

curl --request POST "https://YOUR_WORKSPACE.godarai.ir/v1/moderations" \
  --header "Authorization: Bearer YOUR_GODARAI_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "openai:default:omni-moderation-latest",
  "input": "این متن را از نظر محتوای پرریسک بررسی کن."
}'

OpenAI Python SDK

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_GODARAI_TOKEN",
    base_url="https://YOUR_WORKSPACE.godarai.ir/v1",
)

response = client.moderations.create(
    "model": "openai:default:omni-moderation-latest",
    input="این متن را از نظر محتوای پرریسک بررسی کن."

)

print(response)

OpenAI NodeJS SDK

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_GODARAI_TOKEN",
  baseURL: "https://YOUR_WORKSPACE.godarai.ir/v1",
});

const response = await client.moderations.create({
  "model": "openai:default:omni-moderation-latest",
  "input": "این متن را از نظر محتوای پرریسک بررسی کن."
});

console.log(response);

مدل باید از نوع moderation باشد و در فضای کاری شما مجاز شده باشد. پس از اجرا، نتیجه را در پاسخ API و گزارش رخدادهای گدارAI می‌توانید پیگیری کنید.

ورودی معتبر

ورودی معمولاً یک رشته یا آرایه‌ای از رشته‌هاست:

Python

import requests

response = requests.post(
    "https://YOUR_WORKSPACE.godarai.ir/v1/moderations",
    headers={
        "Authorization": "Bearer YOUR_GODARAI_TOKEN",
        "Content-Type": "application/json",
    },
    json={
  "model": "openai:default:omni-moderation-latest",
  "input": [
    "متن اول برای بررسی",
    "متن دوم برای بررسی"
  ]
},
    timeout=60,
)

response.raise_for_status()
print(response.json())

NodeJS

const response = await fetch("https://YOUR_WORKSPACE.godarai.ir/v1/moderations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_GODARAI_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "openai:default:omni-moderation-latest",
  "input": [
    "متن اول برای بررسی",
    "متن دوم برای بررسی"
  ]
}),
});

if (!response.ok) {
  throw new Error(`Request failed with status ${response.status}`);
}

const data = await response.json();
console.log(data);

REST API

curl --request POST "https://YOUR_WORKSPACE.godarai.ir/v1/moderations" \
  --header "Authorization: Bearer YOUR_GODARAI_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "openai:default:omni-moderation-latest",
  "input": [
    "متن اول برای بررسی",
    "متن دوم برای بررسی"
  ]
}'

OpenAI Python SDK

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_GODARAI_TOKEN",
    base_url="https://YOUR_WORKSPACE.godarai.ir/v1",
)

response = client.moderations.create(
    "model": "openai:default:omni-moderation-latest",
    input=[
        "متن اول برای بررسی",
        "متن دوم برای بررسی"
      ]

)

print(response)

OpenAI NodeJS SDK

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_GODARAI_TOKEN",
  baseURL: "https://YOUR_WORKSPACE.godarai.ir/v1",
});

const response = await client.moderations.create({
  "model": "openai:default:omni-moderation-latest",
  "input": [
    "متن اول برای بررسی",
    "متن دوم برای بررسی"
  ]
});

console.log(response);

اگر آرایه می‌فرستید، ترتیب خروجی را با ترتیب ورودی نگه دارید تا بدانید هر نتیجه به کدام متن مربوط است.

چه چیزهایی را با Moderation نفرستیم؟

این API برای بررسی متن طراحی شده است، نه تولید پاسخ یا اجرای ابزار. بنابراین پارامترهایی مثل این‌ها را ارسال نکنید:

• messages
• stream
• temperature
• max_tokens
• tools
• tool_choice
• encoding_format
• dimensions

نکته آموزشی: اگر می‌خواهید قبل از چت، متن کاربر را بررسی کنید، اول Moderation را روی متن کاربر اجرا کنید و فقط در صورت مجاز بودن، آن را به Chat Completions بفرستید.

شکل پاسخ

{
  "id": "modr_1",
  "model": "omni-moderation-latest",
  "results": [
    {
      "flagged": false,
      "categories": {
        "hate": false,
        "violence": false
      },
      "category_scores": {
        "hate": 0.001,
        "violence": 0.002
      }
    }
  ]
}

فیلدهای مهم

فیلد	معنی
flagged	اگر true باشد، متن در یکی از دسته‌های حساس نشانه‌گذاری شده است.
categories	نتیجه درست یا نادرست برای هر دسته محتوایی.
category_scores	امتیاز عددی هر دسته؛ برای طراحی آستانه داخلی کاربرد دارد.

همیشه فقط به flagged اکتفا نکنید. در محصولات حساس، امتیاز دسته‌ها را ذخیره و با سیاست داخلی خود تطبیق دهید.

جایگاه در مسیر محصول

دو الگوی رایج وجود دارد:

• بررسی ورودی: متن کاربر را قبل از ارسال به مدل بررسی کنید.
• بررسی خروجی: پاسخ مدل را قبل از نمایش به کاربر بررسی کنید.

برای محصولات عمومی، ترکیب هر دو الگو معمولاً مطمئن‌تر است. برای محصولات داخلی، سطح کنترل را بر اساس ریسک داده، نوع کاربران و سیاست سازمان تعیین کنید.

خطاهای رایج

• model is required: شناسه مدل ارسال نشده است.
• input is required and must be a non-empty string or a non-empty array of strings: ورودی خالی یا نامعتبر است.
• input array items must be non-empty strings: یکی از متن‌های آرایه خالی است.
• stream is not supported for moderations: پاسخ جریانی برای این API معتبر نیست.
• Model access denied or unsupported for moderations: مدل انتخابی در دسترسی شما مجاز نیست یا از نوع Moderation نیست.

جمع‌بندی

Moderation یک لایه ارزیابی محتوایی قابل ثبت و قابل بررسی است. آن را در کنار گاردریل‌ها و سیاست داخلی محصول خود استفاده کنید تا مسیرهای متنی گدارAI فقط پاسخ‌گو نباشند، بلکه قابل کنترل و قابل اعتماد هم بمانند.