📖 Mistral OCR: أداة تحرير الوثائق العربية بالذكاء الاصطناعي

📺 اضغط هنا لمشاهدة الشرح الكامل والعملي على يوتيوب 📺

---

📋 نظرة عامة

هذا المستودع يحتوي على الكود المصدري للمشروع الذي تم شرحه في الفيديو، والذي يوضح كيفية استخدام واجهة برمجة تطبيقات Mistral OCR، وهي ثورة حقيقية في مجال التعرف الضوئي على الحروف (OCR)، خاصة للغة العربية.

المشروع يهدف إلى حل مشكلة "سجون الوثائق الرقمية"، حيث يصعب استخراج النصوص من ملفات PDF الممسوحة ضوئياً والكتب القديمة. باستخدام قوة نماذج الذكاء الاصطناعي التوليدي (Generative AI) من Mistral AI، يمكننا تحويل أي وثيقة إلى نص قابل للتعديل بدقة وسرعة فائقتين، مما يفتح الباب لتحويلها بسهولة إلى ملفات Word أو أي صيغة أخرى.

✨ الميزات الرئيسية

• 🔤 دقة فائقة للغة العربية: يتفوق على الحلول المنافسة مثل Google Document AI و Azure OCR في فهم بنية الخط العربي
• ⚡ سرعة هائلة: قادر على معالجة آلاف الصفحات في دقائق
• 🧠 فهم هيكلي عميق: لا يقرأ الحروف فقط، بل يفهم العناوين، الفقرات، الجداول، والقوائم ويحافظ على تنسيقها
• 📄 مخرجات منظمة: يسلم البيانات بصيغة Markdown، مما يسهل عملية تحويل PDF إلى Word
• 🔄 كود متقدم للمعالجة الدفعية: يتضمن السكربت BatchPdfConv.py ميزات احترافية مثل تتبع الحالة، وتسجيل الأخطاء، وإعادة المحاولة التلقائية

🛠️ المتطلبات الأساسية

قبل البدء، تأكد من أن بيئة العمل لديك جاهزة:

• 🐍 Python 3.9 أو أحدث
• 🔑 مفتاح API من Mistral AI: يمكنك الحصول على مفتاحك من منصة Mistral AI

⚙️ التثبيت والإعداد

1. استنساخ المستودع

git clone https://github.com/Pythonation/Mistral-Arabic-OCR-test.git
cd Mistral-Arabic-OCR-test

2. تثبيت المكتبات المطلوبة

pip install mistralai python-dotenv

3. إعداد مفتاح الـ API (للسكربت المتقدم BatchPdfConv.py)

• أنشئ ملفاً باسم .env في المجلد الرئيسي للمشروع
• أضف مفتاحك الخاص داخل هذا الملف بالشكل التالي:

MISTRAL_API_KEY="ضع_مفتاحك_السري_هنا"

• ملاحظة هامة: تم إضافة ملف .env إلى .gitignore لحماية مفتاحك من الرفع العرضي إلى GitHub

🚀 الاستخدام

يحتوي المستودع على 3 ملفات رئيسية لتلبية احتياجاتك المختلفة:

📄 1. معالجة ملف واحد (docconv.py)

سكربت بسيط ومباشر لمعالجة ملف PDF واحد. يستخدم مفتاح API مكتوب بشكل مباشر داخل الكود (Hardcoded)، وهو مناسب للتجارب السريعة.

طريقة التشغيل:

1. تأكد من وجود ملف باسم document.pdf في نفس المجلد
2. قم بتشغيل السكربت من الـ Terminal:

python docconv.py

3. سيطبع السكربت النص المستخرج بصيغة Markdown مباشرة في الـ Terminal

📓 2. النسخة التفاعلية (docconv.ipynb)

هذا الملف هو عبارة عن Jupyter Notebook ويحتوي على نفس كود معالجة الملف الواحد، ولكنه مقسم إلى خلايا مع شروحات باللغة العربية. إنه مثالي للأغراض التعليمية والتجربة خطوة بخطوة لفهم ما يفعله كل جزء من الكود.

طريقة التشغيل:

1. تأكد من تثبيت Jupyter Notebook أو Jupyter Lab
2. قم بتشغيل Jupyter: jupyter notebook
3. افتح ملف docconv.ipynb من متصفحك وقم بتشغيل الخلايا واحدة تلو الأخرى

🔄 3. المعالجة الدفعية المتقدمة (BatchPdfConv.py)

هذا هو السكربت الأكثر قوة واحترافية، مصمم لمعالجة عدد كبير من الملفات بكفاءة وموثوقية.

الميزات المتقدمة:

• 📊 إدارة الحالة: يستخدم ملف processed_files.csv لتسجيل حالة كل ملف (ناجح/فاشل). إذا توقف السكربت، سيكمل من حيث توقف عند تشغيله مرة أخرى دون إعادة معالجة الملفات الناجحة
• 📝 تسجيل الأخطاء: يتم تسجيل جميع الأخطاء وتفاصيل العمليات في ملف conversion.log للمساعدة في تصحيح الأخطاء
• 🔄 إعادة المحاولة التلقائية: في حال فشل طلب الـ API، سيحاول السكربت إعادة الطلب عدة مرات مع زيادة فترة الانتظار بين المحاولات
• 🔒 الأمان: يقرأ مفتاح الـ API من ملف .env بدلاً من كتابته مباشرة في الكود

طريقة التشغيل:

1. أنشئ مجلداً باسم doc
2. ضع جميع ملفات الـ PDF التي تريد معالجتها داخل مجلد doc
3. تأكد من إعداد ملف .env كما هو موضح في قسم التثبيت
4. قم بتشغيل السكربت:

python BatchPdfConv.py

5. سيتم إنشاء ملفات Markdown الناتجة في المجلد الرئيسي للمشروع

📁 هيكل المشروع

Mistral-Arabic-OCR-test/
├── docconv.py              # سكربت معالجة ملف واحد
├── docconv.ipynb           # نسخة Jupyter Notebook تفاعلية
├── BatchPdfConv.py         # سكربت المعالجة الدفعية المتقدم
├── document.pdf            # ملف PDF للاختبار
├── docs_import/            # مجلد ملفات PDF المدخلة
├── docs_exports/           # مجلد ملفات Markdown المخرجة
├── .env                    # ملف إعدادات API (يجب إنشاؤه)
└── README.md               # هذا الملف

🐛 استكشاف الأخطاء وحلها

مشاكل شائعة:

1. خطأ في مفتاح API:

   • تأكد من صحة مفتاح API في ملف .env
   • تأكد من أن المفتاح نشط وغير منتهي الصلاحية

2. خطأ في تثبيت المكتبات:

   pip install --upgrade pip
   pip install mistralai python-dotenv
   

3. مشكلة في قراءة ملف PDF:

   • تأكد من أن الملف موجود في المسار الصحيح
   • تأكد من أن الملف غير تالف

🤝 المساهمة والدعم

هذا المشروع يهدف إلى خدمة المجتمع العربي والمطورين. يمكنك المساهمة بعدة طرق:

• 🐛 فتح قضية (Issue): إذا واجهت مشكلة أو كان لديك اقتراح لتحسين الكود
• 🔧 طلب سحب (Pull Request): إذا قمت بتطوير ميزة جديدة أو إصلاح خطأ، نرحب بمساهماتك
• 💝 دعم القناة: الدعم المادي عبر باتريون أو Super Thanks في يوتيوب يساعدنا على توفير المزيد من هذه الموارد والمعرفة للمجتمع

📄 الترخيص

هذا المشروع مرخص تحت رخصة MIT.

🙏 شكر وتقدير

شكراً لـ Mistral AI على توفير هذه التقنية الرائعة، وللمجتمع العربي على دعمه المستمر.

---

⭐ إذا وجدت هذا المشروع مفيداً، لا تنس إعطاءه نجمة على GitHub!