قرآني : واجهات برمجة القرآن ومصحح التلاوة بالذكاء الاصطناعي

Seif Reda

السلام عليكم ورحمة الله وبركاته،

يسعدني أن أشارك مجتمع إتقان بمشروع Qurani.ai، وهو منصة بنية تحتية تقنية تهدف إلى تمكين المطورين والباحثين ورواد المنتجات الرقمية من بناء تطبيقات قرآنية متقدمة اعتمادًا على واجهات برمجة تطبيقات (APIs) معيارية ومدعومة بتقنيات الذكاء الاصطناعي.

ينطلق المشروع من قناعة بأن المجال القرآني الرقمي يحتاج إلى طبقة تقنية أساسية قابلة لإعادة الاستخدام والتوسع، بحيث لا يضطر كل فريق تقني إلى إعادة بناء منظومة البيانات والمعالجة من الصفر، بل يستطيع الانطلاق مباشرة نحو تطوير تجربة المستخدم والابتكار.

أولًا: الرؤية العامة

يهدف Qurani.ai إلى توفير بنية تحتية معيارية تخدم التطبيقات القرآنية بمختلف أنواعها، سواء كانت تطبيقات قراءة، أو حفظ، أو تعليم، أو بحث معرفي، أو أدوات مدمجة داخل منصات أخرى. الفكرة الأساسية ليست بناء تطبيق واحد، بل توفير طبقة تقنية يمكن البناء عليها لتطوير عشرات التطبيقات والخدمات المختلفة.

ثانيًا: مكتبة البيانات النصية للقرآن الكريم

توفر المنصة مكتبة نصية منظمة وشاملة تشمل:

نص القرآن الكريم بالرسم العثماني المعتمد
دعم أكثر من 360 إصدارًا من القرآن النصي والترجمات المتنوعة عبر لغات متعددة، تشمل أكثر من 270 نسخة نصية و 88 إصدارًا صوتيًا موزعة عبر أقسام البيانات المختلفة، مما يجعلها واحدة من أكثر المكتبات شمولًا من حيث التغطية القرآنية مقارنة بالعديد من المنصات الأخرى، وذلك مع مجموعة هائلة من الملفات الصوتية المتاحة (أكثر من 354,346 ملف صوتي) و 34 قارئًا مختلفًا، مما يمكّن استخدامات واسعة في التطبيقات القرآنية المتنوعة.
ترجمات متعددة عبر لغات عديدة
تفاسير متنوعة
هيكل المصحف الكامل: سور، آيات، أجزاء، أحزاب، أرباع، صفحات
بيانات وصفية وإحصائية منظمة
إمكانيات استعلام مرنة عبر REST API

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

ثالثًا: المكتبة الصوتية

توفر المنصة طبقة متكاملة للتعامل مع التلاوة الصوتية تشمل:

تسجيلات لعدد كبير من القراء مع تقسيمات منظمة على مستوى السورة والآية
ربط الصوت بالنص القرآني بدقة
إمكانية استعمالها داخل تطبيقات الاستماع المتزامن
دعم بناء أنظمة استماع تفاعلية وتطبيقات حفظ تعتمد على الصوت والنص معًا

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

رابعًا: محرك البحث الدلالي

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

أدوات بحث معرفي
تطبيقات تعليمية تفاعلية
أنظمة استكشاف موضوعات قرآنية
تجارب بحث متقدمة داخل التطبيقات

خامسًا: QRC — مصحّح التلاوة بالذكاء الاصطناعي

يعد نظام QRC أحد أهم مكونات Qurani.ai، وهو نظام يعتمد على تقنيات الذكاء الاصطناعي لتحليل التلاوة الصوتية وتقديم تقييم فوري وتغذية راجعة. يقوم النظام بـ:

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

تم تصميم النظام ليكون قابلًا للدمج عبر WebSocket أو API، بحيث يمكن إدراجه داخل منصات تعليم التلاوة أو تطبيقات حفظ القرآن بسهولة.

سادسًا: MCP Server

توفر المنصة خادمًا متوافقًا مع بروتوكول MCP (Model Context Protocol)، مما يتيح التكامل مع أدوات التطوير والوكلاء البرمجية، ويمكّن التطبيقات الذكية من الوصول إلى بيانات القرآن بشكل منظم وقياسي.

سابعًا: المستودع المفتوح المصدر

جزء أساسي من البنية التحتية متاح كمصدر مفتوح عبر GitHub:

https://github.com/misraj-ai/quranhub

المستودع يحتوي على:

الكود الأساسي للخدمات
أمثلة للاستخدام
توثيق فني
آليات الإعداد والتشغيل

ثامنًا: التوثيق والروابط

للاطلاع على التفاصيل الكاملة:

المستودع البرمجي: https://github.com/misraj-ai/quranhub
الموقع والتوثيق: https://qurani.ai/ar/docs
التطبيقات التي تستخدم قرآني: https://qurani.ai/ar/showcases

تطبيق “مصحف اقرأ”

نعمل حاليًا على إطلاق تطبيق “مصحف اقرأ” خلال شهر رمضان المبارك بإذن الله، وهو تطبيق مصحف رقمي مبني بالكامل على بنية Qurani.ai التقنية. يهدف التطبيق إلى تقديم تجربة قراءة متكاملة تشمل:

نص دقيق بالرسم العثماني
استماع متزامن
مصحّح تلاوة مدمج
أدوات مساعدة للحفظ والتعلم

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

أهمية المشروع للمطورين

يوفر Qurani.ai طبقة جاهزة تساعد على:

تقليل وقت التطوير
الاستفادة من مكتبة نصية وصوتية منظمة
دمج البحث الدلالي بسهولة
إضافة مصحّح التلاوة مدعوم بالذكاء الاصطناعي
البناء على بنية معيارية قابلة للتوسع

يسعدني استقبال آرائكم وملاحظاتكم، ومناقشة فرص التعاون أو التطوير المستقبلي داخل المجتمع.

بارك الله فيكم،
م. سيف الدين رضا
ممثلًا عن مسراج

علي ملص

Seif Reda
وعليكم السلام ورحمة الله وبركاته أستاذ سيف.
جهد مبارك ومبادرة نوعية ممتازة، فالمطورون بحاجة ماسة إلى بنية تحتية مفتوحة المصدر تخفف عبء إعادة بناء منظومة بيانات من الصفر عند تطوير كل تطبيق جديد.
لقد اطلعت على التوثيق واستكشفت معمارية المشروع، وأعجبتني فكرة الفصل الذكي الذي قمتم به، أي إتاحة البيانات الأساسية للمصحف مفتوحة المصدر وقابلة للاستضافة ذاتيًا في مقابل تقديم الخدمات المتقدمة التي تتطلب موارد حوسبة عالية مثل مصحح التلاوة والبحث الدلالي كخدمات مدارة عبر مفاتيح API.
أنشأت تطبيق ويب مصغر لتجربة الـ APIs المتاحة، وكان السرعة وهيكلة بيانات JSON جيدة، لكن أثناء التجربة لاحظت وجود مشكلة في إعدادات الـ CORS في بعض الخدمات، وقد ظهرت حتى في أدوات الاختبار الموجودة في التوثيق. اعتقدت أن سببها هو أن بعض الخدمات تعمل فقط عبر بيئات الخوادم أو أدوات Postman/cURL، وتفشل في المتصفح.

لكن عندما حاولت تجاوز المتصفح عبر استخدام cURL مع تمرير مفتاح API، أرجع الخادم خطأ 502 Bad Gateway، لذلك ربما السبب هو أن بعض الخدمات متوقفة مؤقتًا فهل هذا صحيح؟ أم أنني ارتكبت خطأ ما؟
وبخصوص حدود الاستخدام لنقاط الوصول العامة، فما هي الحدود الحالية؟ وهل تنصحون بالاعتماد عليها في بيئة الإنتاج للمشاريع الناشئة؟
وأخيرًا هل لديكم نية لإصدار مكتبات برمجية جاهزة للغات الشائعة لتسهيل استدعاء هذه الواجهات بدلًا من التعامل معها عبر REST مباشرة؟

BessmaSarri

Seif Reda
وعليكم السلام ورحمة الله وبركاته أستاذ سيف،
بارك الله في جهودكم في فريق "مسراج". مشروع Qurani.ai ليس مجرد أداة إضافية، بل هو بالفعل "بنية تحتية" افتقدها مجتمع المطورين الإسلامي طويلاً. الانتقال من مرحلة "بناء البيانات من الصفر" في كل تطبيق إلى مرحلة "الاستهلاك المباشر لـ APIs معيارية" سيسرع من عجلة الابتكار بشكل ملحوظ.

أكثر ما لفت انتباهي في المشروع هو نظام QRC (مصحح التلاوة بالذكاء الاصطناعي). فكرة توفيره كخدمة قابلة للدمج عبر WebSocket تفتح آفاقاً عظيمة لتطبيقات تحفيظ القرآن التفاعلية (Real-time correction)، وهو تحدٍ تقني معقد جداً نجحتم في تبسيطه للمطورين.

لدي بعض التساؤلات والاقتراحات التقنية:

بخصوص محرك البحث الدلالي (Semantic Search): ما هي النماذج اللغوية (LLMs) أو نماذج التضمين (Embedding Models) المستخدمة في بناء هذا المحرك؟ وهل البحث الدلالي يدعم اللغة العربية فقط، أم يمكن للمستخدم البحث بمعاني بلغات أخرى (كالإنجليزية) للوصول إلى الآيات المناسبة؟
التعامل مع QRC في بيئات الاتصال الضعيف: تطبيقات قراءة القرآن تُستخدم غالباً في أوقات وأماكن قد لا تتوفر فيها شبكة إنترنت سريعة. هل هناك تفكير مستقبلي لتوفير نسخ مصغرة (Lite Models) من مصحح التلاوة لتعمل مباشرة على أجهزة المستخدمين (On-device Edge AI)، لتقليل الاعتماد الكلي على الخوادم (Server-side)؟
دعم بروتوكول MCP: توفير خادم MCP خطوة سابقة لعصرها وممتازة جداً.
هذا سيتيح لنا كمطورين ربط بيانات القرآن مباشرة بأدوات مثل Cursor أو Claude لإنشاء وكلاء ذكاء اصطناعي (AI Agents) متخصصة في البحث والتفسير بمنتهى السهولة. سيكون من الرائع مستقبلا رؤية أمثلة تطبيقية (Use Cases) مخصصة للـ MCP

متحمسة جداً لإطلاق تطبيق "مصحف اقرأ" لنرى قوة هذه البنية التحتية في بيئة إنتاجية حقيقية. بالتوفيق لكم

HossamSabry

Seif Reda وعليكم السلام ورحمة الله وبركاته.. مجهود استثنائي يا بشمهندس سيف، ومستوى احترافي في بناء هذه البنية التحتية (Infrastructure) التي يحتاجها المجال.

لفت نظري شمولية المنصة، خاصة دعم بروتوكول MCP وتوافر محرك بحث دلالي؛ هذه الأدوات ستنقل تجربة المستخدم الرقمية للقرآن الكريم إلى مستوى آخر.

لدي سؤال بخصوص مصحح التلاوة (QRC) عند تقليل الـ Latency:
بما أن النظام يعتمد على WebSockets للمعالجة، كيف يتم ضمان استجابة بصرية فورية (Real-time Feedback) للمستخدم دون الشعور بتأخير ناتج عن سرعة الإنترنت؟ وهل يوفر الـ API بيانات دقيقة لتحديد موقع الخطأ (Timestamping) لتمكيننا من تقديم Visual Cues (إشارات بصرية) دقيقة على الكلمات داخل الواجهة؟

بارك الله فيكم وفي هذا العمل العظيم.

علا صالح

Seif Reda وعليكم السلام ورحمة الله وبركاته.
شكرًا على مشاركتنا لمشروع Qurani.ai وتعريفنا على الخدمات المتنوعة والغنية التي توفرونها.

أفكر في تجريب الواجهة البرمجية في تطبيق قرآني مخصص لاستكشاف ميزاتها لكن لدي سؤال قبل البدء:

عند اطلاعي على المستودع البرمجي:
https://github.com/misraj-ai/quranhub
ثم على التوثيق:
https://qurani.ai/ar/docs

لاحظت أن هناك اختلافًا في عرض الواجهات بين api.quranhub.com و https://api.qurani.ai/gw/qh

فما الفرق الفعلي بين ما هو موجود في المستودع البرمجي وما هو موثق في الموقع؟ هل يمثل المستودع الـ Core REST API فقط بينما الموقع يعرض طبقة Gateway إضافةً إلى الخدمات المتقدمة (البحث الدلالي وQRC)

وعند تطوير تطبيق يعتمد على الواجهة البرمجية ما هو الـ Base URL الذي أستدعيه للاستفادة من كافة الخدمات التي توفرونها؟ وهل جميع الخدمات متاحة للاستخدام بشكل مجاني، أم أن هناك خدمات تتطلب اشتراك مدفوع؟

Seif Reda

علي ملص
وعليكم السلام ورحمة الله وبركاته،

شكرًا جزيلًا على تجربتكم وملاحظاتكم القيمة.

حتى نتمكن من تتبع المشكلة بدقة، هل يمكنكم تزويدنا بأمثلة للـ requests التي قمتم بإرسالها ولم تنجح معكم؟
يفضل إرسال:

الـ Endpoint المستخدم

طريقة الاستدعاء (Browser / cURL / Postman)

الهيدرز المرسلة (خصوصًا Authorization)

نص الاستجابة الكامل للخطأ

هذا سيساعدنا في إعادة اختبار نفس السيناريو وتحديد سبب المشكلة بسرعة.

بخصوص حدود الاستخدام:

بالنسبة لواجهات البيانات القرآنية العامة (النصية والهيكلية)
لا توجد حاليًا حدود استخدام (Rate Limits) مفروضة عليها، وهي مصممة لتكون متاحة للاستخدام المفتوح، وسرعة الاستجابة فيها عالية جدًا ومناسبة للاعتماد عليها في المشاريع الإنتاجية، بما في ذلك المشاريع الناشئة والتطبيقات ذات الاستخدام الفعلي.

تم تصميم هذه الطبقة لتكون مستقرة وقابلة للاستهلاك المباشر دون تعقيد، وهي مناسبة تمامًا للبناء عليها في بيئة Production.

أما الخدمات المتقدمة مثل البحث الدلالي أو مصحح التلاوة، فهذه قد تخضع لسياسات استخدام مختلفة نظرًا لاعتمادها على موارد حوسبة أعلى، ويتم تنظيمها حسب طبيعة المشروع وحجمه.

وبخصوص المكتبات البرمجية (SDKs):

نعم، لدينا نية لإصدار مكتبات رسمية للغات الشائعة لتسهيل التكامل، خاصة:

JavaScript / TypeScript

Python

الهدف هو توفير طبقة تجريدية تسهّل المصادقة، إدارة الأخطاء، والتعامل مع نقاط الوصول دون الحاجة للتعامل المباشر مع REST في كل مرة.

ونسعد باقتراحاتكم حول اللغات أو البيئات التي تفضلون دعمها أولًا.

Seif Reda

BessmaSarri
وعليكم السلام ورحمة الله وبركاته،

جزاكم الله خيرًا على كلماتكم المشجعة وتحليلكم العميق للمشروع. يسعدنا فعلًا أن تصل فكرة “البنية التحتية” بهذا الوضوح، لأن هذا هو التحول الذي نسعى إليه: تمكين المطور من البناء مباشرة دون إعادة تأسيس طبقة البيانات في كل مرة.

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

وبخصوص تساؤلاتكم:

أولًا: محرك البحث الدلالي (Semantic Search)
المحرك مبني على نماذج تضمين دلالي مهيأة لمعالجة النص العربي بكفاءة، مع تصميم يسمح بدعم الاستعلامات متعددة اللغات عبر طبقة ربط دلالي بين المعنى والترجمة.
التركيز الأساسي حاليًا على العربية من حيث الدقة والسياق، لكن يمكن للمستخدم البحث بمعانٍ بلغات أخرى مثل الإنجليزية للوصول إلى الآيات ذات الصلة، اعتمادًا على طبقة المعالجة الدلالية المتاحة.
حرصنا في المعمارية على أن تكون مرنة بحيث يمكن تطوير النماذج أو تحسينها مستقبلًا دون التأثير على بقية النظام.

ثانيًا: QRC في بيئات الاتصال الضعيف
ملاحظتكم مهمة جدًا. بالفعل، أي نظام تصحيح لحظي يعتمد على الاتصال قد يتأثر بزمن الاستجابة وجودة الشبكة.
فكرة التشغيل على الأجهزة مباشرة (On-device / Edge AI) مطروحة من حيث المبدأ، لكنها ما تزال بحاجة إلى تقييم واختبارات عملية قبل اعتمادها رسميًا. في الوقت الحالي نركز على ضمان الاستقرار والدقة في البيئة القائمة، مع دراسة أفضل الخيارات لتحسين تجربة الاستخدام في ظروف الاتصال المختلفة.

ثالثًا: دعم بروتوكول MCP
يسعدنا جدًا تقديركم لهذه الخطوة. نحن نرى أن تمكين المطورين من ربط بيانات القرآن مباشرة بأدوات التطوير الحديثة سيفتح بابًا جديدًا لبناء وكلاء ذكاء اصطناعي متخصصة في البحث، التحليل، والمساعدة التعليمية.
نعمل على إعداد أمثلة تطبيقية عملية (Use Cases) توضح سيناريوهات استخدام واضحة للـ MCP، ونتطلع لإشراك المجتمع في اختبارها وتطويرها.

أما بخصوص مصحف اقرأ، فهو بالفعل البيئة الإنتاجية التي نختبر فيها تكامل جميع مكونات البنية التحتية ضمن تجربة مستخدم حقيقية. نعتبره خطوة مهمة لإثبات جاهزية المنصة على أرض الواقع، وليس مجرد إطار نظري.

شاكرين ومقدّرين دعمكم واهتمامكم، ويسعدنا استمرار هذا النقاش التقني المثمر.
بارك الله فيكم ووفقكم لكل خير.

علي ملص

Seif Reda
أهلًا بك أستاذ سيف، وشكرًا جزيلًا على تجاوبك واهتمامك بتتبع المشكلة.
لتسهيل الأمر وتجنب الضياع في تفاصيل الطلبات التي جربتها محليًا، أقترح أن تعتمد على الطلبات التي ترسلها واجهة التوثيق الرسمية الخاصة بكم، حيث تحدث المشكلة هناك كما تلاحظ في الصورة التي أرفقتها في تعليقي السابق. فعندما حاولت استخدام المثال الحي للبحث الدلالي، ظهرت الأخطاء (net::ERR_NAME_NOT_RESOLVED و Failed to fetch RSC payload) في Console.
أعتقد أن هذا يوضح أن المشكلة عامة، ويمكنكم استخدام واجهة التوثيق كبيئة اختبار مباشرة لإعادة إنتاج الخطأ.

وبخصوص التفاصيل التي طلبتها، فمشكلة حظر الـ CORS عند الاستدعاء المباشر من المتصفح، حاولت الاتصال بـ https://api.qurani.ai/gw/ss/ftawy/fuzzy و https://api.qurani.ai/gw/ss/search/tafsir، والاتصال يفشل ويظهر الخطأ التالي:
Access to XMLHttpRequest at '...' from origin '...' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

ولكي أتأكد أن المشكلة ليس محصورة في CORS، استخدمت أدوات Backend/CLI لتوجيه الطلب مع تمرير مفتاح API الصحيح في الترويسة ("api_key: [My_API_Key]")، والاستجابة كانت 502 Bad Gateway.

BessmaSarri

Seif Reda
وعليكم السلام ورحمة الله وبركاته،
الشكر موصول لكم على هذا الرد الوافي للرؤية التقنية والهندسية للمشروع.

أتفق معكم تماماً بخصوص نظام QRC؛ فالتركيز على استقرار الخدمة ودقتها (Stability & Accuracy) عبر الخوادم كخطوة أولى هو القرار الهندسي السليم لضمان جودة المخرجات، قبل الانتقال لتعقيدات التشغيل المحلي (Edge AI).

كما أنني متحمسة جداً لرؤية الأمثلة التطبيقية (Use Cases) الخاصة بـ MCP، فوجود توثيق عملي سيشجع مجتمع المطورين على البدء فوراً في تجربة بناء وكلاء ذكاء اصطناعي ودمجها في مشاريعهم, و قد قمت بمشاركته في عدة مجتمعات للمطورين العرب على منصة ديسكورد (Discord) لتعم الفائدة، ولتشجيع المطورين على استغلال هذه الواجهات البرمجية في مشاريعهم القادمة.

على صعيد آخر، قمت بجولة في صفحة التطبيقات (Showcases) في موقعكم، وأسعدني جداً رؤية هذا التنوع الجميل للمشاريع التي بدأت بالفعل بالاعتماد على بنيتكم التحتية.
فكرة تطبيق "حافظون" تمثل نقلة ممتازة في كيفية توظيف التقنية لخدمة علوم القرآن، والانتقال من مجرد "عرض النص" إلى "دراسة ومقارنة النصوص".
استخدامكم لنقطة الوصول narrations-differences من QuranHub API هو توظيف ذكي جداً للبيانات. أسعدني بشكل خاص الاهتمام بدعم روايات متعددة مثل رواية ورش عن نافع ومقارنتها مع حفص وغيرها، فهذا يخدم شريحة واسعة جداً تعتمد هذه الرواية بشكل أساسي في التلاوة والحفظ، ويسهل عليهم تدارس الفروق بالصوت والنص في واجهة واحدة دون تشتت.

بانتظار إطلاق تطبيق "مصحف اقرأ" بشوق ليكون خير برهان عملي على قوة ومرونة هذه البنية التحتية، خاصة مع اقتراب شهر رمضان المبارك.
وفقكم الله وسدد خطاكم، وبارك في جهود فريق "مسراج" بالكامل

Seif Reda

BessmaSarri

وعليكم السلام ورحمة الله وبركاته،

جزاكم الله خيرًا على دعمكم الصادق ومتابعتكم التفصيلية، ويسعدنا جدًا حرصكم على نشر المشروع في مجتمعات المطورين، فهذا محل تقدير كبير منا.

سعدنا أيضًا بانطباعكم حول صفحة التطبيقات، ولفت انتباهكم لتطبيق “حافظون” تحديدًا. هذا بالضبط ما نطمح إليه: أن تُستخدم البنية التحتية ليس فقط لعرض النص، بل لبناء أدوات بحثية وتعليمية تخدم علوم القرآن بعمق، سواء على مستوى الروايات أو المقارنات أو غيرها من المسارات المتقدمة.

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

نسأل الله أن يبارك في جهودكم كما باركتم في جهودنا، ونسعد دائمًا باستمرار هذا التواصل المثمر.

وفقكم الله وسدد خطاكم.

Seif Reda

HossamSabry

وعليكم السلام ورحمة الله وبركاته،

جزاكم الله خيرًا على كلماتكم الطيبة وتقديركم للمشروع، هذا يسعدنا ويحفّزنا للاستمرار.

بخصوص سؤالكم عن تقليل الـ Latency وتجربة الـ Real-time Feedback في QRC:

نحن نحرص على أن تكون تجربة المستخدم سلسة قدر الإمكان عبر تصميم تدفق الاتصال بحيث يتم إرسال المعالجة بشكل متدرج (Streaming) بدل انتظار اكتمال التسجيل كاملًا، مما يقلل الإحساس بالتأخير ويجعل الاستجابة أقرب للحظية من منظور المستخدم.

بطبيعة الحال، زمن الاستجابة يتأثر بجودة الاتصال، لكننا نعمل على تقليل الحمل في كل رسالة وتحسين إدارة الجلسة عبر WebSocket لضمان أفضل أداء ممكن ضمن حدود الشبكة المتاحة.

أما بخصوص تحديد موقع الخطأ (Timestamping)، فالواجهة توفر بيانات تمكّن المطور من ربط نتيجة التحليل بالمقطع المقروء، بما يسمح ببناء إشارات بصرية (Visual Cues) على مستوى الواجهة سواء لتحديد موضع الخطأ أو تمييز الجزء الذي يحتاج إلى إعادة. طريقة عرض هذه الإشارات تبقى مرنة بالكامل حسب تصميم التطبيق نفسه.

نسعد جدًا بأسئلتكم التقنية الدقيقة، ونتطلع لرؤية تطبيقات تستفيد من هذه الإمكانات بطريقة إبداعية.

بارك الله فيكم ووفقكم لكل خير.

Seif Reda

علي ملص

شكرًا جزيلًا على صبرك وتعاونك.

قمت بدفع إصلاح للمشكلة، تم الآن تصحيح ذلك، ويُفترض أن تعيد الواجهة الخطأ الحقيقي في حال وجوده بدلًا من 502، ولكن قم بالتأكد من تضمين الAPI KEY ضمن الheaders بشكل صحيح كما هو موجود في التوثيق.

يرجى المحاولة مرة أخرى، وإذا استمرت المشكلة يمكنك مشاركة أي تفاصيل إضافية أو بيانات اعتماد (Credentials) معي مباشرة على البريد التالي:

seif.reda@misraj.ai

وسأتابعها معك بشكل مباشر.

شكرًا مرة أخرى على ملاحظاتك الدقيقة وتعاونك.

علي ملص

Seif Reda
العفو، والشكر الجزيل لك أستاذ سيف.
للأسف لا أزال أعاني من المشكلة، وأيضًا الواجهات الموجودة في التوثيق لا تزال لا تعمل. وقد أعدت التجريب عدة مرات بدون فائدة، وهذه التفاصيل:
استخدمت تطبيق ويب React مع WebSocket، وعند إرسال تلاوة صوتية إلى واجهة QRC عبر WebSocket يتم الاتصال بالخادم، لكنه لا يرسل أي استجابة، وهذه تفاصيل الطلب المرسل:

معلومات الاتصال:
Protocol: WebSocket Secure (wss://) URL: wss://api.qurani.ai?api_key=key_BexyLinKyo1LKrJ0qqN4u Method: SendAudioChunk
بيانات الطلب (JSON):
{ "method": "SendAudioChunk", "audio_data": "[base64_encoded_audio_data]", "chapter_index": 1, "verse_index": 1, "hafz_level": 1, "tajweed_level": 3 }
مدة التسجيل: حوالي 5 ثواني.
وقد جربت إرسال الصوت بصيغ مختلفة (Base64, Binary)، واختبرت مستويات حفظ وتجويد مختلفة، وقمت بزيادة مهلة الاتصال إلى 30 ثانية، كما جربت أسماء methods مختلفة (SendAudio, ProcessAudio, etc.) من دون فائدة.
وحاولت أيضًا استخدام REST API للبحث الدلالي:
curl -X GET "https://api.qurani.ai/gw/ss/search/tafsir?query=الصبر&top_k=5" \ -H "api_key: key_XXXXXXXXXXXXXXXXX"
وكانت النتيجة:
400 Bad Request - api key is required
وخلصت إلى التالي:
في واجهة QRC: الاتصال ينجح، لكن لا توجد استجابة من الخادم.
في واجهة البحث الدلالي: الخادم لا يقبل الطلب بسبب عدم التعرف على مفتاح API، علمًا أنني متأكد من إرسال المفتاح الصحيح، وقد جربت صيغ مختلفة للمفتاح (مع/بدون البادئة "key_").

Seif Reda

علا صالح

وعليكم السلام ورحمة الله وبركاته،

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

بالنسبة للاختلاف الذي لاحظتيه:

النطاق api.quranhub.com هو الـ Base URL الخاص بواجهات برمجة التطبيقات العامة (Public APIs)، وهي الواجهات المجانية الخاصة ببيانات القرآن الكريم. هذه الطبقة تتيح لك الوصول إلى جميع البيانات الأساسية مثل الآيات، السور، الصفحات، الموضوعات، الآيات العشوائية وغيرها من البيانات النصية والهيكلية.
هذه الواجهات مجانية بالكامل ومصممة لتكون متاحة للاستخدام المفتوح في التطبيقات القرآنية، كما أن خادم MCP مبني عليها ويعتمد عليها في توفير البيانات.

أما النطاق api.qurani.ai/gw فهو يمثل طبقة Gateway موحدة تشمل واجهات بيانات القرآن إضافة إلى الخدمات المتقدمة مثل البحث الدلالي و QRC، ويتم من خلالها إدارة مفاتيح API وتنظيم الوصول إلى هذه الخدمات.

بالتالي:
إذا كان تطبيقك يعتمد على بيانات القرآن الأساسية فقط، فيمكنك البدء مباشرة باستخدام api.quranhub.com.
أما إذا كنتي ترغبي بالاستفادة من الخدمات المتقدمة لاحقًا، فسيكون التكامل عبر طبقة الـ Gateway.

من ناحية الاستخدام، واجهات البيانات العامة مجانية، بينما بعض الخدمات المتقدمة قد تخضع لتنظيم استخدام عبر مفاتيح API بحسب طبيعة المشروع.

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

Seif Reda

علي ملص

وعليكم السلام ورحمة الله وبركاته،

شكرًا لك على المتابعة والتفاصيل الدقيقة.

بالنسبة لخدمة QRC، بحسب توجيه فريق تصحيح التلاوة، يجب أن يكون التسجيل الصوتي المُرسل مُشفّرًا بصيغة Opus (opus encoded audio).
إذا لم يكن الصوت مُرمّزًا بصيغة Opus بشكل صحيح قبل تحويله إلى Base64 وإرساله، فقد يتم فتح الاتصال دون أن تتم معالجة المقطع، وبالتالي لا تصدر استجابة من الخادم.

لذلك يُرجى التأكد من:

أن التسجيل مُرمّز بصيغة Opus فعلًا (وليس فقط WebM أو WAV مثلًا).

ثم يتم تحويله إلى Base64 بعد الترميز.

ثم إرساله ضمن الحقل audio_data.

أما بخصوص مشكلة البحث الدلالي وظهور الخطأ:
400 Bad Request - api key is required

يمكنك تجربة إرسال المفتاح عبر الهيدر التالي بدلًا من api_key:

X-Api-Key : YOUR_API_KEY

بعض المسارات تعتمد قراءة المفتاح من X-Api-Key في الترويسة بدلًا من api_key.

يرجى تجربة ذلك وإخباري بالنتيجة، وسنواصل المتابعة معك حتى يتم حل المشكلة بالكامل بإذن الله.

علي ملص

Seif Reda
شكرًا جزيلًا على متابعتك أستاذ سيف. أقدر لك ذلك كثيرًا.
سأجرب ما ذكرته خلال اليومين القادمين بإذنه الله وأخبرك بالنتيجة.

Baraw

السلام عليكم ورحمة الله وبركاته،
أسأل الله أن تكونوا بخير، وجزاكم الله خيرًا على جهودكم القيّمة.

أودّ أن أعرف هل جميع البيانات المتوفرة لنسخة المصحف ذات 15 سطرًا متوفرة أيضًا لنسخة المصحف ذات 13 سطرًا؟

فعلى سبيل المثال: هل يمكن عرض صفحة كاملة من مصحف 13 سطرًا بحيث تكون بنفس التنسيق، وتظهر الآيات في نفس مواضعها على كل سطر كما هي في المصحف الهندي-الباكستاني (IndoPak) ذي 13 سطرًا؟

وهل البيانات الوصفية (metadata) الأخرى المرتبطة بالآيات والسور وغيرها متوفرة أيضًا بشكل كامل لهذا النوع من المصاحف؟

وهل توجد قاعدة بيانات أو واجهة برمجة تطبيقات (API) توفر هذه المعلومات؟

جزاكم الله خيرًا، وبارك الله فيكم ونفع بكم.

Seif Reda

Baraw

وعليكم السلام ورحمة الله وبركاته،

جزاكم الله خيرًا على سؤالك واهتمامكم بالتفاصيل المتعلقة بتنسيقات المصحف.

نعم، المنصة تدعم بالفعل أكثر من تخطيط للمصحف (Mushaf Layouts)، بما في ذلك تخطيطات المصحف ذات 13 سطرًا مثل النسخة الهندية-الباكستانية (IndoPak). يمكنكم الاطلاع على جميع التخطيطات المتوفرة عبر واجهة برمجة التطبيقات التالية:

https://api.quranhub.com/v1/mushaf-layouts/?limit=20&offset=0

وستجدون ضمنها تخطيطات مثل:

Indopak 13 lines – Qudratullah

Indopak 13 lines – Taj company

كل تخطيط يحدد عدد الصفحات وعدد الأسطر في الصفحة والخط المستخدم.

أما بخصوص عرض صفحة كاملة بنفس تنسيق المصحف بحيث تظهر الآيات في مواضعها الصحيحة على كل سطر، فهذا متاح عبر واجهة تخطيط الصفحات. على سبيل المثال يمكن جلب تخطيط الصفحة الأولى من مصحف IndoPak ذي 13 سطرًا عبر:

https://api.quranhub.com/v1/mushaf-layouts/indopak-13-lines-layout-qudratullah/pages/1

هذه الواجهة تعيد معلومات كل سطر في الصفحة مثل:

رقم السطر

نوع السطر (آية، اسم سورة، إلخ)

ما إذا كان السطر متمركزًا

رقم السورة إن وجد

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

أما بالنسبة للبيانات الوصفية المرتبطة بالآيات والسور وغيرها، فيمكنكم الاعتماد على البيانات الأساسية للمصحف ذي 15 سطرًا (وهو التخطيط المرجعي الذي نعمل عليه)، ثم بناء mapping بينه وبين التخطيط الآخر مثل مصحف IndoPak ذي 13 سطرًا. بهذه الطريقة يمكن استخدام نفس بيانات الآيات مع إعادة توزيعها وفق تخطيط الصفحة والأسطر الخاص بالمصحف الآخر.

إذا كنتم تبنون تطبيقًا يعتمد على هذا النوع من التخطيط (مثل المصحف IndoPak ذي 13 سطرًا)، فسيسعدنا معرفة ذلك لنرشح لكم أفضل الواجهات المناسبة لسيناريو الاستخدام لديكم.

omar34

Seif Reda
جزاكم الله خيرا و نفع بكم
لو نتعاون سويا
لي منشور باسم omar34

Seif Reda

omar34

وعليكم السلام ورحمة الله وبركاته،

وجزاكم الله خيرًا. اطلعت على المنشور باسم omar34، ويسعدني التعاون معكم بإذن الله.
لو تكرمتم، هل يمكن توضيح نوع التعاون الذي تحتاجونه تحديدًا؟ حتى نرى كيف يمكننا المساعدة.

الصفحة التالية »

ثبت مجتمعنا كتطبيق لتجربة افضل

انضم إلى نشرة إتقان 📩

انضم إلى نشرة إتقان 📩

شكراً لك!