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/hi/api/ai.md

@@ -1,18 +1,26 @@
 ---
 description: "सभी लोकल ML टूल के साथ AI इंजन संदर्भ। बैकग्राउंड हटाना, अपस्केलिंग, OCR, फेस डिटेक्शन, फोटो रिस्टोरेशन, और बहुत कुछ।"
-i18n_source_hash: 14728c1dcd05
-i18n_provenance: machine
-i18n_output_hash: f892a5e5bfe5
+i18n_output_hash: 2ed3bda381fa
+i18n_source_hash: aa9a56cdddc7
+i18n_provenance: human
 ---
 
 # AI इंजन संदर्भ {#ai-engine-reference}
 
-`@snapotter/ai` पैकेज सभी ML ऑपरेशन के लिए Node.js को एक **स्थायी Python साइडकार** से जोड़ता है। फास्ट वार्म-स्टार्ट प्रदर्शन के लिए डिस्पैचर प्रोसेस अनुरोधों के बीच जीवित रहती है। स्टार्टअप पर NVIDIA CUDA स्वतः पहचाना जाता है और उपलब्ध होने पर उपयोग किया जाता है; अन्यथा AI टूल CPU पर चलते हैं।
+`@snapotter/ai` पैकेज स्थानीय ML संचालन के लिए मूल उपकरण और Python रनटाइम का समन्वय करता है। अधिकांश 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 GPU वाले सिस्टम भी शामिल हैं, इस टूल के लिए CUDA और ड्राइवर कपलिंग से बचा जाता है।
 
 VA-API, Quick Sync, या OpenCL के माध्यम से Intel/AMD iGPU त्वरण आज AI इन्फेरेंस के लिए समर्थित नहीं है। किसी कंटेनर में `/dev/dri` को मैप करना इन Python साइडकार टूल को तेज़ नहीं करता जब तक कोई CUDA-सक्षम NVIDIA GPU उपलब्ध न हो।
 
 चार मोडैलिटी (image, audio, video, document) में 19 Python साइडकार AI टूल, साथ ही वैकल्पिक AI क्षमताओं वाले 2 टूल। सभी मॉडल लोकल रूप से चलते हैं; प्रारंभिक मॉडल डाउनलोड के बाद इंटरनेट की आवश्यकता नहीं।
 
+
+<!-- korean-ocr-contract:start -->
+::: info कोरियाई OCR संगतता
+तेज़ OCR `auto`, `en`, `de`, `es`, `fr`, `zh` और `ja` का समर्थन करता है, लेकिन कोरियाई (`ko`) का नहीं। कोरियाई के लिए सटीक OCR पैक और `balanced` या `best` आवश्यक है। पैक आधिकारिक Linux amd64 और arm64 कंटेनरों पर चलता है; NVIDIA होस्ट पर भी OCR CPU पर ही चलता है। असमर्थित सिस्टम स्पष्ट संगतता त्रुटि लौटाते हैं और चुपचाप `fast` पर वापस नहीं जाते। कोरियाई के साथ `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 @@ AI मॉडल साझा डिपेंडेंसी स्टैक द
 
 Docker इमेज एप्लिकेशन के साथ-साथ सामान्य रनटाइम भेजती है। बड़े मॉडल आर्काइव माँग पर स्थायी `/data/ai` वॉल्यूम में डाउनलोड किए जाते हैं, फिर हर उस टूल द्वारा पुनः उपयोग किए जाते हैं जिसे उनकी आवश्यकता होती है। यदि कोई बंडल पहले से इंस्टॉल है क्योंकि किसी अन्य टूल को उसकी आवश्यकता थी, तो एक नया आश्रित टूल सक्षम करना उस बंडल को दोबारा डाउनलोड नहीं करता।
 
-प्रत्येक AI टूल को चलने से पहले एक या अधिक फ़ीचर बंडल की आवश्यकता होती है। एडमिन UI `POST /api/v1/admin/tools/:toolId/features/install` के माध्यम से टूल के हिसाब से इंस्टॉल करता है, जो पूरी बंडल सूची को हल करता है, पहले से इंस्टॉल बंडल छोड़ देता है, और केवल छूटे हुए डाउनलोड को कतारबद्ध करता है। उदाहरण के लिए, किसी ताज़ा इंस्टेंस पर Passport Photo सक्षम करना `background-removal` और `face-detection` को कतारबद्ध करता है; Background Removal पहले से इंस्टॉल होने के बाद इसे सक्षम करना केवल `face-detection` को कतारबद्ध करता है।
+अधिकांश एआई टूल को चलने से पहले एक या अधिक फीचर बंडलों की आवश्यकता होती है। व्यवस्थापक यूआई उन्हें `POST /api/v1/admin/tools/:toolId/features/install` के माध्यम से टूल द्वारा इंस्टॉल करता है, जो पूर्ण बंडल सूची को हल करता है, पहले से इंस्टॉल किए गए बंडलों को छोड़ देता है, और केवल लापता डाउनलोड को कतार में रखता है। उदाहरण के लिए, पासपोर्ट फोटो को ताजा इंस्टेंस कतारों `background-removal` और `face-detection` पर सक्षम करना; बैकग्राउंड रिमूवल के बाद इसे सक्षम करने से केवल `face-detection` कतारें पहले से ही स्थापित हैं। OCR अपवाद है क्योंकि `fast` को किसी पैक की आवश्यकता नहीं है; UI या `POST /api/v1/admin/features/ocr/install` के माध्यम से इसका वैकल्पिक सटीक रनटाइम स्थापित करें।
 
 | बंडल | आकार | साझा डिपेंडेंसी समूह | इसका उपयोग करने वाले टूल |
 |--------|------|-------------------------|-------------------|
@@ -61,7 +71,7 @@ Docker इमेज एप्लिकेशन के साथ-साथ स
 | `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, ocr-pdf |
+| `ocr` | ~208-234 MiB डाउनलोड / ~409-488 MiB स्थापित | वैकल्पिक RapidOCR 3.9.1, ONNX Runtime 1.20.1, और पिन किए गए PP-OCR मॉडल | ओसीआर, ओसीआर-पीडीएफ (केवल `balanced` और `best`) |
 | `transcription` | ~600 MB | faster-whisper स्पीच-टू-टेक्स्ट मॉडल | transcribe-audio, auto-subtitles |
 
 क्रॉस-बंडल डिपेंडेंसी वाले टूल:
@@ -71,7 +81,17 @@ Docker इमेज एप्लिकेशन के साथ-साथ स
 | `passport-photo` | `background-removal`, `face-detection` | बैकग्राउंड हटाता है, फिर पासपोर्ट और ID फोटो नियमों के अनुसार क्रॉप को फ्रेम करने के लिए फेस लैंडमार्क का उपयोग करता है। |
 | `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 के `CPUExecutionProvider` के माध्यम से चलाते हैं, तो वही पैक केवल CPU और NVIDIA Docker होस्ट पर काम करता है। सटीक रनटाइम के लिए कम से कम 4 GiB प्रभावी मेमोरी की आवश्यकता होती है: कॉन्फ़िगर कंटेनर cgroup सीमा, अन्यथा होस्ट मेमोरी। उस हस्ताक्षरित अनुकूलता न्यूनतम से नीचे की प्रणाली को डाउनलोड से पहले अस्वीकार कर दिया जाता है। यह आवश्यकता बिल्ट-इन फास्ट OCR पर लागू नहीं होती है। Bare-metal बिल्ड को अस्वीकार कर दिया गया है क्योंकि उनके libc और Python ABI का सुरक्षित रूप से अनुमान नहीं लगाया जा सकता है; जब होस्ट Tesseract और Ghostscript प्रदान करता है तो तेज़ OCR उपलब्ध रहता है।
+
+आर्किटेक्चर के आधार पर वैकल्पिक आर्टिफैक्ट लगभग 208-234 MiB संपीड़ित और 409-488 MiB निकाला गया है। हस्ताक्षरित सूचकांक इंस्टॉलर द्वारा लागू सटीक संपीड़ित और निकाले गए बाइट गिनती को बांधता है। अंतर्निहित Tesseract आधिकारिक छवि में लगभग 25 MiB जोड़ता है और `/data/ai` में किसी फ़ाइल की आवश्यकता नहीं है।
+
+ऑनलाइन इंस्टॉलेशन एक हस्ताक्षरित रिलीज़ इंडेक्स और वर्तमान प्लेटफ़ॉर्म के लिए सटीक सामग्री-संबोधित आर्टिफैक्ट लाता है। SnapOtter नई पीढ़ी को परमाणु रूप से सक्रिय करने से पहले Ed25519 इंडेक्स हस्ताक्षर, आर्टिफैक्ट आकार, SHA-256 डाइजेस्ट, मॉडल डाइजेस्ट, पथ, फ़ाइल मोड और चरणबद्ध smoke test को सत्यापित करता है। एक असफल इंस्टालेशन पूर्व स्वस्थ पीढ़ी को सक्रिय छोड़ देता है।
+
+एयर-गैप्ड इंस्टॉलेशन के लिए, `index` और `archive` नामक मल्टीपार्ट फ़ील्ड का उपयोग करके रिलीज़ के `ocr-runtime-index.json` और मिलान वाले OCR रनटाइम संग्रह को `POST /api/v1/admin/features/import` पर अपलोड करें। ऑफ़लाइन आयात ऑनलाइन इंस्टॉलेशन के समान ही हस्ताक्षर, हैश, निष्कर्षण, संगतता और धुआं-परीक्षण जांच लागू करता है; विश्वसनीय हस्ताक्षरित अनुक्रमणिका के बिना एक संग्रह अस्वीकार कर दिया जाता है।
 
 ---
 
@@ -143,16 +163,16 @@ Docker इमेज एप्लिकेशन के साथ-साथ स
 ## 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` | string | `"auto"` | भाषा: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko` |
-| `enhance` | boolean | `true` | OCR सटीकता सुधारने के लिए इमेज को पूर्व-संसाधित करें |
-| `engine` | string | - | अप्रचलित। `tesseract` को `fast`, `paddleocr` को `balanced` पर मैप करता है |
+| `enhance` | बूलियन | स्तर पर निर्भर | स्थानीय कंट्रास्ट में सुधार करें. फास्ट इसे सीधे लागू करता है; सटीक स्तर केवल तभी भिन्न होते हैं जब कैलिब्रेटेड स्कोरिंग OCR में सुधार करती है। सर्वश्रेष्ठ के लिए डिफ़ॉल्ट चालू |
+| `engine` | डोरी | - | अस्वीकृत अनुकूलता उपनाम. `tesseract` को `fast` और पुराने `paddleocr` मान को `balanced` में मैप करें; यह PaddlePaddle लोड नहीं करता है |
 
-बाउंडिंग बॉक्स, कॉन्फ़िडेंस स्कोर, और निकाले गए टेक्स्ट ब्लॉक के साथ संरचित परिणाम लौटाता है।
+निकाले गए पाठ और उद्गम मेटाडेटा को लौटाता है: इंजन, अनुरोधित और वास्तविक गुणवत्ता, उपकरण, प्रदाता, गिरावट की स्थिति, चेतावनियां, और लागू होने पर सटीक-रनटाइम/मॉडल संस्करण। स्पष्ट गुणवत्ता अनुरोध कभी भी दूसरे स्तर पर नहीं आते। यदि `balanced` या `best` अनुपलब्ध है, तो API चुपचाप `fast` चलाने के बजाय `FEATURE_NOT_INSTALLED` या `FEATURE_INCOMPATIBLE` लौटाता है।
 
 ## PDF OCR {#pdf-ocr}
 
@@ -163,9 +183,13 @@ AI-संचालित OCR का उपयोग करके स्कैन
 
 | पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण |
 |-----------|------|---------|-------------|
-| `quality` | `"fast"` \| `"balanced"` \| `"best"` | `"balanced"` | प्रसंस्करण स्तर |
+| `quality` | `"fast"` \| `"balanced"` \| `"best"` | गतिशील | जब `quality` और `engine` नहीं दिए जाते, SnapOtter इस क्रम में सर्वोत्तम उपलब्ध टियर चुनता है: `best`, `balanced`, `fast`। कोरियाई के लिए `fast` कभी नहीं चुना जाता; `best`, फिर `balanced` उपयोग होता है, अन्यथा सटीक रनटाइम का इंस्टॉलेशन या संगतता त्रुटि लौटती है। |
 | `language` | string | `"auto"` | भाषा: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko` |
 | `pages` | string | `"all"` | पृष्ठ चयन: `"all"`, `"1-3"`, `"1,3,5"` |
+| `enhance` | बूलियन | स्तर पर निर्भर | स्थानीय कंट्रास्ट में सुधार करें. फास्ट इसे सीधे लागू करता है; सटीक स्तर केवल तभी भिन्न होते हैं जब कैलिब्रेटेड स्कोरिंग OCR में सुधार करती है। सर्वश्रेष्ठ के लिए डिफ़ॉल्ट चालू |
+| `engine` | डोरी | - | अस्वीकृत अनुकूलता उपनाम. `tesseract` को `fast` और पुराने `paddleocr` मान को `balanced` में मैप करें; यह PaddlePaddle लोड नहीं करता है |
+
+वही नो-डाउनग्रेड नियम PDF OCR पर लागू होता है। PDF पृष्ठों को पहचान से पहले रैस्टराइज़ किया जाता है, और एक अनुरोध अधिकतम 50 पृष्ठों का चयन कर सकता है।
 
 ## फेस / PII ब्लर {#face-pii-blur}