Hugging Face's logo

Spaces:
DrAbdulmalek
/
OmniFile-Processor
Running

App Files Community
OmniFile-Processor / docs /USER_GUIDE.md
Dr. Abdulmalek
deploy: OmniFile AI Processor v4.3.0
900df0b
preview code
|
raw
history blame contribute delete
35.4 kB

دليل المستخدم - OmniFile AI Processor v2.1

User Guide - OmniFile AI Processor v2.1

نظام ذكاء اصطناعي متكامل لمعالجة الملفات والنصوص والخط اليدوي Integrated AI System for File Processing, Text Analysis, and Handwriting Recognition

المحتويات / Table of Contents

  1. متطلبات النظام / System Requirements
  2. التثبيت / Installation
  3. التشغيل / Running
  4. الميزات الرئيسية / Key Features
  5. اختصارات لوحة المفاتيح / Keyboard Shortcuts
  6. حل المشكلات / Troubleshooting
  7. أسئلة شائعة / FAQ

1. متطلبات النظام / System Requirements

المتطلبات الأساسية / Core Requirements

المتطلب / Requirement الحد الأدنى / Minimum الموصى به / Recommended
Python / Python Version 3.8+ 3.11+
الذاكرة (RAM) / Memory 4 GB 8 GB+
مساحة القرص / Disk Space 5 GB (للنماذج) 10 GB+
نظام التشغيل / OS Linux / Windows / macOS Ubuntu 22.04+ / Manjaro / Arch
المعالج / CPU x86_64 dual-core x86_64 quad-core+

متطلبات GPU (اختياري) / GPU Requirements (Optional)

المتطلب / Requirement المواصفات / Specification
كرت الشاشة / GPU NVIDIA GPU (CUDA Compute Capability 6.0+)
CUDA / CUDA Toolkit 11.8+ (12.1+ موصى به)
VRAM / Video Memory 4 GB (لـ TrOCR-base)
cuDNN / cuDNN 8.x+

ملاحظة / Note: يعمل النظام بالكامل على CPU بدون أي مشكلة، لكن GPU يسرّع عمليات TrOCR و EasyOCR بشكل كبير. Note: The system works fully on CPU without issues. GPU significantly accelerates TrOCR and EasyOCR processing.

المتطلبات الاختيارية / Optional Dependencies

المكتبة / Library الغرض / Purpose التثبيت / Install
Tesseract OCR محرك OCR احتياطي خفيف apt install tesseract-ocr tesseract-ocr-ara tesseract-ocr-eng
Redis المعالجة غير المتزامنة (Celery) apt install redis-server
ONNX Runtime تسريع الاستدلال pip install onnxruntime أو onnxruntime-gpu
Presidio فحص البيانات الحساسة المتقدم pip install presidio-analyzer presidio-anonymizer

2. التثبيت / Installation

2.1 التثبيت المحلي / Local Installation 

# 1. استنساخ المشروع / Clone the repository
git clone https://github.com/DrAbdulmalek/OmniFile_Processor.git
cd OmniFile_Processor

# 2. إنشاء بيئة افتراضية (موصى به) / Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate      # Linux/macOS
# venv\Scripts\activate       # Windows

# 3. تثبيت الحزم / Install dependencies
pip install -r requirements.txt

# 4. تثبيت Tesseract (اختياري) / Install Tesseract (optional)
# Ubuntu/Debian:
sudo apt install tesseract-ocr tesseract-ocr-ara tesseract-ocr-eng
# macOS:
brew install tesseract

2.2 التثبيت على Google Colab / Google Colab Installation 

# 1. استنساخ المشروع / Clone the project
!git clone https://github.com/DrAbdulmalek/OmniFile_Processor.git
%cd OmniFile_Processor

# 2. تثبيت الحزم / Install packages
!pip install -q -r requirements.txt

# 3. تثبيت Tesseract / Install Tesseract
!apt install -y tesseract-ocr tesseract-ocr-ara tesseract-ocr-eng

# 4. تشغيل التطبيق / Run the application
!streamlit run app.py --server.port 7860
📖 إعداد Google Colab المتقدم / Advanced Colab Setup 
# ربط Google Drive للحفظ المستمر
from google.colab import drive
drive.mount('/content/drive')

# إنشاء مجلد العمل
import os
WORK_DIR = '/content/drive/MyDrive/OmniFile_AI'
os.makedirs(WORK_DIR, exist_ok=True)

# نسخ المشروع إلى Drive
!cp -r /content/OmniFile_Processor/* {WORK_DIR}/

# إعداد الإعدادات
from config import OmniFileConfig
cfg = OmniFileConfig.from_colab_drive()
cfg.setup_environment()

2.3 التثبيت مع GPU Support / GPU Installation 

# 1. تثبيت PyTorch مع دعم CUDA / Install PyTorch with CUDA support
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118

# 2. تثبيت ONNX Runtime مع دعم GPU (اختياري)
pip install onnxruntime-gpu

# 3. تثبيت بقية الحزم / Install remaining packages
pip install -r requirements.txt

# 4. التحقق من GPU / Verify GPU
python -c "import torch; print(f'CUDA: {torch.cuda.is_available()}, Device: {torch.cuda.get_device_name(0) if torch.cuda.is_available() else \"CPU\"}')"

2.4 التثبيت باستخدام Docker / Docker Installation 

# بناء الصورة / Build the image
docker build -t omnifile-processor .

# تشغيل الحاوية / Run the container
docker run -d \
  --name omnifile \
  -p 7860:7860 \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/models_cache:/app/models_cache \
  --gpus all \
  omnifile-processor

2.5 التثبيت على HuggingFace Spaces / HuggingFace Spaces 

# المشروع يحتوي Dockerfile جاهز / Project includes a ready Dockerfile
# 1. أنشئ Space جديد من نوع Docker
# 2. ارفع ملفات المشروع
# 3. سيتم البناء تلقائياً

# أو استخدم git:
git clone https://huggingface.co/spaces/<your-username>/OmniFile_Processor
cd OmniFile_Processor
# انسخ ملفات المشروع ثم ارفع
git add .
git commit -m "Deploy OmniFile AI Processor"
git push

3. التشغيل / Running

3.1 واجهة Streamlit (الواجهة الرئيسية) / Streamlit UI (Main Interface) 

# تشغيل عادي / Normal run
streamlit run app.py

# تشغيل بمنفذ محدد / Run on specific port
streamlit run app.py --server.port 8501

# تشغيل للوصول العام / Run for public access
streamlit run app.py --server.port 8501 --server.address 0.0.0.0

# إعداد Google Colab / Colab setup
streamlit run app.py --server.port 7860

ملاحظة / Note: واجهة Streamlit هي الواجهة الأساسية والموصى بها لمعظم المستخدمين. توفر جميع الميزات في شكل تبويبات منظمة. Note: Streamlit UI is the primary and recommended interface for most users. It provides all features in organized tabs.

3.2 واجهة Gradio (واجهة متقدمة) / Gradio UI (Advanced Interface) 

# تشغيل واجهة Gradio / Run Gradio interface
python -m src.gradio_ui

ملاحظة / Note: واجهة Gradio توفر تجربة تفاعلية متقدمة مع دعم أفضل لمعالجة الصور والمعاينة الفورية. Note: Gradio UI provides an advanced interactive experience with better image processing and instant preview support.

3.3 وضع سطر الأوامر / CLI Mode 

# تشغيل وضع CLI / Run in CLI mode
python main.py --cli

# عرض معلومات الإصدار / Show version info
python main.py --version

3.4 إعداد بيئة Google Colab / Colab Setup 

# إعداد تلقائي لبيئة Colab / Automatic Colab setup
python main.py --colab

يقوم هذا الأمر تلقائياً بـ:

  • ربط Google Drive
  • تثبيت جميع الحزم
  • إعداد مسارات التخزين المؤقت

This command automatically:

  • Mounts Google Drive
  • Installs all packages
  • Sets up cache paths

3.5 المعالجة غير المتزامنة (Celery) / Async Processing (Celery) 

# 1. تشغيل Redis / Start Redis
redis-server &

# 2. تشغيل عامل Celery / Start Celery worker
celery -A tasks worker --loglevel=info

# 3. تشغيل التطبيق / Run the app
streamlit run app.py

ملاحظة / Note: المعالجة غير المتزامنة مفيدة لمعالجة ملفات PDF الكبيرة أو الدفعات الكبيرة من الصور. Note: Async processing is useful for large PDF files or large batches of images.

4. الميزات الرئيسية / Key Features

4.1 معالجة OCR / OCR Processing

يتضمن النظام ثلاث محركات OCR متكاملة تعمل معاً لتحقيق أفضل دقة: The system includes three integrated OCR engines working together for maximum accuracy:

محرك TrOCR (من Microsoft) / TrOCR Engine (Microsoft)

الخاصية / Feature التفاصيل / Details
الأفضل لـ / Best for الخط اليدوي، الكلمات المعزولة، الملاحظات
النماذج / Models small (خفيف), base (متوازن), large (أدق)
GPU يدعم CUDA لتسريع كبير
ONNX يمكن تحويله لـ ONNX Runtime
Quantization يدعم INT8 لتقليل الذاكرة

محرك EasyOCR / EasyOCR Engine

الخاصية / Feature التفاصيل / Details
الأفضل لـ / Best for النصوص المطبوعة، النصوص متعددة اللغات
السرعة / Speed الأسرع بين المحركات الثلاثة
اللغات / Languages 80+ لغة (بما فيها العربية والإنجليزية والألمانية)
GPU يدعم CUDA
Batch يدعم المعالجة الدفعية

محرك Tesseract / Tesseract Engine

الخاصية / Feature التفاصيل / Details
الأفضل لـ / Best for النصوص المطبوعة الواضحة، الاستخدام الخفيف
الوزن / Weight خفيف جداً، لا يحتاج GPU
اللغات / Languages 100+ لغة (تحتاج تثبيت حزم اللغة)
التثبيت / Install يحتاج تثبيت على النظام (apt/brew)

إعدادات المحركات / Engine Settings

يمكن التحكم بكل محرك من خلال OmniFileConfig: Each engine can be controlled through OmniFileConfig:

from config import OmniFileConfig

cfg = OmniFileConfig()

# تفعيل/تعطيل المحركات / Enable/disable engines
cfg.enable_trocr = True       # تفعيل TrOCR
cfg.enable_easyocr = True     # تفعيل EasyOCR
cfg.enable_tesseract = True   # تفعيل Tesseract

# حجم نموذج TrOCR / TrOCR model size
cfg.trocr_model_variant = "base"  # "small" | "base" | "large"

# التخزين المؤقت / Caching
cfg.ocr_cache_enabled = True     # تفعيل كاش OCR
cfg.ocr_cache_ttl = 3600         # مدة صلاحية الكاش (ثانية)

# تحسين الأداء / Performance optimization
cfg.use_onnx = False            # تسريع ONNX Runtime
cfg.use_quantization = False    # تخفيف دقة INT8
cfg.low_memory = False          # وضع الذاكرة المنخفضة

# معالجات إضافية / Additional settings
cfg.dpi = 300                   # دقة تحويل PDF
cfg.trocr_batch_size = 8       # حجم الدفعة
cfg.num_beams = 4              # عدد أشعة البحث
cfg.easy_conf_threshold = 0.80 # حد الثقة لـ EasyOCR

4.2 التصحيح الإملائي / Spell Correction

المصحح الإملائي الذكي يدعم ثلاث لغات مع حماية المصطلحات التقنية: The smart spell corrector supports three languages with protection for technical terms:

اللغات المدعومة / Supported Languages

اللغة / Language المكتبة / Library ملاحظات / Notes
الإنجليزية / English pyspellchecker دقة عالية للمصطلحات العامة
العربية / Arabic ar-corrector تصحيح متقدم للعربية
الألمانية / German pyspellchecker يدعم الأحرف الخاصة (ä, ö, ü, ß)

حماية المصطلحات / Term Protection

يحمي المصحح تلقائياً: The corrector automatically protects:

  • كلمات Python المحجوزة: def, class, import, return, if, for, while ...
  • أسماء المكتبات: numpy, pandas, torch, transformers, fastapi ...
  • المتغيرات: snake_case, camelCase, PascalCase
  • الأرقام والرموز: لا يتم تصحيحها أبداً
  • المصطلحات المخصصة: يمكن إضافة مصطلحات محمية إضافية

التعلم من المستخدم / Learning from User

يتعلم المصحح من تصحيحات المستخدم ويحفظها: The corrector learns from user corrections and saves them:

from modules.nlp.spell_corrector import SpellCorrector

corrector = SpellCorrector()

# تعليم المصحح / Teach the corrector
corrector.learn_correction("omnifle", "omnifile")
corrector.learn_correction("hendwritng", "handwriting")

# التصحيح يحتاج 2 تصحيحات متطابقة ليُفعّل / Corrections need 2 identical votes to activate
# يمكن تغيير الحد بـ min_votes=1 / Can change threshold with min_votes=1

4.3 الترجمة / Translation

المترجم التقني يدعم الترجمة بين ثلاث لغات مع حماية الكود البرمجي: The technical translator supports translation between three languages with code protection:

اتجاهات الترجمة / Translation Directions

من إلى / From to النموذج / Model
EN to AR Helsinki-NLP/opus-mt-en-ar
AR to EN Helsinki-NLP/opus-mt-ar-en
EN to DE Helsinki-NLP/opus-mt-en-de
DE to EN Helsinki-NLP/opus-mt-de-en
DE to AR Helsinki-NLP/opus-mt-de-ar
AR to DE Helsinki-NLP/opus-mt-ar-de

ملاحظة / Note: عند عدم توفر نموذج مباشر، يستخدم النظام الإنجليزية كلغة وسيطة تلقائياً. Note: When a direct model is unavailable, the system automatically uses English as a pivot language.

حماية الكود البرمجي / Code Protection

يحافظ المترجم على المقاطع التالية بدون ترجمة: The translator preserves the following without translation:

  • مقاطع الكود (```python ... ``` و `inline`)
  • أسماء المتغيرات (snake_case, camelCase)
  • أسماء الفئات (PascalCase)
  • أنواع البيانات (int, str, bool, list, dict)
  • كلمات Python المحجوزة
  • عناوين URL والبريد الإلكتروني
  • الأرقام

القاموس التقني / Technical Glossary

يحتوي المترجم على قاموس مدمج لأكثر من 80 مصطلح تقني: The translator includes a built-in glossary of 80+ technical terms:

الإنجليزية / English العربية / Arabic
Machine Learning التعلم الآلي
Deep Learning التعلم العميق
Neural Network الشبكة العصبية
Natural Language Processing معالجة اللغة الطبيعية
Computer Vision الرؤية الحاسوبية
Artificial Intelligence الذكاء الاصطناعي 
from modules.nlp.translator import TechnicalTranslator

translator = TechnicalTranslator()

# ترجمة نص / Translate text
result = translator.translate_text(
    "Machine learning is a subset of artificial intelligence",
    source="en",
    target="ar"
)
print(result["translated_text"])

# ترجمة مستند كامل / Translate a full document
doc_result = translator.translate_document(
    long_text, source="en", target="ar", chunk_size=500
)

# إضافة مصطلح للقاموس / Add term to glossary
translator.add_to_glossary("fine-tuning", "الضبط الدقيق")

4.4 التلخيص / Summarization (جديد v2.1)

ميزة جديدة في v2.1 لتلخيص النصوص الطويلة باستخدام نماذج BART: New feature in v2.1 for summarizing long texts using BART models:

النماذج المدعومة / Supported Models

اللغة / Language النموذج / Model النوع / Type
الإنجليزية / English facebook/bart-large-cnn تلخيص أخبار
الإنجليزية / English facebook/bart-large-xsum تلخيص عام
الإنجليزية / English google/pegasus-xsum تلخيص BBC
العربية / Arabic UAE-Code/mbart-summarization-ar تلخيص عربي

الميزات / Features

  • كشف اللغة تلقائياً: يكشف اللغة من النص ويختار النموذج المناسب
  • نموذج احتياطي: عند فشل النموذج الأساسي، يجرب النموذج الاحتياطي تلقائياً
  • تخزين مؤقت: يحفظ نتائج التلخيص لتسريع الطلبات المتكررة
  • انحطاط سلس: إذا تعذر التلخيص، يعيد أول 200 حرف كملخص
  • معالجة دفعية: يدعم تلخيص مجموعة نصوص مع تتبع التقدم
from modules.nlp.summarizer import TextSummarizer

summarizer = TextSummarizer(
    max_length=130,
    min_length=30,
    enable_cache=True
)

# تلخيص نص / Summarize text
result = summarizer.summarize(long_article)
print(result["summary"])
print(f"نسبة الضغط: {result['compression_ratio']:.1%}")
print(f"اللغة: {result['language']}")
print(f"النموذج: {result['model']}")
print(f"وقت المعالجة: {result['processing_time']:.2f}s")

4.5 فحص البيانات الحساسة / Sensitive Data Scanning (جديد v2.1)

ميزة جديدة في v2.1 لكشف البيانات الحساسة وإخفائها: New feature in v2.1 for detecting and redacting sensitive data:

الأنماط المدعومة / Supported Patterns

النمط / Pattern الوصف / Description مستوى الخطورة / Risk
CREDIT_CARD بطاقات ائتمانية عالي / High
EMAIL_ADDRESS بريد إلكتروني متوسط / Medium
PHONE_NUMBER أرقام هواتف متوسط / Medium
IP_ADDRESS عناوين IP منخفض / Low
SSN رقم ضمان اجتماعي عالي / High
API_KEY مفاتيح API عالي / High
JWT_TOKEN رموز JWT عالي / High
AWS_KEY مفاتيح AWS عالي / High
PRIVATE_KEY مفاتيح خاصة (RSA, EC, DSA) حرج / Critical
IBAN أرقام IBAN عالي / High

طرق الفحص / Detection Methods

  1. Presidio (متقدم): أكثر دقة، يستخدم NLP لتحليل السياق
  2. Regex (احتياطي): يعمل دائماً بدون مكتبات إضافية
from modules.security.sensitive_data_scanner import SensitiveDataScanner

scanner = SensitiveDataScanner(use_presidio=True)

# فحص نص / Scan text
result = scanner.scan_text("Contact: john@email.com, Card: 4111-1111-1111-1111")
print(f"بيانات حساسة: {result['sensitive_data_found']}")
print(f"مستوى الخطورة: {result['risk_level']}")
print(f"عدد الكيانات: {result['total_entities']}")

# إخفاء البيانات الحساسة / Redact sensitive data
safe_text = scanner.anonymize_text(
    "Card: 4111-1111-1111-1111, Email: john@email.com",
    mask_char="[REDACTED]"
)
print(safe_text)  # Card: [REDACTED], Email: [REDACTED]

# إضافة نمط مخصص / Add custom pattern
scanner.add_custom_pattern(
    name="NATIONAL_ID_SA",
    label="هوية وطنية سعودية",
    regex=r"\b\d{10}\b",
    risk="high"
)

4.6 تنظيم الملفات / File Organization

فرز تلقائي حسب النوع / Automatic Sorting by Type

الملفات المعتمدة للتقسيم: Supported file categories:

التصنيف / Category الامتدادات / Extensions
الصور / Images .png, .jpg, .jpeg, .bmp, .tiff, .webp
المستندات / Documents .pdf, .docx, .txt, .md, .rtf
البيانات / Data .csv, .json, .xlsx, .xml, .yaml
الكود / Code .py, .js, .ts, .java, .cpp, .h, .ipynb
الأرشيفات / Archives .zip, .tar.gz, .7z, .rar

فحص أمني للملفات / Security File Scanning

  • فحص الامتدادات المعتمدة
  • كشف الأنماط المحظورة (passwords, secrets, api_key, token)
  • تحديد حجم الملفات
  • تسجيل سجل المعالجة

النسخ الاحتياطي / Backup 

from modules.security.backup_manager import BackupManager

# إنشاء نسخة احتياطية / Create backup
backup = BackupManager.create_backup(source_dir="./data")

# استعادة نسخة / Restore backup
BackupManager.restore_backup(backup_path="./backups/backup_2024.zip")

4.7 استخراج الكيانات المسماة / Named Entity Recognition (NER)

استخراج الأسماء والأماكن والمنظمات من النصوص العربية والإنجليزية: Extract names, locations, and organizations from Arabic and English texts:

نوع الكيان / Entity Type النموذج / Model
PERSON (أشخاص) aubmindlab/bert-base-arabertv02-ner
ORG (منظمات) aubmindlab/bert-base-arabertv02-ner
LOC (أماكن) aubmindlab/bert-base-arabertv02-ner

4.8 تصنيف النصوص / Text Classification

تصنيف المستندات تلقائياً إلى فئات: Automatic document classification into categories:

from modules.nlp.text_classifier import TextClassifier

classifier = TextClassifier()
result = classifier.classify("This is a research paper about neural networks")
print(result["category"])    # "research"
print(result["confidence"])  # 0.95

4.9 كشف اللغة / Language Detection 

from modules.nlp.language_detector import LanguageDetector

detector = LanguageDetector()
result = detector.detect("هذا نص عربي")
print(result["language"])    # "ar"
print(result["confidence"])  # 0.99

5. اختصارات لوحة المفاتيح / Keyboard Shortcuts

واجهة Streamlit / Streamlit Interface

العملية / Action الاختصار / Shortcut الوصف / Description
رفع ملف / Upload file Drag and Drop سحب وإفلات الملف في منطقة الرفع
تشغيل معالجة / Run processing Enter في حقول الإدخال النصية
حفظ النتائج / Save results Ctrl+S حفظ النص المُعالج (إن توفر)
توسيع تبويب / Expand tab الضغط على العنوان توسيع/طي تبويب في الشريط الجانبي
تحديث الصفحة / Refresh page R إعادة تشغيل التطبيق
إيقاف مؤقت / Pause Ctrl+C إيقاف التطبيق في الطرفية
بحث / Search Ctrl+F بحث في النصوص المعروضة

واجهة Gradio / Gradio Interface

العملية / Action الاختصار / Shortcut
رفع صورة / Upload image Drag and Drop أو النقر على منطقة الرفع
مسح المدخلات / Clear inputs زر Clear
إرسال / Submit زر Submit أو Enter

6. حل المشكلات / Troubleshooting

6.1 مشكلة: OCR بطيء / Issue: OCR is Slow

الأعراض / Symptoms: المعالجة تستغرق وقتاً طويلاً (> 10 ثوانٍ للصورة الواحدة)

الحلول / Solutions:

# 1. فعّل GPU / Enable GPU
cfg.use_gpu = True

# 2. استخدم نموذج TrOCR أصغر / Use a smaller TrOCR model
cfg.trocr_model_variant = "small"  # بدلاً من "base" أو "large"

# 3. فعّل ONNX Runtime لتسريع الاستدلال / Enable ONNX Runtime
cfg.use_onnx = True
# تأكد من تثبيت: pip install onnxruntime

# 4. فعّل Quantization (INT8) لتقليل الذاكرة / Enable Quantization
cfg.use_quantization = True

# 5. عطّل المحركات غير المستخدمة / Disable unused engines
cfg.enable_trocr = False  # إذا كنت تحتاج EasyOCR فقط
# أو استخدم محرك واحد فقط:
cfg.enable_easyocr = True
cfg.enable_tesseract = False

# 6. فعّل التخزين المؤقت / Enable caching
cfg.ocr_cache_enabled = True
cfg.ocr_cache_ttl = 3600  # ساعة واحدة

# 7. قلل دقة تحويل PDF / Reduce PDF conversion DPI
cfg.dpi = 200  # بدلاً من 300

6.2 مشكلة: نفاد الذاكرة (OOM) / Issue: Out of Memory

الأعراض / Symptoms: RuntimeError: CUDA out of memory أو تجمد النظام

الحلول / Solutions:

# 1. فعّل وضع الذاكرة المنخفضة / Enable low memory mode
cfg.low_memory = True

# 2. استخدم نموذج TrOCR-small / Use TrOCR-small model
cfg.trocr_model_variant = "small"

# 3. فعّل Quantization (INT8) / Enable Quantization
cfg.use_quantization = True

# 4. قلل حجم الدفعة / Reduce batch size
cfg.trocr_batch_size = 4  # بدلاً من 8

# 5. عطّل TrOCR واستخدم EasyOCR فقط / Disable TrOCR, use EasyOCR only
cfg.enable_trocr = False
cfg.enable_easyocr = True

# 6. أضف تنظيف الذاكرة / Add memory cleanup
import gc
import torch
torch.cuda.empty_cache()
gc.collect()

6.3 مشكلة: TrOCR لا يعمل / Issue: TrOCR Not Working

الأعراض / Symptoms: خطأ عند محاولة استخدام TrOCR، أو النتيجة دائماً من EasyOCR

الحلول / Solutions:

# 1. تأكد من تثبيت المكتبات المطلوبة
pip install transformers torch

# 2. تأكد من إصدار transformers
pip install --upgrade transformers>=4.36.0

# 3. جرب التشغيل على CPU

cfg.use_gpu = False  # قسّم المشكلة: هل هي مشكلة GPU؟

# 4. تحقق من توفر المحرك
from modules.vision.ocr_engine import OCREngine
engine = OCREngine()
engines = engine.get_available_engines()
for e in engines:
    print(f"{e['name']}: available={e['available']}, enabled={e['enabled']}")

6.4 مشكلة: الترجمة لا تعمل / Issue: Translation Not Working

الأعراض / Symptoms: لا يظهر النص المترجم، أو يظهر رسالة "الترجمة غير متوفرة"

الحلول / Solutions:

# 1. تأكد من اتصال الإنترنت (لتحميل النموذج أول مرة)

# 2. تأكد من تثبيت المكتبات
pip install transformers sentencepiece

# 3. تأكد من إصدار sentencepiece
pip install --upgrade sentencepiece

# 4. تحقق من التخزين المؤقت (قد يكون تالفاً)
from modules.nlp.translator import TechnicalTranslator
translator = TechnicalTranslator()
translator.clear_cache()

# 5. تأكد من اللغات المدعومة
print(TechnicalTranslator.SUPPORTED_LANGUAGES)  # ['en', 'ar', 'de']
print(TechnicalTranslator.TRANSLATION_MODELS)

6.5 مشكلة: التلخيص لا يعمل / Issue: Summarization Not Working

الحلول / Solutions:

# تأكد من تثبيت المكتبات
pip install transformers torch

# إذا كنت تواجه مشكلة في نموذج عربي
pip install --upgrade transformers sentencepiece

# تحقق من توفر الملخص
from modules.nlp.summarizer import TextSummarizer
summarizer = TextSummarizer()
print(f"متاح: {summarizer.is_available()}")

# تأكد من أن النص طويل بما يكفي (30 كلمة على الأقل)
result = summarizer.summarize("نص قصير جداً")
print(result.get("reason"))  # "text_too_short"

6.6 مشكلة: خطأ في Tesseract / Issue: Tesseract Error

الأعراض / Symptoms: TesseractNotFoundError أو نتائج فارغة

الحلول / Solutions:

# Ubuntu/Debian:
sudo apt install tesseract-ocr tesseract-ocr-ara tesseract-ocr-eng

# macOS:
brew install tesseract
brew install tesseract-lang  # لغات إضافية

# Windows:
# حمّل من: https://github.com/UB-Mannheim/tesseract/wiki
# أضف مسار Tesseract لمتغيرات البيئة PATH

# التحقق من التثبيت:
tesseract --version
tesseract --list-langs

# أو ببساطة عطّل Tesseract واستخدم المحركات الأخرى
cfg.enable_tesseract = False

6.7 مشكلة: أخطاء التبعيات / Issue: Dependency Errors 

# إعادة تثبيت جميع الحزم
pip install -r requirements.txt --force-reinstall

# أو تثبيت الحزم المفقودة فقط:
pip install streamlit>=1.28.0
pip install transformers>=4.36.0
pip install torch>=2.1.0
pip install easyocr>=1.7.0
pip install PyMuPDF>=1.23.0

# تحقق من الحزم المفقودة تلقائياً:
python main.py  # سيظهر تحذير بالحزم المفقودة

7. أسئلة شائعة / FAQ

Q1: هل يعمل النظام بدون اتصال بالإنترنت؟ / Does the system work offline?

A: نعم، بعد تحميل النماذج لأول مرة (يحتاج إنترنت)، يعمل النظام بالكامل بدون اتصال. النماذج تُحفظ في مجلد models_cache/. A: Yes, after downloading models for the first time (requires internet), the system works fully offline. Models are cached in models_cache/.

Q2: ما هو أفضل محرك OCR للاستخدام؟ / What is the best OCR engine?

A: يعتمد على الاستخدام: A: It depends on the use case:

  • الخط اليدوي: TrOCR (الأفضل)
  • النصوص المطبوعة متعددة اللغات: EasyOCR (الأسرع)
  • الاستخدام الخفيف بدون GPU: Tesseract (الأخف)
  • لأفضل نتيجة: استخدم الثلاثة معاً (الافتراضي)

Q3: هل يمكن إضافة لغة جديدة؟ / Can I add a new language?

A: نعم، راجع دليل المطور / Developer Guide لخطوات إضافة لغة جديدة. باختصار: A: Yes, see the Developer Guide for steps to add a new language. Briefly:

  1. أضف الرمز في supported_languages في config.py
  2. أضف مصحح في spell_corrector.py
  3. أضف نموذج ترجمة في translator.py

Q4: كم يحتاج تحميل النماذج من الوقت؟ / How long does model download take?

A: يعتمد على سرعة الإنترنت وحجم النموذج: A: Depends on internet speed and model size:

  • TrOCR-small: 400 MB (2 دقائق)
  • TrOCR-base: 800 MB (4 دقائق)
  • TrOCR-large: 1.5 GB (8 دقائق)
  • EasyOCR (EN+AR): ~200 MB
  • نماذج الترجمة: ~300 MB لكل اتجاه

Q5: كيف أستخدم النظام مع GPU على Google Colab؟ / How to use GPU on Colab?

A:

# 1. تأكد من اختيار GPU في Runtime > Change runtime type > T4 GPU
# 2. تحقق:
import torch
print(f"CUDA available: {torch.cuda.is_available()}")
print(f"GPU: {torch.cuda.get_device_name(0)}")

# 3. الإعدادات ستكشف GPU تلقائياً:
from config import OmniFileConfig
cfg = OmniFileConfig.from_colab_drive()
# cfg.use_gpu سيكون True تلقائياً إذا توفر CUDA

Q6: هل يمكن معالجة ملفات PDF؟ / Can PDF files be processed?

A: نعم! النظام يدعم: A: Yes! The system supports:

  • استخراج النص المباشر من PDF
  • تحويل صفحات PDF إلى صور ومعالجتها بـ OCR
  • معالجة PDF متعدد الصفحات مع تتبع التقدم
  • دعم PDF الممسوح ضوئياً (scanned PDFs)

Q7: كيف أحمي كلمة معينة من التصحيح الإملائي؟ / How to protect a word from spell correction?

A:

from modules.nlp.spell_corrector import SpellCorrector

corrector = SpellCorrector()

# حماية مؤقتة / Temporary protection
result = corrector.correct_with_protection(
    "my custom term numpy pandas",
    protected_terms=["custom", "term"]
)

# حماية دائمة / Permanent protection
corrector.add_protected_term("OmniFile")
corrector.add_protected_term("TrOCR")

Q8: كيف أنشر النظام على الخادم؟ / How to deploy on a server?

A: هناك عدة خيارات: A: Several options available:

  1. Docker: docker build -t omnifile . && docker run -p 7860:7860 omnifile
  2. HuggingFace Spaces: ارفع المشروع مع Dockerfile
  3. Manual: streamlit run app.py --server.port 7860 --server.address 0.0.0.0
  4. مع Celery: لتسريع المعالجة غير المتزامنة

Q9: ما هو الفرق بين v2.0 و v2.1؟ / What's new in v2.1?

A:

الميزة / Feature v2.0 v2.1
محركات OCR مفعّلة دائماً قابلة للتفعيل/التعطيل
ONNX Runtime غير مدعوم مدعوم - تسريع الاستدلال
Quantization غير مدعوم مدعوم - INT8 لتقليل الذاكرة
OCR Cache غير مدعوم مدعوم - تخزين مؤقت
Summarization غير مدعوم مدعوم - تلخيص BART
Sensitive Scan غير مدعوم مدعوم - Presidio + Regex
Celery غير مدعوم مدعوم - معالجة غير متزامنة
الوضع الداكن غير مدعوم مدعوم - تخصيص

Q10: كيف أساهم في المشروع؟ / How to contribute?

A: اتبع الخطوات التالية: A: Follow these steps:

  1. Fork المشروع من GitHub
  2. أنشئ branch جديد: git checkout -b feature/my-feature
  3. اتبع معايير الكود في دليل المطور / Developer Guide
  4. أضف اختبارات للميزة الجديدة
  5. ارفع Pull Request مع وصف واضح

المؤلف / Author: Dr Abdulmalek Tamer Al-husseini 📍 الموقع / Location: Homs, Syria 📧 البريد / Email: Abdulmalek.husseini@gmail.com الإصدار / Version: 2.1 الترخيص / License: راجع ملف LICENSE