تصنيف ملفات PDF في .NET: دليل تعليمي وعينة كود

تصنيف ملفات PDF في .NET أمر أساسي لأتمتة تدفقات عمل المستندات، واستخراج الرؤى، وتوجيه المحتوى دون مراجعة يدوية. يوفر GroupDocs.Classification Cloud SDK for .NET واجهة برمجة تطبيقات قوية تجعل تصنيف PDF سهلًا وقابلًا للتوسع. في هذا البرنامج التعليمي ستتعلم سير عمل كامل لتصنيف PDF، بدءًا من إعداد المشروع وتكوين التصنيف الهرمي إلى المعالجة الدفعية، ومعالجة OCR لملفات PDF الممسوحة ضوئيًا، وتحسين الأداء، مع أمثلة شفرة جاهزة للتنفيذ.

خطوات تصنيف ملفات PDF في .NET

1. إضافة حزمة NuGet - قم بتشغيل dotnet add package GroupDocs.Classification-Cloud لتضمين المكتبة في مشروعك.
2. إنشاء وتكوين عميل API - قم بتهيئة ClassificationApi باستخدام معرف العميل والسر.
3. رفع ملف PDF - استخدم نقطة النهاية UploadFile لإرسال المستند إلى التخزين السحابي.
4. تحديد التصنيف الهرمي - قدّم ملف JSON يربط الفئات بالكلمات المفتاحية؛ هذا يوجه محرك التصنيف.
5. استدعاء طريقة التصنيف - استدعِ ClassifyDocument مع معرف الملف، والتصنيف الهرمي، وعامل عتبة الثقة الاختياري.
6. معالجة النتائج - تكرّر عبر كائنات ClassificationResult، وتحقق من خاصية Confidence لتصفية التسميات ذات الثقة المنخفضة.

لمزيد من التفاصيل حول كائنات الطلب، راجع مرجع API.

تصنيف ملفات PDF بكفاءة في .NET - مثال كامل على الكود

يوضح المثال التالي تصنيفًا شاملاً من البداية إلى النهاية لملف PDF واحد، بما في ذلك معالجة الأخطاء ومعالجة النتائج.

ملاحظة: يوضح مثال الشيفرة هذا الوظيفة الأساسية. قبل استخدامه في مشروعك، تأكد من تحديث مسارات الملفات (sample.pdf, taxonomy.json)، واستبدال بيانات الاعتماد النائبة ببياناتك الفعلية YOUR_CLIENT_ID و YOUR_CLIENT_SECRET، واختبر بدقة في بيئة التطوير الخاصة بك. إذا واجهت أي مشكلات، يرجى الرجوع إلى الوثائق الرسمية أو التواصل مع فريق الدعم للحصول على المساعدة.

تصنيف PDF عبر REST API باستخدام cURL

يعمل SDK عبر REST API، لذا يمكنك أيضًا استدعاؤه مباشرةً باستخدام cURL. فيما يلي الخطوات النموذجية.

1. الحصول على رمز وصول

curl -X POST "https://api.groupdocs.cloud/v1.0/oauth2/token" \
     -H "Content-Type: application/json" \
     -d '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET","grant_type":"client_credentials"}'

2. رفع ملف PDF

curl -X POST "https://api.groupdocs.cloud/v1.0/storage/file/upload" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -F "file=@sample.pdf"

3. تصنيف المستند

curl -X POST "https://api.groupdocs.cloud/v1.0/classification/classify" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "fileId": "sample.pdf",
           "taxonomy": "{\"categories\":[{\"name\":\"Invoice\",\"keywords\":[\"amount\",\"total\",\"invoice\"]}]}",
           "confidenceThreshold": 0.6
         }'

4. تنزيل النتيجة (إذا لزم الأمر) - تُعيد الواجهة البرمجية JSON مباشرةً؛ يمكنك توجيهها إلى ملف.

لمزيد من التفاصيل، راجع وثائق API الرسمية.

التثبيت والإعداد في .NET

1. تثبيت حزمة NuGet

   dotnet add package GroupDocs.Classification-Cloud
   

2. تنزيل أحدث ملف ثنائي (اختياري) من صفحة الإصدار.
3. إضافة الترخيص المؤقت الخاص بك (للتطوير فقط) عن طريق نسخ ملف الترخيص وتهيئة كائن Configuration كما هو موضح في مثال الشيفرة.
4. تحقق من الاتصال - نفّذ استدعاء بسيط GetSupportedFileTypes للتأكد من أن العميل يمكنه الوصول إلى الخدمة.

استخدام GroupDocs.Classification Cloud SDK لتصنيف ملفات PDF في .NET

يقوم SDK بتجريد معالجة HTTP، والتسلسل، وتعيين الأخطاء، مما يتيح لك التركيز على منطق الأعمال. يدعم:

• لغات متعددة - الواجهة البرمجية لا تعتمد على لغة معينة؛ عميل .NET يتبع نفس العقد.
• تصنيف مستند إلى التصنيف الهرمي - تقوم بتعريف الفئات مرة واحدة وتعيد استخدامها عبر المشاريع.
• تقييم الثقة - كل تسمية تتضمن قيمة ثقة، مما يتيح تصفية بناءً على العتبة.

فهم هذه الميزات يساعدك على تصميم سير عمل تصنيف PDF قوي.

ميزات GroupDocs.Classification Cloud SDK التي تهم هذه المهمة

• المعالجة الدفعية - تصنيف آلاف ملفات PDF في طلب واحد.
• تكامل OCR - استخراج النص تلقائيًا من ملفات PDF الممسوحة ضوئيًا قبل التصنيف.
• دعم تصنيف مخصص - تحميل تصنيفات JSON أو XML لتتناسب مع مجال عملك.
• تسجيل مفصل - استرجاع معرفات الطلبات للتشخيص وتتبع التدقيق.

تكوين تصنيف التصنيف وحدود الثقة

أنشئ ملف taxonomy.json يصف الفئات الخاصة بك:

{
  "categories": [
    {
      "name": "Invoice",
      "keywords": ["invoice", "amount", "total", "due"]
    },
    {
      "name": "Resume",
      "keywords": ["experience", "education", "skills", "profile"]
    }
  ]
}

عند إنشاء ClassifyDocumentRequest، قم بتعيين خاصية ConfidenceThreshold (مثلاً 0.6) لتصفية التنبؤات غير المؤكدة. اضبط هذه القيمة بناءً على تحمل نطاقك للنتائج الإيجابية الخاطئة.

تحسين الأداء لمجموعات PDF الكبيرة

• تقسيم الدفعة - قسّم المجموعات الكبيرة إلى مجموعات من 100‑200 ملف لتجنب انتهاء المهلة.
• تمكين المعالجة غير المتزامنة - استخدم نقطة النهاية SubmitJob واستعلم GetJobStatus لتحرير الخيوط.
• إعادة استخدام نفس التصنيف - حمّل التصنيف مرة واحدة وأعد استخدام نفس سلسلة JSON لجميع الطلبات.
• التحميل المتوازي - حمّل الملفات بشكل متزامن باستخدام Task.WhenAll لتقليل زمن استجابة الشبكة.

معالجة ملفات PDF الممسوحة ضوئياً وتكامل OCR

تحتوي المستندات الممسوحة ضوئياً على صور بدلاً من النص القابل للتحديد. لتصنيفها:

1. اضبط علامة ocr إلى true في الطلب.
2. يمكنك اختيارياً تحديد ocrLanguage (مثال: "en" للإنجليزية).
3. تقوم الخدمة بتنفيذ OCR داخليًا قبل تطبيق قواعد التصنيف.

تضمن هذه العملية ذات الخطوتين أن يتم التعامل مع ملفات PDF التي تحتوي على صور فقط بنفس الطريقة التي يتم بها التعامل مع ملفات PDF الأصلية للتصنيف.

استكشاف أخطاء التصنيف الشائعة وإصلاحها

• 401 Unauthorized - تحقق من أن ClientId و ClientSecret صحيحان وأن طلب الرمز المميز نجح.
• 400 Bad Request (Invalid Taxonomy) - تأكد من أن JSON الخاص بالتصنيف مُشكل بشكل صحيح؛ فقدان الأقواس يسبب هذا الخطأ.
• 404 Not Found (File ID) - أكد أن الملف تم تحميله بنجاح وأن fileId يتطابق مع مسار التخزين.
• Low confidence scores - راجع كلمات مفتاح التصنيف الخاصة بك؛ أضف مصطلحات أكثر تمثيلاً أو زد مجموعة التدريب.

للحصول على قائمة كاملة بأكواد الأخطاء، راجع مرجع API.

أفضل الممارسات لتصنيف PDF في .NET

• حافظ على تصنيف صغير ومركز - وجود الكثير من الكلمات المفتاحية المتداخلة يقلل من الدقة.
• استخدم ملفات تصنيف بإصدارات - احفظها في نظام التحكم بالمصادر لتتبع التغييرات.
• حدد عتبة ثقة مناسبة - ابدأ بـ 0.6 واضبطها بناءً على نتائج التحقق.
• راقب حالة المهمة - سجّل معرفات الطلب وأوقات الاستجابة لتحليل الأداء.
• أمن الاعتمادات - احفظ ClientId و ClientSecret في متغيّرات البيئة أو Azure Key Vault.

الخلاصة

تصنيف ملفات PDF في .NET يصبح بسيطًا مع GroupDocs.Classification Cloud SDK for .NET. باتباع الخطوات المذكورة أعلاه لإعداد SDK، وتعريف تصنيف واضح، ومعالجة OCR لملفات PDF الممسوحة ضوئيًا، وتحسين أداء الدُفعات، يمكنك بناء خدمة تصنيف موثوقة وقابلة للتوسع لأي تطبيق يركز على المستندات. تذكر الحصول على ترخيص مناسب للاستخدام الإنتاجي؛ يمكنك البدء بترخيص مؤقت من صفحة الترخيص المؤقت والترقية إلى اشتراك كامل مع تزايد احتياجاتك.

الأسئلة المتكررة

س: كيف يمكنني تصنيف ملفات PDF في .NET بثقة عالية؟
ج: قم بتعيين ConfidenceThreshold في الطلب لتصفية النتائج ذات الثقة المنخفضة. تُعيد SDK درجة ثقة لكل تسمية، مما يتيح لك الاحتفاظ فقط بالتنبؤات التي تتجاوز المستوى الذي اخترته. راجع الوثائق الرسمية لمزيد من التفاصيل.

س: هل يدعم SDK تقنية OCR لملفات PDF الممسوحة ضوئياً؟
A: نعم. قم بتمكين OCR عن طريق ضبط علامة ocr في طلب التصنيف. تقوم الخدمة باستخراج النص من ملفات PDF القائمة على الصور قبل تطبيق التصنيف الهرمي، مما يحسن الدقة للوثائق الممسوحة ضوئياً.

س: ما هي أفضل طريقة لمعالجة آلاف ملفات PDF؟
ج: استخدم التصنيف الدفعي مع الوظائف غير المتزامنة. قسّم المجموعات الكبيرة إلى أجزاء يمكن التحكم فيها، قدّمها عبر SubmitJob، وتحقق من الحالة عبر GetJobStatus حتى الانتهاء. يضمن هذا النهج تجنب مهلات الوقت ويزيد من الإنتاجية.

س: أين يمكنني الحصول على ترخيص مؤقت للتطوير؟
ج: قم بزيارة صفحة الترخيص المؤقت لإنشاء مفتاح ترخيص لمدة 30‑يوم. طبّقها في Configuration قبل إجراء مكالمات API.

اقرأ المزيد

• تصنيف المستندات والنص الخام باستخدام C#
• تحليل المشاعر للنص أو المستندات باستخدام واجهة برمجة تطبيقات REST في C#
• تصنيف النص الخام في MS Office و PDF والعديد من المستندات الأخرى باستخدام cURL