fix: make OCR portable and reliable across AMD64 and ARM64 (#519)

* fix: make OCR portable and reliable

* fix: harden OCR installation portability

* fix: pin OCR partials across downloads

* fix: make OCR execution reliably asynchronous

* fix: harden OCR portability and docs routes

* fix: preserve decoder and docs safeguards

apps/docs/ar/api/ai.md

@@ -1,18 +1,26 @@
 ---
 description: "مرجع محرك الذكاء الاصطناعي مع جميع أدوات التعلم الآلي المحلية. إزالة الخلفية، وتحسين الدقة، وقراءة النصوص (OCR)، واكتشاف الوجوه، وترميم الصور، والمزيد."
-i18n_source_hash: 14728c1dcd05
-i18n_provenance: machine
-i18n_output_hash: 7aeaaf9da34e
+i18n_output_hash: 778d92965216
+i18n_source_hash: aa9a56cdddc7
+i18n_provenance: human
 ---
 
 # مرجع محرك الذكاء الاصطناعي {#ai-engine-reference}
 
-تربط الحزمة `@snapotter/ai` بين Node.js و**عملية Python جانبية دائمة** لجميع عمليات التعلم الآلي. تبقى عملية الموزّع نشطة بين الطلبات لأداء بدء دافئ سريع. يُكتشف NVIDIA CUDA تلقائيًا عند بدء التشغيل ويُستخدم عند توفره؛ وإلا فإن أدوات الذكاء الاصطناعي تعمل على وحدة المعالجة المركزية.
+تقوم حزمة `@snapotter/ai` بتنسيق الأدوات الأصلية وأوقات تشغيل Python لعمليات ML المحلية. تستخدم معظم أدوات ML Python sidecar المستمر لبدء التشغيل الدافئ السريع. OCR منفصل عمدا: يستدعي `fast` ثنائي Tesseract الأصلي، بينما يستخدم `balanced` و`best` JSONL dispatcher المستمر المخصص والمثبت على جيل RapidOCR النشط غير القابل للتغيير ضمن `/data/ai/v3`. يحمل كل طلب generation lease. أثناء الترقية، يقوم SnapOtter بتشغيل smoke test على المرشح قبل التنشيط، ويتحول تلقائيًا إلى dispatcher الجديد، ثم يستنزف الجيل القديم قبل garbage collection.
+
+يتم اكتشاف NVIDIA CUDA تلقائيًا ويتم استخدامه في أوقات التشغيل التي تدعمه. يستخدم OCR CPU على كل مضيف، بما في ذلك الأنظمة التي تحتوي على وحدات معالجة الرسومات NVIDIA، مع تجنب CUDA واقتران برنامج التشغيل لهذه الأداة.
 
 تسريع وحدة معالجة الرسومات المدمجة من Intel/AMD عبر VA-API أو Quick Sync أو OpenCL غير مدعوم لاستدلال الذكاء الاصطناعي حاليًا. تعيين `/dev/dri` داخل حاوية لا يسرّع أدوات Python الجانبية هذه ما لم تتوفر وحدة معالجة رسومات NVIDIA قادرة على تشغيل CUDA.
 
 19 أداة ذكاء اصطناعي تعمل عبر Python الجانبية موزّعة على أربع طرائق (صورة، وصوت، وفيديو، ومستند)، بالإضافة إلى أداتين ذواتَي قدرات ذكاء اصطناعي اختيارية. تعمل جميع النماذج محليًا، ولا حاجة للإنترنت بعد التنزيل الأولي للنموذج.
 
+
+<!-- korean-ocr-contract:start -->
+::: info توافق OCR الكوري
+يدعم Fast OCR اللغات `auto` و`en` و`de` و`es` و`fr` و`zh` و`ja`، لكنه لا يدعم الكورية (`ko`). تتطلب الكورية حزمة OCR الدقيقة ومستوى `balanced` أو `best`. تعمل الحزمة على حاويات Linux amd64 وarm64 الرسمية، بما في ذلك مضيفات NVIDIA حيث يبقى OCR على CPU. تُرجع الأنظمة غير المدعومة خطأ توافق صريحاً ولا تعود بصمت إلى `fast`. كما يُرفض طلب Korean مع `fast` أو الاسم القديم `tesseract` قبل وضعه في قائمة الانتظار، مع `FEATURE_INCOMPATIBLE` والسبب `fast-korean-unsupported`.
+:::
+<!-- korean-ocr-contract:end -->
 ## البنية المعمارية {#architecture}
 
 ```
@@ -22,15 +30,17 @@ Node.js Tool Route
  @snapotter/ai bridge.ts
       | (stdin/stdout JSON + stderr progress events)
       v
- Python dispatcher (persistent process, "ai" profile)
+ +-- Native Tesseract + Ghostscript (fast image/PDF OCR)
+ |
+ +-- Isolated OCR runtime (persistent JSONL dispatcher)
+ |     `-- RapidOCR + ONNX Runtime CPU + pinned PP-OCR models
+ |
+ `-- Python dispatcher (persistent process, "ai" profile)
       |
       |-- remove_bg.py        (rembg / BiRefNet)
       |-- upscale.py          (RealESRGAN)
       |-- inpaint.py          (LaMa ONNX)
       |-- outpaint.py         (LaMa canvas expansion)
-      |-- ocr.py              (PaddleOCR / Tesseract)
-      |-- ocr_pdf.py          (page-by-page document OCR)
-      |-- ocr_preprocess.py   (image enhancement for OCR)
       |-- detect_faces.py     (MediaPipe)
       |-- face_landmarks.py   (MediaPipe landmarks)
       |-- enhance_faces.py    (GFPGAN / CodeFormer)
@@ -52,7 +62,7 @@ Node.js Tool Route
 
 تشحن صورة Docker التطبيقَ إضافةً إلى وقت التشغيل المشترك. تُنزَّل أرشيفات النماذج الكبيرة عند الطلب إلى وحدة التخزين الدائمة `/data/ai`، ثم تُعاد استخدامها من قِبل كل أداة تحتاجها. إذا كانت الحزمة مثبّتة بالفعل لأن أداة أخرى احتاجتها، فإن تفعيل أداة جديدة معتمدة عليها لا يُعيد تنزيل تلك الحزمة.
 
-تتطلب كل أداة ذكاء اصطناعي حزمة ميزات واحدة أو أكثر قبل أن تتمكن من العمل. تُثبِّت واجهة المسؤول حسب الأداة عبر `POST /api/v1/admin/tools/:toolId/features/install`، التي تحلّ قائمة الحزم الكاملة، وتتجاوز الحزم المثبّتة بالفعل، وتُدرِج فقط التنزيلات المفقودة في قائمة الانتظار. على سبيل المثال، تفعيل صورة جواز السفر على نسخة جديدة يُدرِج `background-removal` و`face-detection` في قائمة الانتظار؛ أما تفعيلها بعد تثبيت إزالة الخلفية بالفعل فيُدرِج `face-detection` فقط.
+تتطلب معظم أدوات الذكاء الاصطناعي حزمة ميزات واحدة أو أكثر قبل أن تتمكن من التشغيل. تقوم واجهة المستخدم الإدارية بتثبيت تلك عن طريق الأداة من خلال `POST /api/v1/admin/tools/:toolId/features/install`، الذي يحل قائمة الحزم الكاملة، ويتخطى الحزم المثبتة بالفعل، ويضع التنزيلات المفقودة فقط في قائمة الانتظار. على سبيل المثال، تمكين صورة جواز السفر في قائمة انتظار المثيلات الجديدة `background-removal` و`face-detection`؛ تمكينه بعد تثبيت بالفعل قوائم الانتظار إزالة الخلفية فقط `face-detection`. OCR هو الاستثناء لأن `fast` لا يحتاج إلى حزمة؛ قم بتثبيت وقت التشغيل الدقيق الاختياري من خلال واجهة المستخدم أو `POST /api/v1/admin/features/ocr/install`.
 
 | الحزمة | الحجم | مجموعة التبعيات المشتركة | الأدوات التي تستخدمها |
 |--------|------|-------------------------|-------------------|
@@ -61,7 +71,7 @@ Node.js Tool Route
 | `object-eraser-colorize` | 1-2 GB | الرسم الداخلي/الخارجي بـ LaMa و DDColor | erase-object, colorize, ai-canvas-expand |
 | `upscale-enhance` | 5-6 GB | RealESRGAN و GFPGAN / CodeFormer وإزالة التشويش | upscale, enhance-faces, noise-removal |
 | `photo-restoration` | 4-5 GB | مسار إصلاح الخدوش والترميم | restore-photo |
-| `ocr` | 5-6 GB | حزمة قراءة النصوص PaddleOCR / Tesseract | ocr, ocr-pdf |
+| `ocr` | ~208-234 MiB تنزيل / ~409-488 MiB مثبتة | اختياري RapidOCR 3.9.1، ONNX Runtime 1.20.1، ونماذج PP-OCR المثبتة | ocr وocr-pdf (`balanced` و`best` فقط) |
 | `transcription` | ~600 MB | نماذج تحويل الكلام إلى نص faster-whisper | transcribe-audio, auto-subtitles |
 
 أدوات ذات تبعيات عبر عدة حزم:
@@ -71,7 +81,17 @@ Node.js Tool Route
 | `passport-photo` | `background-removal`، `face-detection` | يزيل الخلفية، ثم يستخدم معالم الوجه لتأطير القص وفق قواعد صور جواز السفر والهوية. |
 | `enhance-faces` | `upscale-enhance`، `face-detection` | يكتشف الوجوه قبل تشغيل تحسين GFPGAN أو CodeFormer على مناطق الوجه المحددة. |
 
-تتوفر الأداة فقط عندما تكون جميع حزمها المطلوبة مثبّتة. عمليات التثبيت الجزئية صالحة وتُعالَج تدريجيًا: تُعاد استخدام الحزم المثبّتة، وتُعرَض الحزم المفقودة على أنها تنزيلات، وتُشغَّل عمليات التثبيت المُدرَجة في قائمة الانتظار واحدة تلو الأخرى بحيث لا تُعدَّل بيئة Python المشتركة بالتزامن.
+تتوفر الأداة فقط عند تثبيت جميع الحزم المطلوبة، باستثناء OCR: تظل طبقة `fast` المضمنة متاحة بدون حزمة OCR الاختيارية. عمليات التثبيت الجزئية صالحة ويتم التعامل معها بشكل متزايد: تتم إعادة استخدام الحزم المثبتة، وتظهر الحزم المفقودة كتنزيلات، ويتم تشغيل عمليات التثبيت الموضوعة في قائمة الانتظار واحدًا تلو الآخر حتى لا يتم تعديل بيئة Python المشتركة بشكل متزامن.
+
+### التثبيت الدقيق لوقت تشغيل OCR {#accurate-ocr-runtime-installation}
+
+تعد حزمة OCR الدقيقة بمثابة وقت تشغيل خاص بالمنصة لحاوية Linux amd64 أو Linux arm64 الرسمية. يستخدم الإصدار amd64 Python 3.12؛ يستخدم الإصدار arm64 Python 3.11. يعمل كلا الإصدارين على تشغيل RapidOCR من خلال ONNX Runtime's `CPUExecutionProvider`، لذا فإن نفس الحزمة تعمل على وحدة المعالجة المركزية (CPU) فقط ومضيفي NVIDIA Docker. يتطلب وقت التشغيل الدقيق ما لا يقل عن 4 GiB من الذاكرة الفعالة: الحد الأقصى للحاوية التي تم تكوينها cgroup، خلاف ذلك الذاكرة المضيفة. يتم رفض النظام الموجود أسفل الحد الأدنى من التوافق الموقع قبل التنزيل. لا ينطبق هذا المتطلب على Fast OCR المدمج. تم رفض إصدارات Bare-metal لأنه لا يمكن استنتاج libc و Python ABI بشكل آمن؛ يظل OCR السريع متاحًا عندما يوفر المضيف Tesseract و Ghostscript.
+
+يكون المنتج الاختياري حوالي 208-234 MiB مضغوطًا و409-488 MiB مستخرجًا، اعتمادًا على البنية. يربط الفهرس الموقع عدد البايتات المضغوطة والمستخرجة بدقة والذي يفرضه المثبت. يضيف Tesseract المدمج حوالي 25 MiB إلى الصورة الرسمية ولا يحتاج إلى ملفات في `/data/ai`.
+
+يجلب التثبيت عبر الإنترنت فهرس الإصدار الموقع والمحتوى المحدد الذي يتناوله النظام الأساسي الحالي. يتحقق SnapOtter من توقيع فهرس Ed25519، وحجم القطعة الأثرية، وملخص SHA-256، وملخصات النموذج، والمسارات، وأوضاع الملفات، و smoke test المرحلي قبل تنشيط الجيل الجديد ذريًا. يؤدي التثبيت الفاشل إلى ترك الجيل السليم السابق نشطًا.
+
+للتثبيت الهوائي، قم بتحميل كل من `ocr-runtime-index.json` الخاص بالإصدار وأرشيف وقت تشغيل OCR المطابق إلى `POST /api/v1/admin/features/import` باستخدام حقول متعددة الأجزاء تسمى `index` و`archive`. يطبق الاستيراد دون اتصال نفس عمليات التحقق من التوقيع والتجزئة والاستخراج والتوافق واختبار الدخان مثل التثبيت عبر الإنترنت؛ يتم رفض الأرشيف الذي لا يحتوي على الفهرس الموقع الموثوق به.
 
 ---
 
@@ -143,16 +163,16 @@ Node.js Tool Route
 ## قراءة النصوص (OCR) / استخراج النص {#ocr-text-extraction}
 
 **مسار الأداة:** `ocr`  
-**النماذج:** Tesseract (سريع)، PaddleOCR PP-OCRv5 (متوازن)، PaddleOCR-VL 1.5 (الأفضل)
+**النماذج:** Tesseract (`fast`)؛ RapidOCR مع نماذج PP-OCRv6 الصغيرة (`balanced`)؛ الطرازات المتوسطة PP-OCRv6 مع تسجيل متغير مُعاير (`best`)
 
 | المعامل | النوع | الافتراضي | الوصف |
 |-----------|------|---------|-------------|
-| `quality` | `"fast"` \| `"balanced"` \| `"best"` | `"balanced"` | طبقة المعالجة |
+| `quality` | `"fast"` \| `"balanced"` \| `"best"` | متحرك | عند حذف `quality` و`engine`، يختار SnapOtter أعلى مستوى متاح بالترتيب: `best` ثم `balanced` ثم `fast`. لا تختار اللغة الكورية `fast` أبداً؛ بل تستخدم `best` ثم `balanced`، أو تُرجع خطأ تثبيت أو توافق لوقت التشغيل الدقيق. |
 | `language` | نص | `"auto"` | اللغة: `auto`، `en`، `de`، `fr`، `es`، `zh`، `ja`، `ko` |
-| `enhance` | منطقي | `true` | معالجة الصورة مسبقًا لتحسين دقة قراءة النصوص |
-| `engine` | نص | - | مهمَل. يعيّن `tesseract` إلى `fast`، و`paddleocr` إلى `balanced` |
+| `enhance` | منطقية | تعتمد على الطبقة | تحسين التباين المحلي. سريع يطبقه مباشرة؛ تحافظ الطبقات الدقيقة على المتغير فقط عندما يؤدي تسجيل المعايرة إلى تحسين OCR. الإعدادات الافتراضية للأفضل |
+| `engine` | خيط | - | الاسم المستعار للتوافق مهمل. تعيين `tesseract` إلى `fast` وقيمة `paddleocr` القديمة إلى `balanced`؛ لا يتم تحميل PaddlePaddle |
 
-يُرجِع نتائج مهيكلة مع مربعات إحاطة، ودرجات ثقة، وكتل نص مستخرجة.
+إرجاع النص المستخرج بالإضافة إلى بيانات تعريف المصدر: المحرك، والجودة المطلوبة والفعلية، والجهاز، والموفر، وحالة التدهور، والتحذيرات، وإصدارات وقت التشغيل/الطراز الدقيقة عند الاقتضاء. طلبات الجودة الصريحة لا تعود أبدًا إلى مستوى آخر. في حالة عدم توفر `balanced` أو `best`، تقوم API بإرجاع `FEATURE_NOT_INSTALLED` أو `FEATURE_INCOMPATIBLE` بدلاً من تشغيل `fast` بصمت.
 
 ## قراءة نصوص PDF {#pdf-ocr}
 
@@ -163,9 +183,13 @@ Node.js Tool Route
 
 | المعامل | النوع | الافتراضي | الوصف |
 |-----------|------|---------|-------------|
-| `quality` | `"fast"` \| `"balanced"` \| `"best"` | `"balanced"` | طبقة المعالجة |
+| `quality` | `"fast"` \| `"balanced"` \| `"best"` | متحرك | عند حذف `quality` و`engine`، يختار SnapOtter أعلى مستوى متاح بالترتيب: `best` ثم `balanced` ثم `fast`. لا تختار اللغة الكورية `fast` أبداً؛ بل تستخدم `best` ثم `balanced`، أو تُرجع خطأ تثبيت أو توافق لوقت التشغيل الدقيق. |
 | `language` | نص | `"auto"` | اللغة: `auto`، `en`، `de`، `fr`، `es`، `zh`، `ja`، `ko` |
 | `pages` | نص | `"all"` | تحديد الصفحات: `"all"`، `"1-3"`، `"1,3,5"` |
+| `enhance` | منطقية | تعتمد على الطبقة | تحسين التباين المحلي. سريع يطبقه مباشرة؛ تحافظ الطبقات الدقيقة على المتغير فقط عندما يؤدي تسجيل المعايرة إلى تحسين OCR. الإعدادات الافتراضية للأفضل |
+| `engine` | خيط | - | الاسم المستعار للتوافق مهمل. تعيين `tesseract` إلى `fast` وقيمة `paddleocr` القديمة إلى `balanced`؛ لا يتم تحميل PaddlePaddle |
+
+تنطبق نفس قاعدة عدم الرجوع إلى الإصدار السابق على PDF OCR. يتم تنقيط صفحات PDF قبل التعرف عليها، ويمكن لطلب واحد تحديد 50 صفحة على الأكثر.
 
 ## طمس الوجوه / المعلومات الشخصية {#face-pii-blur}