توجيه الاستخراج (Extraction Prompt)

هذا هو التوجيه (prompt) المُرسل فعلياً إلى Gemini مع كل صورة إيصال، كما هو في analyze.py (المتغيّر EXTRACTION_PROMPT). انسخه كما هو لتجربته أو لتعديله لعملك الخاص.

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

- vendor: اسم المتجر أو الجهة كما هو مكتوب بالعربية.
- date: تاريخ الإيصال بصيغة YYYY-MM-DD. إذا كان التاريخ بأرقام هندية (٠-٩) حوّله إلى أرقام عربية غربية عادية.
- category: صنّف الإيصال إلى واحدة فقط من هذه الفئات: مطعم، سوبر ماركت، صيدلية، قطع غيار، اتصالات، خدمات، أخرى.
- currency: حدد العملة كرمز مختصر فقط: YER لليال اليمني، SAR لليال السعودي، أو OTHER لأي عملة أخرى.
- line_items: قائمة بكل بند يظهر في الإيصال، مع اسمه (name)، الكمية (quantity)، سعر الوحدة (unit_price)، وإجمالي البند (total).
- subtotal: المجموع الفرعي قبل الضريبة كما هو مطبوع. إذا لم يكن مطبوعًا صراحة، احسبه من مجموع البنود.
- tax: قيمة الضريبة (ضريبة القيمة المضافة) كما هي مطبوعة. إذا لم تظهر أي ضريبة في الإيصال، أعد 0.
- total: المبلغ الإجمالي النهائي كما هو مطبوع.

أعد الأرقام كقيم رقمية فقط (بدون فواصل أو رموز عملة داخل الرقم). التزم تمامًا بمخطط JSON المحدد في الطلب، ولا تضف أي نص خارج JSON.

يُرسل هذا التوجيه مصحوباً بمخطط JSON صارم (RESPONSE_SCHEMA في analyze.py، عبر خاصيتَي responseMimeType: application/json وresponseSchema في Gemini) يفرض الحقول vendor وdate وcategory وcurrency وline_items وsubtotal وtax وtotal بأنواعها الصحيحة، مع قائمة مغلقة لقيم category.

الشرح

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

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

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

• طلب الأرقام مجردة وبدون فواصل الآلاف أو رموز العملات: يوصي التوجيه باستخراج الأرقام كقيم عددية صرفة (مثال: 1500.50 بدلاً من 1,500.50 ر.ي أو SAR 1,500). هذا الاختيار يسهّل حياة الكود؛ إذ يمكنه إدخال هذه الأرقام مباشرة في خلايا Excel الرياضية وإجراء عمليات الجمع التلقائي دون الحاجة لكتابة دوال تنظيف نصوص معقدة لإزالة الرموز والفواصل يدوياً.

• تقييد تصنيف الفئات بقائمة مغلقة ومحددة مسبقاً: بدلاً من ترك الحبل على الغارب للنموذج ليخترع أسماء فئات من عنده (مما قد يجعله يصنف فاتورة سوبرماركت مرة كـ "أغذية"، ومرة كـ "بقالة"، ومرة كـ "مشتريات منزلية")، قيّدناه بقائمة خيارات ثابتة ومغلقة. هذا التقييد هو ما يجعل جدول "الإجمالي حسب الفئة" في التقرير دقيقاً وقابلاً للتجميع والمقارنة، بدلاً من الحصول على عشرين فئة مكررة بأسماء مختلفة قليلاً لا يمكن تجميعها.

• دمج التوجيه مع مخطط JSON صارم (responseSchema): للتأكيد على دقة الهيكلية، يُدمج التوجيه اللغوي مع ميزة Gemini المتمثلة في وضع المخطط الصارم وتفعيل responseMimeType=application/json. هذا صمام أمان مزدوج: بينما يشرح التوجيه المقصود بلغة طبيعية، يفرض المخطط البرمجي (Schema) الهيكل الميكانيكي للمخرجات بشكل إجباري وقاطع. هذا يضمن ألا يخرج رد النموذج عن صيغة JSON صالحة للقراءة برمجياً، وهو أمر بالغ الأهمية في عرض حي لا يحتمل توقفاً مفاجئاً.

الخلاصة الذهبية التي يجب أن تخرج بها اليوم: التوجيه الاحترافي لاستخراج البيانات = قائمة حقول واضحة ومحددة + تعليمات صارمة تمنع التخمين والهلوسة + قالب مخرجات مغلق ومقيَّد برمجياً. هذه هي الوصفة التي يمكنك تكرارها لأي مهمة أتمتة تحوّل صورة إلى بيانات رقمية منظمة في عملك.