API_DOCUMENTATION.md

📡 وثائق API - Whisper Text Processor

دليل شامل لاستخدام API معالج النصوص المتكامل

🌐 معلومات عامة

Base URL

https://YOUR_USERNAME-whisper-text-processor.hf.space

Content-Type

application/json

Authentication

لا يتطلب API مصادقة حالياً (قد يتغير في المستقبل)

📋 نقاط النهاية (Endpoints)

1. فحص حالة الخادم

GET /health

فحص حالة الخادم والتأكد من أن جميع المكونات تعمل بشكل صحيح.

المعاملات: لا توجد

الاستجابة:

{
  "status": "healthy",
  "message": "خادم معالج النصوص يعمل بشكل طبيعي",
  "processor_loaded": true
}

مثال:

curl -X GET "https://your-space.hf.space/health"

---

2. تصحيح النصوص

POST /correct-text

تصحيح النص المدخل باستخدام قاموس مرجعي مبني من النصوص المرجعية.

المعاملات:

{
  "text": "string",              // النص المراد تصحيحه (مطلوب)
  "reference_texts": ["string"], // قائمة النصوص المرجعية (مطلوب)
  "max_distance": 3,           // أقصى مسافة للتصحيح (اختياري)
  "threshold_freq": 1          // الحد الأدنى لتكرار الكلمة (اختياري)
}

الاستجابة:

{
  "success": true,
  "message": "تم تصحيح النص بنجاح",
  "data": {
    "original_text": "يحتاز غشاء الطبل",
    "corrected_text": "يهتز غشاء الطبل",
    "corrections": [
      {
        "original": "يحتاز",
        "corrected": "يهتز",
        "frequency": 4,
        "distance": 2
      }
    ],
    "corrections_count": 1
  }
}

مثال:

curl -X POST "https://your-space.hf.space/correct-text" \
     -H "Content-Type: application/json" \
     -d '{
       "text": "يحتاز غشاء الطبل تنتقل عظيمات السماء",
       "reference_texts": [
         "يهتز غشاء الطبل تنتقل عظيمات السمع الاهتزازات",
         "يهتز غشاء النافذة البيضية يهتز اللمف الخارجي"
       ],
       "max_distance": 3,
       "threshold_freq": 1
     }'

---

3. مقارنة النصوص

POST /compare-texts

مقارنة نصين وحساب معدلات الخطأ مع إظهار الاختلافات بصرياً.

المعاملات:

{
  "reference_text": "string",    // النص المرجعي (مطلوب)
  "transcribed_text": "string"   // النص المستخرج (مطلوب)
}

الاستجابة:

{
  "success": true,
  "message": "تم مقارنة النصوص بنجاح",
  "data": {
    "wer": 0.3,
    "cer": 0.076,
    "wer_percentage": "30.00%",
    "cer_percentage": "7.69%",
    "html_diff": "<span>HTML مع الاختلافات المظللة</span>",
    "reference_words": 10,
    "transcribed_words": 10,
    "word_differences": 0
  }
}

مثال:

curl -X POST "https://your-space.hf.space/compare-texts" \
     -H "Content-Type: application/json" \
     -d '{
       "reference_text": "يهتز غشاء الطبل تنتقل عظيمات السمع",
       "transcribed_text": "يحتاز غشاء الطبل تنتقل عظيمات السماء"
     }'

---

4. معالجة الملفات الصوتية

POST /process-audio

معالجة شاملة للملف الصوتي تتضمن تحويل الصوت إلى نص، التصحيح، والمقارنة.

المعاملات (multipart/form-data):

• audio_file: ملف صوتي (مطلوب)
• reference_text: النص المرجعي (مطلوب)
• reference_texts: نصوص مرجعية إضافية كـ JSON string (اختياري)
• max_distance: أقصى مسافة للتصحيح (اختياري، افتراضي: 3)
• threshold_freq: الحد الأدنى لتكرار الكلمة (اختياري، افتراضي: 1)

الاستجابة:

{
  "success": true,
  "message": "تم معالجة الملف الصوتي بنجاح",
  "data": {
    "audio_path": "/path/to/audio.wav",
    "reference_text": "النص المرجعي",
    "original_transcription": "النص المستخرج الأصلي",
    "corrected_transcription": "النص المصحح",
    "corrections": [...],
    "original_metrics": {
      "wer": 0.15,
      "cer": 0.08,
      "wer_percentage": "15.00%",
      "cer_percentage": "8.00%"
    },
    "corrected_metrics": {
      "wer": 0.0,
      "cer": 0.0,
      "wer_percentage": "0.00%",
      "cer_percentage": "0.00%"
    },
    "improvement": {
      "wer_improvement": 0.15,
      "cer_improvement": 0.08
    },
    "timestamps": [...]
  }
}

مثال:

curl -X POST "https://your-space.hf.space/process-audio" \
     -F "audio_file=@audio.wav" \
     -F "reference_text=يهتز غشاء الطبل تنتقل عظيمات السمع" \
     -F "reference_texts=[\"نص إضافي 1\", \"نص إضافي 2\"]" \
     -F "max_distance=3" \
     -F "threshold_freq=1"

---

5. إنشاء تقرير HTML

POST /generate-report

إنشاء تقرير HTML شامل يحتوي على جميع نتائج المعالجة مع تصميم تفاعلي.

المعاملات (multipart/form-data):

• audio_file: ملف صوتي (مطلوب)
• reference_text: النص المرجعي (مطلوب)
• reference_texts: نصوص مرجعية إضافية كـ JSON string (اختياري)

الاستجابة:

<!DOCTYPE html>
<html dir="rtl" lang="ar">
<head>
    <meta charset="UTF-8">
    <title>تقرير معالجة النصوص</title>
    <!-- CSS styles -->
</head>
<body>
    <!-- تقرير HTML كامل مع النتائج والإحصائيات -->
</body>
</html>

مثال:

curl -X POST "https://your-space.hf.space/generate-report" \
     -F "audio_file=@audio.wav" \
     -F "reference_text=يهتز غشاء الطبل" \
     -o report.html

---

🔧 أكواد الاستجابة

نجح الطلب

• 200 OK: تم تنفيذ الطلب بنجاح

أخطاء العميل

• 400 Bad Request: معاملات غير صحيحة أو مفقودة
• 422 Unprocessable Entity: بيانات غير صالحة

أخطاء الخادم

• 500 Internal Server Error: خطأ في الخادم أو المعالج

📝 أمثلة متقدمة

1. معالجة متعددة اللغات

import requests

# تصحيح نص عربي
response = requests.post(
    "https://your-space.hf.space/correct-text",
    json={
        "text": "السلام عليكم ورحمة الله وبركاته",
        "reference_texts": ["السلام عليكم ورحمة الله وبركاته"]
    }
)

2. معالجة دفعية

import asyncio
import aiohttp

async def process_multiple_texts(texts, reference_texts):
    async with aiohttp.ClientSession() as session:
        tasks = []
        for text in texts:
            task = session.post(
                "https://your-space.hf.space/correct-text",
                json={
                    "text": text,
                    "reference_texts": reference_texts
                }
            )
            tasks.append(task)
        
        responses = await asyncio.gather(*tasks)
        return [await r.json() for r in responses]

3. تحليل الأداء

import time
import requests

def benchmark_api():
    start_time = time.time()
    
    response = requests.post(
        "https://your-space.hf.space/compare-texts",
        json={
            "reference_text": "نص طويل للاختبار...",
            "transcribed_text": "نص طويل مع أخطاء..."
        }
    )
    
    end_time = time.time()
    processing_time = end_time - start_time
    
    print(f"وقت المعالجة: {processing_time:.2f} ثانية")
    return response.json()

🛡️ أفضل الممارسات

1. إدارة الأخطاء

import requests
from requests.exceptions import RequestException

def safe_api_call(url, data):
    try:
        response = requests.post(url, json=data, timeout=30)
        response.raise_for_status()
        return response.json()
    except RequestException as e:
        print(f"خطأ في API: {e}")
        return None

2. تحسين الأداء

# استخدام session للطلبات المتعددة
session = requests.Session()
session.headers.update({"Content-Type": "application/json"})

# إعادة استخدام الاتصال
for text in texts:
    response = session.post(url, json={"text": text, ...})

3. التعامل مع الملفات الكبيرة

# رفع ملفات صوتية كبيرة
with open("large_audio.wav", "rb") as f:
    files = {"audio_file": f}
    data = {"reference_text": "النص المرجعي"}
    
    response = requests.post(
        "https://your-space.hf.space/process-audio",
        files=files,
        data=data,
        timeout=300  # مهلة أطول للملفات الكبيرة
    )

🔍 استكشاف الأخطاء

أخطاء شائعة وحلولها

1. خطأ 400 - Bad Request

{
  "detail": "يجب أن يكون الملف من نوع صوتي"
}

الحل: تأكد من أن الملف المرفوع هو ملف صوتي صالح (.wav, .mp3, .m4a, إلخ)

2. خطأ 500 - Internal Server Error

{
  "detail": "معالج النصوص غير متاح"
}

الحل: الخادم قيد التحميل أو إعادة التشغيل، حاول مرة أخرى بعد دقائق

3. خطأ Timeout

الحل: زيادة مهلة الطلب أو تقليل حجم الملف الصوتي

📊 حدود الاستخدام

الحدود الحالية

• حجم الملف الصوتي: حتى 25 MB
• طول النص: حتى 10,000 حرف
• عدد النصوص المرجعية: حتى 50 نص
• معدل الطلبات: 100 طلب/دقيقة

نصائح للتحسين

• استخدم ملفات صوتية مضغوطة
• قسم النصوص الطويلة إلى أجزاء
• استخدم التخزين المؤقت للنتائج المتكررة

---

ملاحظة: هذه الوثائق قابلة للتحديث. راجع الإصدار الأحدث على GitHub.