`@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 टूल। सभी मॉडल लोकल रूप से चलते हैं; प्रारंभिक मॉडल डाउनलोड के बाद इंटरनेट की आवश्यकता नहीं।
तेज़ 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` के साथ अस्वीकार किया जाता है।
एक अलग "docs" डिस्पैचर प्रोफ़ाइल AI अनुमति सूची को दस्तावेज़-प्रसंस्करण स्क्रिप्ट (`doc_pagecount`, `doc_health`, `doc_flatten`, `doc_redact`, `doc_text`, `doc_to_word`, `doc_metadata`, `doc_html_pdf`) से बदल देती है और भारी ML आयातों को छोड़ देती है।
**टाइमआउट:** 300 s डिफ़ॉल्ट; OCR और BiRefNet बैकग्राउंड हटाने को 600 s मिलते हैं।
## फ़ीचर बंडल {#feature-bundles}
AI मॉडल साझा डिपेंडेंसी स्टैक द्वारा पैकेज किए जाते हैं, प्रति टूल एक आर्काइव नहीं। एक फ़ीचर बंडल कई टूल को सक्षम कर सकता है जब वे एक ही मॉडल परिवार, Python wheels, या नेटिव लाइब्रेरी का उपयोग करते हैं। इससे रिलीज़ Docker इमेज छोटी रहती है और एक ही बैकग्राउंड मैटिंग, फेस डिटेक्शन, OCR, रिस्टोरेशन, और स्पीच मॉडल की डुप्लिकेट प्रतियाँ संग्रहीत करने से बचा जाता है।
Docker इमेज एप्लिकेशन के साथ-साथ सामान्य रनटाइम भेजती है। बड़े मॉडल आर्काइव माँग पर स्थायी `/data/ai` वॉल्यूम में डाउनलोड किए जाते हैं, फिर हर उस टूल द्वारा पुनः उपयोग किए जाते हैं जिसे उनकी आवश्यकता होती है। यदि कोई बंडल पहले से इंस्टॉल है क्योंकि किसी अन्य टूल को उसकी आवश्यकता थी, तो एक नया आश्रित टूल सक्षम करना उस बंडल को दोबारा डाउनलोड नहीं करता।
अधिकांश एआई टूल को चलने से पहले एक या अधिक फीचर बंडलों की आवश्यकता होती है। व्यवस्थापक यूआई उन्हें `POST /api/v1/admin/tools/:toolId/features/install` के माध्यम से टूल द्वारा इंस्टॉल करता है, जो पूर्ण बंडल सूची को हल करता है, पहले से इंस्टॉल किए गए बंडलों को छोड़ देता है, और केवल लापता डाउनलोड को कतार में रखता है। उदाहरण के लिए, पासपोर्ट फोटो को ताजा इंस्टेंस कतारों `background-removal` और `face-detection` पर सक्षम करना; बैकग्राउंड रिमूवल के बाद इसे सक्षम करने से केवल `face-detection` कतारें पहले से ही स्थापित हैं। OCR अपवाद है क्योंकि `fast` को किसी पैक की आवश्यकता नहीं है; UI या `POST /api/v1/admin/features/ocr/install` के माध्यम से इसका वैकल्पिक सटीक रनटाइम स्थापित करें।
| `passport-photo` | `background-removal`, `face-detection` | बैकग्राउंड हटाता है, फिर पासपोर्ट और ID फोटो नियमों के अनुसार क्रॉप को फ्रेम करने के लिए फेस लैंडमार्क का उपयोग करता है। |
| `enhance-faces` | `upscale-enhance`, `face-detection` | चयनित फेस क्षेत्रों पर GFPGAN या CodeFormer एन्हांसमेंट चलाने से पहले फेस का पता लगाता है। |
एक उपकरण तभी उपलब्ध होता है जब OCR को छोड़कर उसके सभी आवश्यक बंडल इंस्टॉल हो जाते हैं: इसका अंतर्निहित `fast` टियर वैकल्पिक OCR पैक के बिना उपलब्ध रहता है। आंशिक इंस्टॉल मान्य हैं और इन्हें क्रमिक रूप से प्रबंधित किया जाता है: इंस्टॉल किए गए बंडलों का पुन: उपयोग किया जाता है, लापता बंडलों को डाउनलोड के रूप में दिखाया जाता है, और कतारबद्ध इंस्टॉल एक समय में एक चलते हैं इसलिए साझा Python वातावरण को समवर्ती रूप से संशोधित नहीं किया जाता है।
सटीक 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` पर अपलोड करें। ऑफ़लाइन आयात ऑनलाइन इंस्टॉलेशन के समान ही हस्ताक्षर, हैश, निष्कर्षण, संगतता और धुआं-परीक्षण जांच लागू करता है; विश्वसनीय हस्ताक्षरित अनुक्रमणिका के बिना एक संग्रह अस्वीकार कर दिया जाता है।
| `quality` | `"fast"` \| `"balanced"` \| `"best"` | गतिशील | जब `quality` और `engine` नहीं दिए जाते, SnapOtter इस क्रम में सर्वोत्तम उपलब्ध टियर चुनता है: `best`, `balanced`, `fast`। कोरियाई के लिए `fast` कभी नहीं चुना जाता; `best`, फिर `balanced` उपयोग होता है, अन्यथा सटीक रनटाइम का इंस्टॉलेशन या संगतता त्रुटि लौटती है। |
| `enhance` | बूलियन | स्तर पर निर्भर | स्थानीय कंट्रास्ट में सुधार करें. फास्ट इसे सीधे लागू करता है; सटीक स्तर केवल तभी भिन्न होते हैं जब कैलिब्रेटेड स्कोरिंग OCR में सुधार करती है। सर्वश्रेष्ठ के लिए डिफ़ॉल्ट चालू |
| `engine` | डोरी | - | अस्वीकृत अनुकूलता उपनाम. `tesseract` को `fast` और पुराने `paddleocr` मान को `balanced` में मैप करें; यह PaddlePaddle लोड नहीं करता है |
निकाले गए पाठ और उद्गम मेटाडेटा को लौटाता है: इंजन, अनुरोधित और वास्तविक गुणवत्ता, उपकरण, प्रदाता, गिरावट की स्थिति, चेतावनियां, और लागू होने पर सटीक-रनटाइम/मॉडल संस्करण। स्पष्ट गुणवत्ता अनुरोध कभी भी दूसरे स्तर पर नहीं आते। यदि `balanced` या `best` अनुपलब्ध है, तो API चुपचाप `fast` चलाने के बजाय `FEATURE_NOT_INSTALLED` या `FEATURE_INCOMPATIBLE` लौटाता है।
| `quality` | `"fast"` \| `"balanced"` \| `"best"` | गतिशील | जब `quality` और `engine` नहीं दिए जाते, SnapOtter इस क्रम में सर्वोत्तम उपलब्ध टियर चुनता है: `best`, `balanced`, `fast`। कोरियाई के लिए `fast` कभी नहीं चुना जाता; `best`, फिर `balanced` उपयोग होता है, अन्यथा सटीक रनटाइम का इंस्टॉलेशन या संगतता त्रुटि लौटती है। |
| `enhance` | बूलियन | स्तर पर निर्भर | स्थानीय कंट्रास्ट में सुधार करें. फास्ट इसे सीधे लागू करता है; सटीक स्तर केवल तभी भिन्न होते हैं जब कैलिब्रेटेड स्कोरिंग OCR में सुधार करती है। सर्वश्रेष्ठ के लिए डिफ़ॉल्ट चालू |
| `engine` | डोरी | - | अस्वीकृत अनुकूलता उपनाम. `tesseract` को `fast` और पुराने `paddleocr` मान को `balanced` में मैप करें; यह PaddlePaddle लोड नहीं करता है |
वही नो-डाउनग्रेड नियम PDF OCR पर लागू होता है। PDF पृष्ठों को पहचान से पहले रैस्टराइज़ किया जाता है, और एक अनुरोध अधिकतम 50 पृष्ठों का चयन कर सकता है।
मास्क को एक **दूसरे फ़ाइल भाग** (fieldname `mask`) के रूप में भेजा जाता है, base64 के रूप में नहीं। मास्क में सफेद पिक्सेल मिटाने वाले क्षेत्रों को इंगित करते हैं। `format` और `quality` सेटिंग्स शीर्ष-स्तरीय फ़ॉर्म फ़ील्ड के रूप में भेजी जाती हैं।
"नकली पारदर्शी" PNG को ठीक करता है जहाँ बैकग्राउंड हटा दिया गया था लेकिन फ्रिंजिंग, हेलो, या अर्ध-पारदर्शी आर्टिफैक्ट पीछे छूट गए। साफ अल्फा चैनल उत्पन्न करने के लिए BiRefNet के उच्च-रिज़ॉल्यूशन मैटिंग मॉडल का उपयोग करता है, फिर किनारों के साथ रंग संदूषण हटाने के लिए कॉन्फ़िगर करने योग्य डिफ्रिंज प्रसंस्करण लागू करता है।
**OOM फ़ॉलबैक शृंखला:** यदि BiRefNet HR-मैटिंग उपलब्ध मेमोरी से अधिक हो जाती है, तो टूल स्वतः `birefnet-general` पर, फिर `u2net` पर फ़ॉलबैक करता है।
| पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण |
|-----------|------|---------|-------------|
| `defringe` | number (0-100) | `30` | रंग संदूषण हटाने के लिए एज डिफ्रिंज शक्ति |
## वैकल्पिक AI क्षमताओं वाले टूल {#tools-with-optional-ai-capabilities}
निम्नलिखित टूल Python साइडकार टूल नहीं हैं लेकिन कुछ विकल्प सक्षम होने पर AI फ़ीचर का उपयोग करते हैं।
### इमेज एन्हांसमेंट {#image-enhancement}
**टूल रूट:**`image-enhancement`
**इंजन:** विश्लेषण-आधारित (Sharp हिस्टोग्राम और सांख्यिकी)
इमेज का विश्लेषण करता है और एक्सपोज़र, कंट्रास्ट, व्हाइट बैलेंस, सैचुरेशन, शार्पनेस, और नॉइज़ के लिए स्वचालित सुधार लागू करता है। दृश्य-विशिष्ट मोड का समर्थन करता है।
| पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण |
|-----------|------|---------|-------------|
| `mode` | `"auto"` \| `"portrait"` \| `"landscape"` \| `"low-light"` \| `"food"` \| `"document"` | `"auto"` | सुधारों को ट्यून करने के लिए दृश्य मोड |
| `intensity` | number (0-100) | `50` | कुल सुधार शक्ति |
| `corrections.exposure` | boolean | `true` | एक्सपोज़र सुधार लागू करें |
| `corrections.contrast` | boolean | `true` | कंट्रास्ट सुधार लागू करें |
| `corrections.whiteBalance` | boolean | `true` | व्हाइट बैलेंस सुधार लागू करें |
| `corrections.saturation` | boolean | `true` | सैचुरेशन सुधार लागू करें |
| `corrections.sharpness` | boolean | `true` | शार्पनेस सुधार लागू करें |
