تحلیل متن: احساسات، اسپم و زبان در یک فراخوانی

تحلیل متن Discuse در یک درخواست POST https://api.discuse.com/api/v2/check، پیام را از نظر سمی‌بودن، اسپم و زبان ارزیابی می‌کند. متن خود را در content.text بفرستید، با هدر X-API-Key احراز هویت کنید، و نتایج هر بررسی را از بخش results بخوانید.

اندپوینت متن چه چیزهایی را بررسی می‌کند؟

یک فراخوانی /api/v2/check می‌تواند سه بررسی متنی را هم‌زمان اجرا کند:

• احساسات: امتیازدهی به سمی‌بودن، ناسزا، تهدید و توهین، به‌همراه نتیجه‌گیری درباره منفی/سمی بودن.
• اسپم: اسپم تبلیغاتی، کلاهبرداری‌ها و متن تولیدشده توسط ربات، که به‌صورت یک label به‌همراه امتیاز اطمینان برگردانده می‌شود.
• زبان: کد زبان تشخیص‌داده‌شده، با امکان اعمال محدودیت بر اساس زبان مورد انتظار.

هر بررسی فقط زمانی اجرا می‌شود که فعال شده باشد؛ یا در تنظیمات پروژه شما، یا از طریق شیء settings در همان درخواست.

چطور اندپوینت متن را فراخوانی کنم؟

curl -X POST https://api.discuse.com/api/v2/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "content": {
      "text": "This is an example message to analyze"
    },
    "settings": {
      "check_sentiment": true,
      "check_spam": true,
      "check_language": true
    }
  }'

content.text تا ۱۰٬۰۰۰ نویسه را می‌پذیرد. کلید API را می‌توان در هدر X-API-Key یا به‌صورت api_key در بدنه درخواست ارسال کرد.

پاسخ

{
  "has_violations": false,
  "cached": false,
  "message": "Content appears safe",
  "results": {
    "hits": false,
    "sentiment": {
      "hit": false,
      "is_negative": false,
      "is_toxic": false,
      "score": 0.04,
      "toxicity": 0.02,
      "toxic": 0.02,
      "profanity": 0.01,
      "threat": 0.00,
      "insult": 0.03
    },
    "spamfinder": {
      "text": "This is an example message to analyze",
      "label": "ham",
      "confidence": 0.12,
      "is_spam": false,
      "hit": false
    },
    "language": {
      "language": "en",
      "confidence": 0.98,
      "hit": false
    }
  },
  "usage": {
    "api_requests_used": 41,
    "api_requests_limit": 5000,
    "api_requests_remaining": 4959
  }
}

has_violations بازتابی از results.hits است: وقتی هرکدام از بررسی‌های فعال‌شده پرچم hit خود را فعال کند، مقدار آن true می‌شود. processing_time_ms فقط زمانی در پاسخ وجود دارد که زمان‌سنجی در تنظیمات پروژه شما فعال باشد.

تحلیل احساسات

بررسی احساسات هم یک نتیجه‌گیری کلی و هم امتیازهای جداگانه برای هر بُعد را از 0.0 تا 1.0 برمی‌گرداند.

فیلد	نوع	معنی
is_negative	bool	پیام منفی به نظر می‌رسد
is_toxic	bool	پیام از آستانه سمی‌بودن عبور کرده است
score	number	امتیاز کلی احساس/شدت
toxicity	number	میزان اطمینان از سمی‌بودن (0.0–1.0)
toxic	number	میزان اطمینان از سمی‌بودن (نام مستعار قدیمی برای toxicity)
profanity	number	میزان اطمینان از وجود زبان صریح یا ناسزا
threat	number	میزان اطمینان از وجود تهدید به آسیب
insult	number	میزان اطمینان از وجود حمله شخصی
hit	bool	زمانی True است که پیام آستانه‌های احساسات را نقض کند
message	string	توضیح اختیاری

چطور امتیاز احساسات را تفسیر کنم؟

امتیاز نشان‌دهنده میزان اطمینان مدل است که آن بُعد درباره متن صدق می‌کند:

• 0.0 – 0.3: پایین، معمولاً امن.
• 0.3 – 0.6: متوسط، ممکن است نیازمند بازبینی باشد.
• 0.6 – 0.8: بالا، احتمالاً مشکل‌ساز.
• 0.8 – 1.0: بسیار بالا، تقریباً قطعاً ناقض قوانین.

مثال: محتوای سمی

درخواست:

{
  "content": {
    "text": "You're the worst person I've ever met. I hate everything about you."
  },
  "settings": { "check_sentiment": true }
}

پاسخ:

{
  "has_violations": true,
  "results": {
    "hits": true,
    "sentiment": {
      "hit": true,
      "is_negative": true,
      "is_toxic": true,
      "score": 0.91,
      "toxicity": 0.89,
      "toxic": 0.89,
      "profanity": 0.15,
      "threat": 0.22,
      "insult": 0.95
    }
  }
}

تشخیص اسپم

بررسی اسپم متن را طبقه‌بندی می‌کند و یک label واحد به‌همراه امتیاز اطمینان برمی‌گرداند. این بررسی الگوهایی را شناسایی می‌کند که از فهرست‌های مسدودسازی کلمات کلیدی عبور می‌کنند: اسپم تبلیغاتی، کلاهبرداری و فیشینگ، و متن تولیدشده توسط ربات.

مثال: محتوای اسپم

درخواست:

{
  "content": {
    "text": "CONGRATULATIONS! You've won $10,000! Click here to claim: www.fake-prize.com"
  },
  "settings": { "check_spam": true }
}

پاسخ:

{
  "has_violations": true,
  "results": {
    "hits": true,
    "spamfinder": {
      "text": "CONGRATULATIONS! You've won $10,000! Click here to claim: www.fake-prize.com",
      "label": "spam",
      "confidence": 0.97,
      "is_spam": true,
      "hit": true
    }
  }
}

is_spam نتیجه خام مدل است (مدل متن را به‌عنوان اسپم برچسب‌گذاری کرده است). hit تصمیمی است که آستانه‌ها را در نظر می‌گیرد: فقط زمانی true می‌شود که is_spam درست باشد و confidence از آستانه اسپم پروژه شما عبور کند. برای مدیریت محتوا، معیار را hit قرار دهید، نه is_spam. برای جزئیات، راهنمای تشخیص اسپم را ببینید.

تشخیص زبان

برای تشخیص کد زبان content.text، مقدار check_language را تنظیم کنید. نتیجه در results.language.language قرار می‌گیرد (برای مثال "en"، "fr"، "es").

درخواست:

{
  "content": { "text": "Bonjour, comment allez-vous aujourd'hui?" },
  "settings": { "check_language": true }
}

پاسخ:

{
  "results": {
    "language": {
      "language": "fr",
      "confidence": 0.99,
      "hit": false
    }
  }
}

برای علامت‌گذاری محتوایی که به زبان مورد انتظار شما نیست، expected_language را تنظیم کنید. وقتی زبان تشخیص‌داده‌شده متفاوت باشد، language.hit برابر با true می‌شود و expected/detected مقداردهی می‌شوند:

{
  "content": { "text": "Hola, cómo estás?" },
  "settings": { "check_language": true, "expected_language": "en" }
}

{
  "results": {
    "language": {
      "language": "es",
      "detected": "es",
      "expected": "en",
      "confidence": 0.95,
      "hit": true
    }
  }
}

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

کدام بررسی‌ها را می‌توانم روشن یا خاموش کنم؟

شیء اختیاری settings پیش‌فرض‌های پروژه شما را فقط برای یک درخواست بازنویسی می‌کند. گزینه‌های مرتبط با متن عبارت‌اند از:

تنظیم	نوع	اثر
check_sentiment	bool	اجرای تحلیل احساسات
check_spam	bool	اجرای تشخیص اسپم
check_language	bool	اجرای تشخیص زبان
check_badwords	bool	اجرای فهرست مسدودسازی واژه‌های نامناسب
expected_language	string	کد زبانی که باید اعمال شود (مثلاً "en")

{
  "content": { "text": "Your message here" },
  "settings": {
    "check_sentiment": true,
    "check_spam": true,
    "check_language": true,
    "expected_language": "en"
  }
}

محدودیت‌های مصرف

تشخیص احساسات، اسپم و زبان از سهمیه تحلیل احساساتِ هر پلن استفاده می‌کنند:

پلن	تحلیل احساسات در ماه
Basic	۱٬۰۰۰
Gold	۵٬۰۰۰
Platinum	۱۵٬۰۰۰
Ultimate	۳۰٬۰۰۰

پاسخ‌های کش‌شده از سهمیه شما کم نمی‌شوند. شیء usage در هر پاسخ، مقادیر api_requests_used، api_requests_limit و api_requests_remaining را گزارش می‌کند.

بهترین روش‌ها

آستانه‌ها را برای هر پلتفرم جداگانه تنظیم کنید

برای مخاطبان مختلف، حد آستانه‌های متفاوتی برای احساسات اعمال کنید:

const THRESHOLDS = {
  kids:    { toxicity: 0.3, profanity: 0.2, threat: 0.2, insult: 0.3 },
  general: { toxicity: 0.5, profanity: 0.5, threat: 0.4, insult: 0.5 },
  adult:   { toxicity: 0.7, profanity: 0.8, threat: 0.5, insult: 0.7 }
};

زمینه را در نظر بگیرید

محتوای بالینی، روزنامه‌نگارانه و داستانی ممکن است به‌طور موجه امتیازهای سمی‌بودن و ناسزا را فعال کند. برای موارد مرزی، امتیازدهی خودکار را با بازبینی انسانی ترکیب کنید:

const sentiment = result.results.sentiment;
if (sentiment.toxicity > 0.9) {
  await removeContent(contentId);       // high confidence: auto-remove
} else if (sentiment.toxicity > 0.5) {
  await queueForReview(contentId);      // borderline: human review
} else {
  await approveContent(contentId);
}

نمونه‌های یکپارچه‌سازی

JavaScript

async function analyzeText(text) {
  const response = await fetch('https://api.discuse.com/api/v2/check', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.DISCUSE_API_KEY
    },
    body: JSON.stringify({
      content: { text },
      settings: { check_sentiment: true, check_spam: true, check_language: true }
    })
  });

  return response.json();
}

const result = await analyzeText('Hello, how are you?');
console.log(result.has_violations); // false

Python

import os
import requests

def analyze_text(text):
    response = requests.post(
        'https://api.discuse.com/api/v2/check',
        headers={
            'Content-Type': 'application/json',
            'X-API-Key': os.environ['DISCUSE_API_KEY']
        },
        json={
            'content': {'text': text},
            'settings': {
                'check_sentiment': True,
                'check_spam': True,
                'check_language': True
            }
        }
    )
    return response.json()

result = analyze_text('Hello, how are you?')
print(result['has_violations'])  # False

آماده‌اید تحلیل متن را پیاده‌سازی کنید؟ برای راه‌اندازی گام‌به‌گام، راهنمای شروع سریع را ببینید.