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

@@ -1,18 +1,26 @@
 ---
 description: "Довідник рушія ШІ з усіма локальними інструментами ML. Видалення фону, збільшення роздільної здатності, OCR, розпізнавання облич, реставрація фото та інше."
-i18n_source_hash: 14728c1dcd05
-i18n_provenance: machine
-i18n_output_hash: e36cdc2779d7
+i18n_output_hash: 3a80b8a66b82
+i18n_source_hash: aa9a56cdddc7
+i18n_provenance: human
 ---
 
 # Довідник рушія ШІ {#ai-engine-reference}
 
-Пакет `@snapotter/ai` з'єднує Node.js із **постійним допоміжним процесом Python** для всіх операцій ML. Процес диспетчера залишається активним між запитами задля швидкого «теплого» старту. NVIDIA CUDA автоматично визначається під час запуску та використовується за наявності; в іншому разі інструменти ШІ працюють на CPU.
+Пакет `@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 і підключення драйверів для цього інструменту.
 
 Прискорення на iGPU Intel/AMD через VA-API, Quick Sync або OpenCL наразі не підтримується для інференсу ШІ. Прокидання `/dev/dri` в контейнер не прискорює ці інструменти допоміжного процесу Python, якщо немає NVIDIA GPU з підтримкою CUDA.
 
 19 інструментів ШІ на допоміжному процесі Python у чотирьох модальностях (зображення, аудіо, відео, документ), а також 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 @@ Node.js Tool Route
 
 Docker-образ постачає застосунок разом зі спільним середовищем виконання. Великі архіви моделей завантажуються за потреби в постійний том `/data/ai`, а далі повторно використовуються кожним інструментом, якому вони потрібні. Якщо набір уже встановлено, бо його потребував інший інструмент, увімкнення нового залежного інструмента не завантажує цей набір повторно.
 
-Кожен інструмент ШІ вимагає одного чи кількох наборів функцій, перш ніж зможе працювати. Адмін-інтерфейс встановлює за інструментом через `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`, який розкриває повний список пакетів, пропускає пакети, які вже встановлено, і ставить у чергу лише відсутні завантаження. Наприклад, увімкнення Passport Photo у нових чергах екземплярів `background-removal` і `face-detection`; увімкнення після того, як видалення фону вже встановлено, черги лише `face-detection`. OCR є винятком, оскільки `fast` не потребує пакета; інсталюйте необов’язкове точне середовище виконання через інтерфейс користувача або `POST /api/v1/admin/features/ocr/install`.
 
 | Набір | Розмір | Група спільних залежностей | Інструменти, що його використовують |
 |--------|------|-------------------------|-------------------|
@@ -61,7 +71,7 @@ Docker-образ постачає застосунок разом зі спіл
 | `object-eraser-colorize` | 1-2 ГБ | inpainting/outpainting LaMa та DDColor | erase-object, colorize, ai-canvas-expand |
 | `upscale-enhance` | 5-6 ГБ | RealESRGAN, GFPGAN / CodeFormer, шумозаглушення | upscale, enhance-faces, noise-removal |
 | `photo-restoration` | 4-5 ГБ | конвеєр ремонту подряпин і реставрації | restore-photo |
-| `ocr` | 5-6 ГБ | стек OCR 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 МБ | моделі мовлення в текст 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 через `CPUExecutionProvider` ONNX Runtime, тому той самий пакет працює лише на центральному процесорі та хостах 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 @@ 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` | логічний | Залежно від рівня | Поліпшення локального контрасту. Fast застосовує його безпосередньо; точні рівні зберігають варіант лише тоді, коли калібрована оцінка покращує OCR. За замовчуванням для найкращого |
+| `engine` | рядок | - | Застарілий псевдонім сумісності. Зіставляє `tesseract` на `fast` і застаріле значення `paddleocr` на `balanced`; він не завантажує PaddlePaddle |
 
-Повертає структуровані результати з обмежувальними рамками, оцінками впевненості та витягнутими блоками тексту.
+Повертає витягнутий текст, а також метадані про походження: механізм, запитану та фактичну якість, пристрій, постачальника, стан деградації, попередження та точні версії часу виконання/моделі, якщо це можливо. Явні запити щодо якості ніколи не повертаються до іншого рівня. Якщо `balanced` або `best` недоступні, API повертає `FEATURE_NOT_INSTALLED` або `FEATURE_INCOMPATIBLE` замість тихого запуску `fast`.
 
 ## OCR для PDF {#pdf-ocr}
 
@@ -163,9 +183,13 @@ Docker-образ постачає застосунок разом зі спіл
 
 | Параметр | Тип | За замовчуванням | Опис |
 |-----------|------|---------|-------------|
-| `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` | логічний | Залежно від рівня | Поліпшення локального контрасту. Fast застосовує його безпосередньо; точні рівні зберігають варіант лише тоді, коли калібрована оцінка покращує OCR. За замовчуванням для найкращого |
+| `engine` | рядок | - | Застарілий псевдонім сумісності. Зіставляє `tesseract` на `fast` і застаріле значення `paddleocr` на `balanced`; він не завантажує PaddlePaddle |
+
+Таке ж правило заборони на пониження версії застосовується до PDF OCR. Сторінки PDF растеризуються перед розпізнаванням, і один запит може вибрати не більше 50 сторінок.
 
 ## Розмиття облич / PII {#face-pii-blur}