description:"Справочник по AI-движку со всеми локальными ML-инструментами. Удаление фона, апскейлинг, OCR, распознавание лиц, реставрация фотографий и другое."
Пакет `@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-возможностями. Все модели работают локально: после первоначальной загрузки моделей интернет не требуется.
Быстрый 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 с по умолчанию; для OCR и удаления фона BiRefNet отводится 600 с.
## Пакеты возможностей {#feature-bundles}
AI-модели упакованы по общему стеку зависимостей, а не по одному архиву на инструмент. Один пакет возможностей может включать несколько инструментов, если они используют одно семейство моделей, одни Python-колёса (wheels) или одни нативные библиотеки. Это позволяет держать релизный Docker-образ меньше и избегать хранения дубликатов одних и тех же моделей матирования фона, распознавания лиц, OCR, реставрации и речи.
Docker-образ поставляется вместе с приложением и общей средой выполнения. Крупные архивы моделей загружаются по требованию в постоянный том `/data/ai`, а затем повторно используются каждым инструментом, которому они нужны. Если пакет уже установлен, потому что его затребовал другой инструмент, включение нового зависимого инструмента не приводит к повторной загрузке этого пакета.
Большинству инструментов искусственного интеллекта требуется один или несколько пакетов функций, прежде чем они смогут работать. Пользовательский интерфейс администратора устанавливает их с помощью инструмента `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`.
| `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 |
Инструменты с межпакетными зависимостями:
| Инструмент | Требуемые пакеты | Причина |
|------|------------------|-----|
| `passport-photo` | `background-removal`, `face-detection` | Удаляет фон, затем использует ключевые точки лица, чтобы обрезать кадр под правила для фото на паспорт и удостоверение личности. |
| `enhance-faces` | `upscale-enhance`, `face-detection` | Распознаёт лица перед применением улучшения GFPGAN или CodeFormer к выбранным областям лица. |
Инструмент доступен только в том случае, если установлены все необходимые пакеты, за исключением 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`. Автономный импорт применяет те же проверки подписи, хеша, извлечения, совместимости и дымового тестирования, что и онлайн-установка; архив без доверенного подписанного индекса отклоняется.
**Модели:** Tesseract (`fast`); RapidOCR с небольшими моделями PP-OCRv6 (`balanced`); Средние модели PP-OCRv6 с калиброванной оценкой вариантов (`best`)
| `quality` | `"fast"` \| `"balanced"` \| `"best"` | Динамический | Если `quality` и `engine` не заданы, SnapOtter выбирает лучший доступный уровень в порядке `best`, `balanced`, `fast`. Для корейского языка `fast` никогда не выбирается: используется `best`, затем `balanced`, либо возвращается ошибка установки или совместимости точной среды выполнения. |
| `enhance` | логическое значение | Зависит от уровня | Улучшите локальный контраст. Fast применяет его напрямую; точные уровни сохраняют вариант только тогда, когда калиброванная оценка улучшает OCR. По умолчанию включено в лучшем случае |
| `engine` | нить | - | Устаревший псевдоним совместимости. Сопоставляет `tesseract`с`fast`, а устаревшее значение `paddleocr`с`balanced`; не загружается PaddlePaddle |
Возвращает извлеченный текст, а также метаданные происхождения: механизм, запрошенное и фактическое качество, устройство, поставщик, состояние деградации, предупреждения и точные версии времени выполнения/модели, если применимо. Явные запросы на качество никогда не переходят на другой уровень. Если `balanced` или `best` недоступны, API возвращает `FEATURE_NOT_INSTALLED` или `FEATURE_INCOMPATIBLE` вместо автоматического запуска `fast`.
| `quality` | `"fast"` \| `"balanced"` \| `"best"` | Динамический | Если `quality` и `engine` не заданы, SnapOtter выбирает лучший доступный уровень в порядке `best`, `balanced`, `fast`. Для корейского языка `fast` никогда не выбирается: используется `best`, затем `balanced`, либо возвращается ошибка установки или совместимости точной среды выполнения. |
| `enhance` | логическое значение | Зависит от уровня | Улучшите локальный контраст. Fast применяет его напрямую; точные уровни сохраняют вариант только тогда, когда калиброванная оценка улучшает OCR. По умолчанию включено в лучшем случае |
| `engine` | нить | - | Устаревший псевдоним совместимости. Сопоставляет `tesseract`с`fast`, а устаревшее значение `paddleocr`с`balanced`; не загружается PaddlePaddle |
То же правило запрета перехода на более раннюю версию применяется к PDF OCR. Страницы PDF перед распознаванием растрируются, и за один запрос можно выбрать не более 50 страниц.
| `quality` | number (1-100) | `90` | Качество вывода |
## Реставрация фотографий {#photo-restoration}
**Маршрут инструмента:**`restore-photo`
Многошаговый конвейер для старых или повреждённых фотографий: обнаружение и устранение царапин/разрывов, улучшение лиц, шумоподавление и опциональное раскрашивание.
**Модели:** ключевые точки лица MediaPipe + удаление фона BiRefNet
Двухфазный рабочий процесс: анализ (распознать лицо + удалить фон), затем генерация (обрезка, изменение размера, замощение). Поддерживает 37+ стран в 6 регионах.
### Фаза 1: анализ {#phase-1-analyze}
`POST /api/v1/tools/image/passport-photo/analyze`
Принимает файл изображения (multipart). Возвращает данные ключевых точек лица, base64-превью и размеры изображения.
| `adjustX` | number | `0` | Регулировка горизонтального положения |
| `adjustY` | number | `0` | Регулировка вертикального положения |
| `landmarks` | object | (обязательно) | Ключевые точки из фазы 1 |
| `imageWidth` | number | (обязательно) | Ширина изображения из фазы 1 |
| `imageHeight` | number | (обязательно) | Высота изображения из фазы 1 |
## Удаление объектов (инпейнтинг) {#object-erasing-inpainting}
**Маршрут инструмента:**`erase-object`
**Модель:** LaMa через ONNX Runtime
Маска отправляется как **вторая файловая часть** (имя поля `mask`), а не как base64. Белые пиксели в маске обозначают области для удаления. Настройки `format` и `quality` отправляются как поля формы верхнего уровня.
Исправляет «псевдопрозрачные» PNG, где фон был удалён, но остались бахрома, ореолы или полупрозрачные артефакты. Использует высокоразрешающую модель матирования BiRefNet для создания чистого альфа-канала, затем применяет настраиваемую обработку удаления бахромы для устранения цветового загрязнения вдоль краёв.
**Цепочка запасных вариантов при нехватке памяти (OOM):** Если BiRefNet HR-matting превышает доступную память, инструмент автоматически переходит на `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` | Общая сила коррекции |
Дополнительная конечная точка анализа доступна по адресу `POST /api/v1/tools/image/image-enhancement/analyze`, которая возвращает обнаруженные коррекции без их применения.
### Контентно-зависимое изменение размера (Seam Carving) {#content-aware-resize-seam-carving}
**Маршрут инструмента:**`content-aware-resize`
**Движок:** бинарник Go `caire` (не Python, без выгоды от GPU)
Интеллектуально изменяет размер изображений, удаляя низкоэнергетические швы и сохраняя важное содержимое.
| Параметр | Тип | По умолчанию | Описание |
|-----------|------|---------|-------------|
| `width` | number | - | Целевая ширина |
| `height` | number | - | Целевая высота |
| `protectFaces` | boolean | `false` | Защищать обнаруженные области лиц (требует пакет `face-detection`) |
| `blurRadius` | number (0-20) | `4` | Предварительное размытие для расчёта энергии |
| `sobelThreshold` | number (1-20) | `2` | Порог чувствительности к краям |
