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
2026-08-03 07:46:42 +02:00 · 2026-07-15 03:34:24 +08:00
parent 58121f205f
commit 991c981529
409 changed files with 67151 additions and 8076 deletions
@@ -1,8 +1,8 @@
 ---
 description: "Структура монорепозиторію, архітектура застосунків і пакетів, життєвий цикл запиту та споживання ресурсів SnapOtter."
-i18n_source_hash: 9e8f80499a37
-i18n_provenance: human
 i18n_output_hash: 6a1de194bb8b
+i18n_source_hash: 733cb3c10884
+i18n_provenance: human
 ---

 # Архітектура {#architecture}
@@ -36,13 +36,13 @@ snapotter/

 ### `@snapotter/ai` {#snapotter-ai}

-Проміжний шар, який викликає скрипти Python для ML-операцій. Під час першого використання цей шар запускає стійкий процес-диспетчер Python, який заздалегідь імпортує важкі бібліотеки (PIL, NumPy, MediaPipe, rembg), тож наступні AI-виклики пропускають накладні витрати на імпорт. Якщо диспетчер ще не готовий, шар повертається до породження свіжого підпроцесу Python на кожен запит.
+Рівень мосту, який викликає нативну та Python ML середовища виконання. Більшість інструментів Python використовують постійний dispatcher, який попередньо імпортує важкі бібліотеки (PIL, NumPy, MediaPipe, rembg), тому наступні виклики пропускають накладні витрати на імпорт. OCR ізольовано від цього змінного спільного середовища: `fast` викликає рідний Tesseract, тоді як `balanced` і `best` використовують виділений постійний JSONL dispatcher, закріплений на активному незмінному RapidOCR/ONNX покоління. Кожен запит містить generation lease. Активація спочатку запускає smoke test на кандидаті, а потім атомарно перемикається на його dispatcher. Попередній dispatcher зливається перед тим, як його генерацію буде зібрано сміттям.

 **Моделі не завантажуються заздалегідь.** Скрипт кожного інструмента завантажує ваги своєї моделі з диска під час запиту і відкидає їх після завершення запиту. Дивіться [Споживання ресурсів](#resource-footprint) для повного профілю пам'яті.

-Підтримувані операції: видалення фону (rembg/BiRefNet), збільшення роздільності (RealESRGAN), розмиття облич (MediaPipe), покращення облич (GFPGAN/CodeFormer), видалення об'єктів (LaMa ONNX), OCR (PaddleOCR/Tesseract), розфарбовування (DDColor), видалення шуму, видалення ефекту червоних очей, відновлення фото, генерація фото на паспорт, виправлення прозорості (BiRefNet HR-matting) та зміна розміру з урахуванням вмісту (двійковий файл Go caire).
+Підтримувані операції: видалення фону (rembg/BiRefNet), масштабування (RealESRGAN), розмиття обличчя (MediaPipe), покращення обличчя (GFPGAN/CodeFormer), стирання об’єктів (LaMa ONNX), OCR (Tesseract і RapidOCR з моделями PP-OCR ONNX), розфарбовування (DDColor), видалення шуму, видалення ефекту червоних очей, відновлення фотографій, створення фотографій на паспорт, фіксація прозорості (BiRefNet HR-matting) і зміна розміру з урахуванням вмісту (двійковий файл Go caire).

-Скрипти Python розташовані в `packages/ai/python/`. Образ Docker заздалегідь завантажує всі ваги моделей під час збірки, тож контейнер працює повністю офлайн.
+Сценарії Python знаходяться в `packages/ai/python/`. Великі додаткові пакети моделей встановлюються на вимогу в постійний том `/data/ai`. Точний OCR використовує підписані, специфічні для платформи артефакти; вбудований рівень Tesseract не вимагає завантаження пакета моделей.

 ### `@snapotter/shared` {#snapotter-shared}

@@ -87,7 +87,7 @@ snapotter/
 2. Фронтенд надсилає multipart POST на `/api/v1/tools/:section/:toolId` з файлом і налаштуваннями.
 3. Маршрут API валідує вхідні дані за допомогою Zod, а потім розподіляє обробку.
 4. Для стандартних інструментів завдання ставиться в чергу до відповідного пулу BullMQ (image, media або docs залежно від модальності). Воркер BullMQ у процесі автоматично орієнтує зображення на основі метаданих EXIF, виконує функцію обробки інструмента й повертає результат.
-5. Для AI-інструментів міст TypeScript надсилає запит до стійкого диспетчера Python (або породжує свіжий підпроцес як запасний варіант), чекає його завершення та зчитує вихідний файл.
+5. Для більшості інструментів ШІ міст TypeScript надсилає запит до постійного Python dispatcher. Натомість швидкий OCR викликає Tesseract, а точний OCR запускає закріплений виконуваний файл із активного незмінного покоління OCR. Запитуваний рівень OCR фіксується на вході та ніколи не мовчки змінюється під час виконання.
 6. Прогрес завдання зберігається в таблиці `jobs` у PostgreSQL, тож стан переживає перезапуски контейнера. Оновлення в реальному часі доставляються через SSE за адресою `/api/v1/jobs/:jobId/progress`.
 7. API повертає `jobId` та `downloadUrl`. Користувач завантажує оброблений файл з `/api/v1/download/:jobId/:filename`.

@@ -1,8 +1,8 @@
 ---
 description: "Розгорніть SnapOtter у продакшені за допомогою Docker. Вимоги до апаратного забезпечення, налаштування GPU та конфігурації зворотного проксі для Nginx, Traefik і Cloudflare."
-i18n_source_hash: 6b6957060fa6
-i18n_provenance: machine
-i18n_output_hash: 823840401d54
+i18n_output_hash: 4d221e5eaf97
+i18n_source_hash: e0d8d5f6fc87
+i18n_provenance: human
 ---

 # Розгортання {#deployment}
@@ -11,6 +11,12 @@ SnapOtter розгортається як стек Docker Compose із 3 кон

 Див. [Docker Image](./docker-tags) щодо налаштування GPU, прикладів Docker Compose і фіксації версій.

+
+<!-- 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 -->
 ## Швидкий старт (CPU) {#quick-start-cpu}

 ```yaml
@@ -113,7 +119,7 @@ docker compose up -d

 ## Швидкий старт (NVIDIA CUDA) {#quick-start-nvidia-cuda}

-Для прискорення через NVIDIA CUDA на AI-інструментах (видалення фону, збільшення роздільності, покращення облич, OCR):
+Для прискорення NVIDIA CUDA у підтримуваних інструментах ШІ (видалення фону, масштабування, покращення обличчя):

 ```yaml
 # docker-compose-gpu.yml - Requires: NVIDIA GPU + nvidia-container-toolkit
@@ -251,10 +257,10 @@ deploy:
 |---|---|
 | CPU | 4 ядра |
 | RAM | 4 GB |
-| Диск | 3 GB (образ) + 24 GB (моделі AI) + робочий простір |
+| Disk | 3 ГБ (зображення) + близько 20 ГБ (усі додаткові пакети AI) + робочий простір |
 | GPU | Не потрібен (резервний варіант на CPU) |

-**Саме встановлення AI-бандлів піднімає RAM до 4 GB.** Без встановленого AI застосунок у стані спокою займає близько 360 MB; з усіма сімома встановленими бандлами він тримає ~2.6 GB резидентно, оскільки Python AI-сайдкар попередньо завантажує свої моделі (видалення фону, збільшення роздільності, OCR, транскрипція, виявлення облич, реставрація) під час запуску. Не-AI встановлення залишаються легкими; AI-встановлення потребують ≥4 GB.
+**Встановлення та запуск більших пакетів штучного інтелекту – це те, що підштовхує рекомендацію до 4 ГБ RAM.** Без встановлення додаткових пакетів програма простоює близько 360 МБ. Застарілі інструменти Python використовують sidecar, тоді як точний OCR використовує виділений довготривалий dispatcher, закріплений на активному незмінному поколінні. Перед активацією інсталятор запускає smoke test на кандидаті. Потім він автоматично перемикається на новий dispatcher і зливає попередній dispatcher перед garbage collection. Кожен офіційний артефакт точного OCR повинен передати свій найгірший release suite всередині 4 GiB cgroup, тоді як рекомендація хосту 4 ГБ залишає запас для програми Node.js, Postgres, Redis, черг і одночасної роботи.

 Більшість AI-інструментів цілком придатні до використання на CPU; парі з них справді потрібен GPU. Виміряно на сучасному 4-ядерному CPU:

@@ -271,7 +277,7 @@ SnapOtter навмисно не запікає ці завантаження м

 Деякі інструменти залежать від більш ніж одного спільного бандла. Наприклад, Passport Photo потребує і `background-removal`, і `face-detection`; якщо `background-removal` вже встановлено, увімкнення Passport Photo завантажує лише відсутній бандл `face-detection`. Те саме повторне використання застосовується до всіх AI-інструментів.

-Розміри завантажень моделей AI:
+Приблизний обсяг пам’яті додаткового набору AI:

 | Бандл | Розмір на диску |
 |---|---|
@@ -279,9 +285,16 @@ SnapOtter навмисно не запікає ці завантаження м
 | Upscale + Покращення облич + Видалення шуму | 5-6 GB |
 | Виявлення облич | 200-300 MB |
 | Стирання об'єктів + Colorize | 1-2 GB |
-| OCR | 5-6 GB |
+| Точний OCR (`balanced`/`best`) | ~208-234 MiB завантажити / ~409-488 MiB встановити |
 | Реставрація фото | 4-5 GB |
-| **Усі бандли** | **~24 GB** |
+| Транскрипція | ~600 МБ |
+| **Усі набори** | **~20 ГБ встановлено** |
+
+Швидкий OCR вбудовано в образ за допомогою Tesseract, додає близько 25 MiB і не потребує додаткового пакета OCR або його вимог до пам’яті 4 GiB. Точна упаковка є в офіційному Linux  amd64 і arm64 контейнери та прогони ONNX Runtime на CPU. Хости NVIDIA використовують те саме середовище виконання CPU OCR, тому OCR не залежить від версії CUDA або архітектури GPU. Точний час виконання вимагає принаймні 4 GiB ефективної пам’яті: обмеження налаштованого контейнера cgroup, інакше пам’ять хоста. SnapOtter відхиляє системи, нижче встановленого мінімуму сумісності перед завантаженням пакета. Встановлення точного пакета також відхиляється для bare-metal/попередньо зібраних архівів, чиї libc і Python ABI не можуть бути гарантовані.
+
+Репліки, що спільно використовують той самий `DATA_DIR`, мають працювати на однаковій архітектурі ЦП; закріплюйте розгортання з кількома репліками за сумісними вузлами за допомогою спорідненості вузлів (node affinity). Для змішаних реплік amd64/arm64 потрібні окремі томи даних і незалежні розгортання SnapOtter.
+
+Точний час виконання зберігає одне активне покоління та очищає його кеш завантажень після активації. Для цього випуску перша інсталяція тимчасово потребує приблизно 620-720 MiB для архіву та постановки, а оновлення може досягти піку близько 1,2 GiB, поки старе покоління залишається активним. Програма інсталяції обчислює точні вимоги з підписаного індексу та поточних поколінь перед завантаженням або витягуванням і зазнає помилки раніше, якщо обсяг даних замалий.

 ```yaml
 deploy:
@@ -353,7 +366,6 @@ SnapOtter підтримує **55+ вхідних форматів** і **14 в

 - **Зміна розміру з урахуванням вмісту** аварійно завершується на великих зображеннях (>5 MP) через обмеження в бінарному файлі caire. Добре працює з меншими зображеннями.
 - **Декодування HEIF** займає 13-23 секунди. HEIC (варіант Apple) значно швидший — 0.3-0.9 секунди.
- **OCR для японської** дає збій на CPU через баг MKLDNN у PaddlePaddle. Працює на GPU.
 - **Upscale** дає таймаут на CPU для всього, крім малих зображень. Для практичного використання потрібен GPU.
 - **CodeFormer** для покращення облич значно повільніший за GFPGAN (53с проти 2с на GPU). GFPGAN рекомендовано для більшості сценаріїв.

@@ -434,6 +446,26 @@ securityContext:
 | `SESSION_DURATION_HOURS` | `168` | Тривалість сеансу входу (7 днів) |
 | `CORS_ORIGIN` | (порожньо) | Дозволені джерела через кому, або порожньо для того самого джерела |

+### Вихідний проксі та приватний CA {#outbound-proxy-and-private-ca}
+
+Офіційний контейнер забезпечує підтримку проксі середовища Node. Якщо SnapOtter має отримати доступ до сховища часу виконання OCR або інших служб HTTPS через корпоративний проксі, установіть `HTTPS_PROXY` (і `HTTP_PROXY`, якщо потрібно). Встановіть для `NO_PROXY` розділений комами список хостів, до яких потрібно отримати прямий доступ, наприклад Postgres, Redis і внутрішнє сховище об’єктів.
+
+Якщо проксі-сервер або внутрішня служба підписана приватним центром сертифікації, підключіть сертифікат ЦС лише для читання та вкажіть на нього `NODE_EXTRA_CA_CERTS`. Файл повинен існувати на момент запуску процесу Node:
+
+```yaml
+services:
+  app:
+    environment:
+      HTTPS_PROXY: http://proxy.example.internal:3128
+      HTTP_PROXY: http://proxy.example.internal:3128
+      NO_PROXY: postgres,redis,minio,localhost,127.0.0.1
+      NODE_EXTRA_CA_CERTS: /etc/snapotter/custom-ca.pem
+    volumes:
+      - ./company-ca.pem:/etc/snapotter/custom-ca.pem:ro
+```
+
+Зберігайте облікові дані проксі за межами файлу Compose (наприклад, у захищеному файлі `.env` або секреті). Не вимикайте перевірку TLS: підписаний індекс OCR автентифікує метадані випуску, тоді як звичайна перевірка TLS все ще захищає транспорт і всі вихідні запити.
+
 ## Перевірка стану {#health-check}

 Контейнер містить вбудовану перевірку стану:
@@ -1,8 +1,8 @@
 ---
 description: "Теги Docker-образу SnapOtter, тести продуктивності GPU, закріплення версій і мультиплатформна підтримка для AMD64 та ARM64."
-i18n_source_hash: 148b3608e11a
-i18n_provenance: human
 i18n_output_hash: 8d481651c9cb
+i18n_source_hash: fda322e78b4b
+i18n_provenance: human
 ---

 # Docker-образ {#docker-image}
@@ -41,7 +41,6 @@ docker run -d --name SnapOtter --gpus all -p 1349:1349 -v SnapOtter-data:/data s
 | Видалення фону (isnet) | 2457 мс | 1137 мс | 2.2x |
 | Збільшення 2x | 350 мс | 309 мс | 1.1x |
 | Збільшення 4x | 910 мс | 310 мс | 2.9x |
-| OCR (PaddleOCR) | 137 мс | 94 мс | 1.5x |
 | Розмиття облич | 139 мс | 122 мс | 1.1x |

 #### Холодний старт (перший запит після запуску контейнера) {#cold-start-first-request-after-container-start}
@@ -50,7 +49,8 @@ docker run -d --name SnapOtter --gpus all -p 1349:1349 -v SnapOtter-data:/data s
 |------|-----|-----|---------|
 | Видалення фону | 22286 мс | 4792 мс | 4.7x |
 | Збільшення 2x | 3957 мс | 2318 мс | 1.7x |
-| OCR (PaddleOCR) | 1469 мс | 1090 мс | 1.3x |
+
+OCR не входить до порівняння CUDA. Як вбудований рівень Tesseract, так і додаткові рівні RapidOCR/ONNX використовують CPU, у тому числі коли контейнер має доступ NVIDIA GPU.

 ### Перевірка стану CUDA {#cuda-health-check}

@@ -1,8 +1,8 @@
 ---
 description: "Встановіть SnapOtter за допомогою Docker однією командою. Включає налаштування Docker Compose, збирання з вихідного коду й повний огляд функцій."
-i18n_source_hash: 4536d4558b8e
-i18n_provenance: machine
 i18n_output_hash: a97c15d102b5
+i18n_source_hash: 24724b5595b2
+i18n_provenance: human
 ---

 # Початок роботи {#getting-started}
@@ -32,7 +32,7 @@ SnapOtter містить анонімну продуктову аналітик
 :::

 ::: tip Прискорення NVIDIA CUDA
-Додайте `--gpus all` для прискорених через NVIDIA CUDA видалення фону, збільшення роздільності, OCR, покращення облич і реставрації:
+Додайте `--gpus all` для NVIDIA CUDA-прискореного видалення фону, масштабування, покращення обличчя та відновлення. OCR залишається на основі ЦП і працює в одному образі з доступом до GPU або без нього:

 ```bash
 docker run -d --name SnapOtter -p 1349:1349 --gpus all -v SnapOtter-data:/data snapotter/snapotter:latest