تحليل النصوص: المشاعر والرسائل غير المرغوب فيها واللغة في استدعاء واحد

يُقيّم تحليل النصوص من 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 ما يصل إلى 10,000 حرف. يمكن إرسال مفتاح 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: إذ تكون true عندما يفعّل أي فحص مُمكّن علامة hit الخاصة به. لا يظهر 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. راجع دليل اكتشاف الرسائل غير المرغوب فيها لمزيد من التفاصيل.

اكتشاف اللغة

اضبط check_language لاكتشاف رمز لغة content.text. تظهر النتيجة في 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	1,000
Gold	5,000
Platinum	15,000
Ultimate	30,000

لا تُحتسب الاستجابات المخزنة مؤقتًا ضمن حصتك. يبلّغ كائن 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

هل أنت مستعد لتنفيذ تحليل النصوص؟ راجع دليل البدء السريع لإعداد خطوة بخطوة.