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,18 +1,26 @@
 ---
 description: "Справочник по AI-движку со всеми локальными ML-инструментами. Удаление фона, апскейлинг, OCR, распознавание лиц, реставрация фотографий и другое."
-i18n_source_hash: 14728c1dcd05
-i18n_provenance: machine
-i18n_output_hash: 362d36a75c8d
+i18n_output_hash: 964be813bc52
+i18n_source_hash: aa9a56cdddc7
+i18n_provenance: human
 ---

 # Справочник по AI-движку {#ai-engine-reference}

-Пакет `@snapotter/ai` связывает Node.js с **постоянным Python-сайдкаром** для всех ML-операций. Процесс диспетчера остаётся активным между запросами, обеспечивая быстрый тёплый старт. NVIDIA CUDA автоматически определяется при запуске и используется, если доступна; иначе AI-инструменты работают на 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 сегодня не поддерживается для AI-инференса. Проброс `/dev/dri` в контейнер не ускоряет эти инструменты Python-сайдкара, если не доступна NVIDIA GPU с поддержкой CUDA.

 19 AI-инструментов Python-сайдкара в четырёх модальностях (изображение, аудио, видео, документ) плюс 2 инструмента с опциональными AI-возможностями. Все модели работают локально: после первоначальной загрузки моделей интернет не требуется.

+
+<!-- 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-инструменту требуется один или несколько пакетов возможностей, прежде чем он сможет работать. Админ-интерфейс устанавливает пакеты по инструменту через `POST /api/v1/admin/tools/:toolId/features/install`, который определяет полный список пакетов, пропускает уже установленные и ставит в очередь только недостающие загрузки. Например, включение «Фото на паспорт» на новом экземпляре ставит в очередь `background-removal` и `face-detection`; включение того же инструмента после того, как уже установлено «Удаление фона», ставит в очередь только `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 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 | 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 MB | модели преобразования речи в текст faster-whisper | transcribe-audio, auto-subtitles |

 Инструменты с межпакетными зависимостями:
@@ -71,7 +81,17 @@ Docker-образ поставляется вместе с приложение
 | `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 через `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 страниц.

 ## Размытие лиц / персональных данных {#face-pii-blur}

@@ -1,8 +1,8 @@
 ---
 description: "Полный справочник REST API. Эндпоинты инструментов, пакетная обработка, конвейеры, файловая библиотека, аутентификация, команды и административные операции."
-i18n_source_hash: 8646977f7cc9
-i18n_provenance: machine
 i18n_output_hash: b2ec4e36cb9f
+i18n_source_hash: b89b5df16af5
+i18n_provenance: human
 ---

 # Справочник REST API {#rest-api-reference}
@@ -178,7 +178,7 @@ curl -X POST http://localhost:1349/api/v1/tools/<section>/<toolId>/batch \
 | `remove-background` | Удаление фона | rembg (BiRefNet / U2-Net) | `model`, `backgroundType` (transparent/color/gradient/blur/image), `backgroundColor`, `gradientColor1`, `gradientColor2`, `gradientAngle`, `blurEnabled`, `blurIntensity`, `shadowEnabled`, `shadowOpacity` |
 | `upscale` | Апскейл изображения | RealESRGAN | `scale` (2/4), `model`, `faceEnhance`, `denoise`, `format`, `quality` |
 | `erase-object` | Ластик объектов | LaMa (ONNX) | Маска отправляется как вторая файловая часть (fieldname `mask`), `format`, `quality` |
-| `ocr` | OCR / Извлечение текста | PaddleOCR / Tesseract | `quality` (fast/balanced/best), `language`, `enhance` |
+| `ocr` | OCR / Извлечение текста | Tesseract (быстрый); RapidOCR + PP-OCR ONNX (сбалансированный/лучший) | `quality` (быстрый/сбалансированный/лучший), `language`, `enhance` |
 | `blur-faces` | Размытие лиц / PII | MediaPipe | `blurRadius`, `sensitivity` |
 | `smart-crop` | Умная обрезка | MediaPipe + Sharp | `mode` (subject/face/trim), `strategy` (attention/entropy), `width`, `height`, `padding`, `facePreset` (closeup/head-shoulders/upper-body/half-body), `sensitivity`, `threshold`, `padToSquare`, `padColor`, `targetSize`, `quality` |
 | `image-enhancement` | Улучшение изображения | На основе анализа | `mode` (auto/exposure/contrast/color/sharpness), `strength` |
@@ -425,7 +425,9 @@ curl -X POST http://localhost:1349/api/v1/tools/image/html-to-image \

 ## Пакетная обработка {#batch-processing}

-Применение общего инструмента с поддержкой пакетной обработки к нескольким файлам сразу. Возвращает ZIP-архив. Пользовательские многофайловые или многошаговые маршруты, такие как подписание PDF, PDF OCR и маршруты пресетов PDF-в-изображение, используют собственный контракт эндпоинта вместо общего маршрута `/batch`.
+Применение общего инструмента с поддержкой пакетной обработки к нескольким файлам сразу. Возвращает ZIP-архив. Пользовательские многофайловые или многошаговые маршруты, такие как подписание PDF и маршруты пресетов PDF-в-изображение, используют собственный контракт эндпоинта вместо общего маршрута `/batch`.
+
+Инструмент `ocr-pdf` поддерживает этот общий маршрут `/batch`.

 ```bash
 curl -X POST http://localhost:1349/api/v1/tools/image/compress/batch \
@@ -594,6 +596,8 @@ data: {"jobId":"...","type":"batch","status":"processing","completedFiles":2,"to

 Управление бандлами AI-функций (установка/удаление пакетов AI-моделей в среде Docker). Предпочтительнее использовать эндпоинт установки на уровне инструмента при включении инструмента из пользовательской автоматизации: некоторым AI-инструментам нужно более одного общего бандла, и этот эндпоинт пропускает уже установленные бандлы, ставя в очередь только недостающие.

+OCR — это необязательное расширение, а не жесткая зависимость. Его уровень `fast` Tesseract работает без пакета; `POST /api/v1/admin/features/ocr/install` устанавливает подписанный пакет RapidOCR для `balanced` и `best` на Linux amd64 или arm64. Точная среда выполнения OCR использует CPU на хостах только с ЦП и NVIDIA и требует не менее 4 GiB эффективной памяти (настроенный предел cgroup контейнера, в противном случае память хоста). SnapOtter сообщает о `requiredMemoryBytes`, `effectiveMemoryBytes` и причине совместимости `insufficient-memory` и отклоняет несовместимую установку перед загрузкой. Это требование к памяти не применяется к `fast`. Пакет составляет около 208-234 MiB для загрузки и 409-488 MiB для установки, в зависимости от цели; подписанный индекс связывает точные размеры, применяемые во время установки.
+
 | Метод | Путь | Доступ | Описание |
 |--------|------|--------|-------------|
 | `GET` | `/api/v1/features` | Auth | Список всех бандлов функций и их статуса установки |
@@ -601,7 +605,18 @@ data: {"jobId":"...","type":"batch","status":"processing","completedFiles":2,"to
 | `POST` | `/api/v1/admin/tools/:toolId/features/install` | Admin (`features:manage`) | Установить каждый бандл, который требуется инструменту; возвращает статус queued/skipped по каждому бандлу |
 | `POST` | `/api/v1/admin/features/:bundleId/uninstall` | Admin (`features:manage`) | Удалить бандл функции и очистить файлы моделей |
 | `GET` | `/api/v1/admin/features/disk-usage` | Admin (`features:manage`) | Получить общее использование диска AI-моделями |
-| `POST` | `/api/v1/admin/features/import` | Admin (`features:manage`) | Импортировать офлайн-архив AI-бандла |
+| `POST` | `/api/v1/admin/features/import` | Администратор (`features:manage`) | Импортируйте устаревший пакет AI (`file`) или подписанный оффлайн OCR выпускать (`index` плюс `archive`) |
+
+Импорт OCR с воздушным зазором должен включать подписанный `ocr-runtime-index.json` выпуска и соответствующий архив платформы. SnapOtter применяет ту же подпись Ed25519, хэш артефакта, совместимость, извлечение и дымовые тесты, которые используются при онлайн-установке:
+
+```bash
+curl -X POST http://localhost:1349/api/v1/admin/features/import \
+  -H "Authorization: Bearer <admin-token>" \
+  -F "index=@ocr-runtime-index.json" \
+  -F "archive=@ocr-linux-amd64-cpu-py312.tar.gz"
+```
+
+Используйте архив `linux-arm64-cpu-py311` на arm64. Подписанный артефакт для другой цели скорее отклоняется, чем устанавливается.

 ## Административные операции {#admin-operations}