عن المشروع

خدمة PolyOCR هي خدمة OCR متعددة اللغات وترجمة اختيارية وخدمة PaddleOCR-VL مستقلة، مبنية على PaddleOCR 3.x وFastAPI. يوضح المؤلف صراحة أن هذا مشروع مجتمعي وليس مكونًا رسميًا من PaddleOCR. القدرات والحدود تستدعي وظيفة OCR الأساسية predict() من PaddleOCR 3.x، وتتوافق مع نتائج التعيين/الكائنات في الإصدار 3.x ونتائج القوائم القديمة. تدعم 78 لغة تغطي أنظمة الكتابة الصينية واليابانية والكورية واللاتينية والسيريلية والعربية والديفاناغارية والتايلاندية واليونانية وغيرها، وتقبل ثلاثة أنواع من الأسماء المستعارة: رموز اللغات والأسماء الإنجليزية والأسماء الصينية (مثل fr / french / 法文). يتم التحقق من اللغة عند حدود الطلب، وتعيد اللغات غير المعروفة فورًا 422 unsupported_language دون انتظار تحميل النموذج. تخضع الصور قبل الاستدلال للتحقق من عدد البايتات ونتيجة فك الترميز وعدد البكسلات وحدود الثقة؛ يُنفَّذ الاستدلال المتزامن في مجموعة خيوط ويُقيَّد التزامن بواسطة سيمافور. يحدّد إدخال الترجمة عدد العناصر وإجمالي الأحرف، ويتطلب تطابق عدد ما يعيده المزود مع الإدخال. تستخدم أخطاء HTTP والمصادقة والتحقق من الطلبات وأخطاء النطاق بنية استجابة error موحدة. تقبل PaddleOCR-VL محتوى الرفع فقط وترفض عناوين URL، وتتطلب مفتاح API مستقلًا وتحدّ حجم الرفع. تستخدم صفحات المتصفح textContent لعرض نتائج الخادم ولا تفسر المحتوى المعاد كـ HTML. التثبيت والتشغيل يدعم Python 3.10 و3.11 و3.12 ويتم فحصها عبر CI. يتم التثبيت عبر pip install -e ".[dev,ocr]"، ثم نسخ .env.example إلى .env وتعديل مفتاح API قبل التشغيل. يستمع مدخل سطر الأوامر افتراضيًا على 127.0.0.1:8000، ويمكن ضبطه عبر POLYOCR_HOST / POLYOCR_PORT؛ يحذر README بشكل خاص من أن --host 0.0.0.0 سيعرّض الخدمة على جميع واجهات الشبكة، وهو أمر ضروري داخل الحاويات، لكن تشغيله مباشرة على حاسوب محمول أو شبكة مشتركة سيتيح لأي شخص في الشبكة المحلية الوصول إلى النسخة. تقع صفحة الويب في المسار الجذر، ووثائق API في /docs. نظرة عامة على API فحص الصحة /v1/health لا يتطلب مصادقة؛ يعيد /v1/languages رموز اللغات ورموز لغة PaddleOCR وأنظمة الكتابة والأسماء المستعارة المتاحة. يدعم طلب OCR على /v1/ocr المصادقة عبر X-API-Key أو Bearer Token، وتشمل حقول النموذج file وlanguage وscore_threshold، وتعيد الاستجابة رمز اللغة المعياري وتتضمن items (text وscore وbbox) وcost_ms وrequest_id وwarnings. تستقبل واجهة الترجمة /v2/translate الحقول texts وtarget_language. الاستجابات الفاشلة موحدة ككائن error يحتوي على code وmessage وrequest_id. تحذير الضبابية الحركية عندما يكون تباين لابلاس للصورة أقل من الحد (افتراضيًا 45.0، قابل للضبط عبر POLYOCR_BLUR_VARIANCE_FLOOR) لكن النموذج لا يزال يعيد نصًا بثقة عالية، تتضمن الاستجابة تحذير suspected_blur، مع ذكر تباين لابلاس والحد في detail. يشرح README الدافع: الضبابية الحركية تعيد نصًا بثقة طبيعية لكن محتواه خاطئ، ولم يكن بإمكان المتصل التمييز سابقًا، وهذا التحذير يحوّل "عدم القدرة على التمييز" إلى "القدرة على التمييز". يُقيَّم التحذير فقط عندما يعيد النموذج نصًا فعليًا، ولا تنتج النتائج الفارغة تحذيرًا. عناصر التكوين تسرد الوثائق مفتاح تشغيل المصادقة ومفتاح API، ومصادر CORS، والحد الأقصى لحجم الرفع (افتراضيًا 10MB)، والحد الأقصى للبكسلات بعد فك الترميز (افتراضيًا 25 مليون)، وعدد الاستدلالات المتزامنة (افتراضيًا 2)، وعدد خيوط عمل OCR، وحد تباين الضبابية، وحدود عناصر وأحرف الترجمة، ومفتاح/عنوان/نموذج خدمة الترجمة المتوافقة مع OpenAI، والمفتاح المستقل وحد الرفع لخدمة VL. ترفض الخدمة الأساسية بدء التشغيل عند تفعيل المصادقة مع كون POLYOCR_API_KEY فارغًا؛ تتطلب خدمة VL دائمًا POLYOCR_VL_API_KEY؛ ولا يُسمح بمصادر CORS شاملة عند استخدام بيانات الاعتماد. Docker والاختبارات يُتاح النشر عبر docker compose up --build، مع تثبيت الصورة على أساس Python 3.10، وتشغيلها كمستخدم غير جذر مع فحص صحة، وسيتم تنزيل النماذج عند أول عملية OCR، مع حفظ ذاكرة التخزين المؤقت في وحدة تخزين Compose. تشمل عملية الاختبار تنسيق وفحص ruff، واختبارات pytest غير التكاملية، وpython -m build؛ يتطلب OCR E2E الحقيقي ضبط POLYOCR_RUN_OCR_E2E=1 صراحةً، وقد ينزّل النماذج. يشغّل CI فقط الاختبارات السريعة التي لا تنزّل النماذج. المعايير والنتائج المقاسة تقارن معايير دقة اللغات الصور المُعلَّمة حسب اللغة، وتُبلِّغ عن exact (نسبة التطابق التام سطرًا بسطر) وcer (معدل خطأ الأحرف)، دون التأثر بترتيب الكشف. تغطي معايير المتانة الضبابية والضغط والدوران والتصغير والضوضاء والتباين الفاتح/الداكن والضبابية الحركية والمنظور والإضاءة غير المنتظمة والظلال ونسيج الورق وغيرها من التدهورات التصويرية. النتائج المقاسة في README هي: الدوران والمنظور وضغط JPEG والتباين الفاتح/الداكن والإضاءة غير المنتظمة والظلال ونسيج الورق لا تكاد تؤثر على التعرف، بل تحصل سيناريوهات التصوير المركبة على درجة كاملة؛ الفشل الحقيقي يقتصر على فقدان التفاصيل، أي ضبابية تتجاوز نحو σ2 أو تصغير إلى أقل من 25%. الأمر الوحيد الذي يستدعي الحذر هو الضبابية الحركية: عند إزاحة 15px يعيد نصًا خاطئًا بثقة طبيعية (Hello World → Heelco Ncotec)، بينما يكون طبيعيًا تمامًا ضمن 9px. معامل preprocess غير مُنفَّذ: خمس خطوط معالجة مسبقة حققت خسارة صافية على جميع التدهورات الـ17، وأضرّ التباين التلقائي بـ11 من 17، لذا يعيد preprocess=true الخطأ 400 preprocess_unsupported بدلًا من تجاهله بصمت. يستخدم معيار الصور الحقيقية CORD-v2 (CC-BY-4.0، مع تعليقات يدوية كلمة بكلمة) للقياس الفعلي، بمتوسط 0.975 exact للصور الاصطناعية و0.841 لاستدعاء الكلمات في الصور الحقيقية، ويذكر README أن درجات الصور الاصطناعية متفائلة بنحو 13 نقطة. المعالجة المسبقة على الصور الحقيقية موجبة في المتوسط لثلاث خطوط، لكن اختبار bootstrap يُظهر أن فترات الثقة 95% لجميع الخطوط الخمسة تعبر الصفر، بأصغر قيمة p تساوي 0.371، ويبقى الاستنتاج "لا توجد فائدة قابلة للكشف إحصائيًا". الترخيص يستخدم Apache License 2.0، بما يتوافق مع PaddleOCR الأصلية، مع تسجيل إسنادات الأطراف الثالثة في NOTICE. تُنزَّل نماذج PaddleOCR وقت التشغيل من موزعيها الأصليين وتخضع لتراخيصهم وشروط استخدامهم.