Справочник по AI-движку

Пакет @snapotter/ai связывает Node.js с постоянным Python-сайдкаром для всех ML-операций. Процесс диспетчера остаётся активным между запросами, обеспечивая быстрый тёплый старт. NVIDIA CUDA автоматически определяется при запуске и используется, если доступна; иначе AI-инструменты работают на CPU.

Ускорение через iGPU Intel/AMD посредством VA-API, Quick Sync или OpenCL сегодня не поддерживается для AI-инференса. Проброс /dev/dri в контейнер не ускоряет эти инструменты Python-сайдкара, если не доступна NVIDIA GPU с поддержкой CUDA.

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

Архитектура

Node.js Tool Route
      |
      v
 @snapotter/ai bridge.ts
      | (stdin/stdout JSON + stderr progress events)
      v
 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)
      |-- colorize.py         (DDColor)
      |-- noise_removal.py    (SCUNet / tiered denoising)
      |-- red_eye_removal.py  (landmark + color analysis)
      |-- restore.py          (scratch repair + enhancement + denoising)
      |-- transcribe.py       (faster-whisper speech-to-text)
      +-- install_feature.py  (on-demand bundle installer)

Отдельный профиль диспетчера «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 с.

Пакеты возможностей

AI-модели упакованы по общему стеку зависимостей, а не по одному архиву на инструмент. Один пакет возможностей может включать несколько инструментов, если они используют одно семейство моделей, одни Python-колёса (wheels) или одни нативные библиотеки. Это позволяет держать релизный Docker-образ меньше и избегать хранения дубликатов одних и тех же моделей матирования фона, распознавания лиц, OCR, реставрации и речи.

Docker-образ поставляется вместе с приложением и общей средой выполнения. Крупные архивы моделей загружаются по требованию в постоянный том /data/ai, а затем повторно используются каждым инструментом, которому они нужны. Если пакет уже установлен, потому что его затребовал другой инструмент, включение нового зависимого инструмента не приводит к повторной загрузке этого пакета.

Каждому AI-инструменту требуется один или несколько пакетов возможностей, прежде чем он сможет работать. Админ-интерфейс устанавливает пакеты по инструменту через POST /api/v1/admin/tools/:toolId/features/install, который определяет полный список пакетов, пропускает уже установленные и ставит в очередь только недостающие загрузки. Например, включение «Фото на паспорт» на новом экземпляре ставит в очередь background-removal и face-detection; включение того же инструмента после того, как уже установлено «Удаление фона», ставит в очередь только face-detection.

Пакет	Размер	Общая группа зависимостей	Инструменты, использующие его
`background-removal`	4-5 GB	матирование фона rembg / BiRefNet	remove-background, passport-photo, transparency-fixer, background-replace, blur-background
`face-detection`	200-300 MB	распознавание лиц и ключевых точек MediaPipe	blur-faces, red-eye-removal, smart-crop
`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
`transcription`	~600 MB	модели преобразования речи в текст faster-whisper	transcribe-audio, auto-subtitles

Инструменты с межпакетными зависимостями:

Инструмент	Требуемые пакеты	Причина
`passport-photo`	`background-removal`, `face-detection`	Удаляет фон, затем использует ключевые точки лица, чтобы обрезать кадр под правила для фото на паспорт и удостоверение личности.
`enhance-faces`	`upscale-enhance`, `face-detection`	Распознаёт лица перед применением улучшения GFPGAN или CodeFormer к выбранным областям лица.

Инструмент доступен только тогда, когда установлены все его требуемые пакеты. Частичная установка допустима и обрабатывается инкрементально: установленные пакеты используются повторно, недостающие пакеты показываются как загрузки, а поставленные в очередь установки выполняются по одной, чтобы общая среда Python не изменялась одновременно.

Удаление фона

Маршрут инструмента: remove-background
Модель: rembg с BiRefNet (по умолчанию) или варианты U2-Net

Параметр	Тип	По умолчанию	Описание
`model`	string	-	Вариант модели (опциональное переопределение)
`backgroundType`	string	`"transparent"`	Одно из: `transparent`, `color`, `gradient`, `blur`, `image`
`backgroundColor`	string	-	Hex-цвет для сплошного фона
`gradientColor1`	string	-	Первый цвет градиента
`gradientColor2`	string	-	Второй цвет градиента
`gradientAngle`	number	-	Угол градиента в градусах
`blurEnabled`	boolean	-	Включить эффект размытия фона
`blurIntensity`	number (0-100)	-	Интенсивность размытия
`shadowEnabled`	boolean	-	Включить падающую тень от объекта
`shadowOpacity`	number (0-100)	-	Непрозрачность тени
`outputFormat`	string	-	Формат вывода: `png`, `webp` или `avif`
`edgeRefine`	integer (0-3)	-	Уровень уточнения краёв
`decontaminate`	boolean	-	Убрать растекание цвета с краёв

Замена фона

Маршрут инструмента: background-replace
Модель: rembg / BiRefNet (общая с remove-background)

Удаляет фон и заменяет его сплошным цветом или градиентом.

Параметр	Тип	По умолчанию	Описание
`backgroundType`	`"color"` \| `"gradient"`	`"color"`	Режим фона
`color`	string	`"#ffffff"`	Hex-цвет фона (когда `backgroundType` равно `color`)
`gradientColor1`	string	-	Первый hex-цвет градиента
`gradientColor2`	string	-	Второй hex-цвет градиента
`gradientAngle`	integer (0-360)	`180`	Угол градиента в градусах
`feather`	integer (0-20)	`0`	Радиус растушёвки краёв
`format`	`"png"` \| `"webp"`	`"png"`	Формат вывода

Размытие фона

Маршрут инструмента: blur-background
Модель: rembg / BiRefNet (общая с remove-background)

Размывает фон, сохраняя объект резким.

Параметр	Тип	По умолчанию	Описание
`intensity`	integer (1-100)	`50`	Интенсивность размытия
`feather`	integer (0-20)	`0`	Радиус растушёвки краёв
`format`	`"png"` \| `"webp"`	`"png"`	Формат вывода

Апскейлинг изображений

Маршрут инструмента: upscale
Модель: RealESRGAN (с запасным вариантом Lanczos при недоступности)

Параметр	Тип	По умолчанию	Описание
`scale`	number	`2`	Коэффициент увеличения
`model`	string	`"auto"`	Вариант модели
`faceEnhance`	boolean	`false`	Применить проход улучшения лиц GFPGAN
`denoise`	number	`0`	Сила шумоподавления
`format`	string	`"auto"`	Переопределение формата вывода
`quality`	number	`95`	Качество вывода (1-100)

OCR / извлечение текста

Маршрут инструмента: ocr
Модели: Tesseract (быстро), PaddleOCR PP-OCRv5 (сбалансированно), PaddleOCR-VL 1.5 (лучшее качество)

Параметр	Тип	По умолчанию	Описание
`quality`	`"fast"` \| `"balanced"` \| `"best"`	`"balanced"`	Уровень обработки
`language`	string	`"auto"`	Язык: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko`
`enhance`	boolean	`true`	Предобработка изображения для повышения точности OCR
`engine`	string	-	Устарело. Сопоставляет `tesseract` с `fast`, `paddleocr` с `balanced`

Возвращает структурированные результаты с ограничивающими рамками, оценками достоверности и извлечёнными блоками текста.

OCR для PDF

Маршрут инструмента: ocr-pdf
Модели: Та же система уровней, что и у OCR изображений

Извлекает текст из отсканированных PDF-документов с помощью AI-OCR, страница за страницей.

Параметр	Тип	По умолчанию	Описание
`quality`	`"fast"` \| `"balanced"` \| `"best"`	`"balanced"`	Уровень обработки
`language`	string	`"auto"`	Язык: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko`
`pages`	string	`"all"`	Выбор страниц: `"all"`, `"1-3"`, `"1,3,5"`

Размытие лиц / персональных данных

Маршрут инструмента: blur-faces
Модель: распознавание лиц MediaPipe

Параметр	Тип	По умолчанию	Описание
`blurRadius`	number (1-100)	`30`	Радиус гауссова размытия
`sensitivity`	number (0-1)	`0.5`	Порог достоверности распознавания

Улучшение лиц

Маршрут инструмента: enhance-faces
Модели: GFPGAN, CodeFormer

Параметр	Тип	По умолчанию	Описание
`model`	`"auto"` \| `"gfpgan"` \| `"codeformer"`	`"auto"`	Модель улучшения
`strength`	number (0-1)	`0.8`	Сила улучшения
`sensitivity`	number (0-1)	`0.5`	Порог распознавания лиц
`onlyCenterFace`	boolean	`false`	Улучшать только самое центральное лицо

AI-раскрашивание

Маршрут инструмента: colorize
Модель: DDColor (с запасным вариантом OpenCV DNN)

Преобразует чёрно-белые или полутоновые фотографии в полноцветные.

Параметр	Тип	По умолчанию	Описание
`intensity`	number (0-1)	`1.0`	Сила насыщенности цвета
`model`	`"auto"` \| `"ddcolor"` \| `"opencv"`	`"auto"`	Вариант модели

Удаление шума

Маршрут инструмента: noise-removal
Модель: SCUNet (многоуровневый конвейер шумоподавления)

Параметр	Тип	По умолчанию	Описание
`tier`	`"quick"` \| `"balanced"` \| `"quality"` \| `"maximum"`	`"balanced"`	Уровень обработки
`strength`	number (0-100)	`50`	Сила шумоподавления
`detailPreservation`	number (0-100)	`50`	Сколько деталей сохранять; выше значение сохраняет больше текстуры
`colorNoise`	number (0-100)	`30`	Сила подавления цветового шума
`format`	string	`"original"`	Формат вывода: `original`, `png`, `jpeg`, `webp`, `avif`, `jxl`
`quality`	number (1-100)	`90`	Качество кодирования вывода

Удаление эффекта красных глаз

Маршрут инструмента: red-eye-removal

Распознаёт ключевые точки лица, находит области глаз и корректирует перенасыщенность красного канала.

Параметр	Тип	По умолчанию	Описание
`sensitivity`	number (0-100)	`50`	Порог обнаружения красных пикселей
`strength`	number (0-100)	`70`	Сила коррекции
`format`	string	-	Переопределение формата вывода (опционально)
`quality`	number (1-100)	`90`	Качество вывода

Реставрация фотографий

Маршрут инструмента: restore-photo

Многошаговый конвейер для старых или повреждённых фотографий: обнаружение и устранение царапин/разрывов, улучшение лиц, шумоподавление и опциональное раскрашивание.

Параметр	Тип	По умолчанию	Описание
`scratchRemoval`	boolean	`true`	Обнаруживать и устранять царапины, разрывы
`faceEnhancement`	boolean	`true`	Применить проход улучшения лиц
`fidelity`	number (0-1)	`0.7`	Сила улучшения лиц (выше = более консервативно)
`denoise`	boolean	`true`	Применить проход шумоподавления
`denoiseStrength`	number (0-100)	`25`	Сила шумоподавления
`colorize`	boolean	`false`	Раскрасить после реставрации
`colorizeStrength`	number (0-100)	`85`	Интенсивность раскрашивания

Фото на паспорт

Маршрут инструмента: passport-photo
Модели: ключевые точки лица MediaPipe + удаление фона BiRefNet

Двухфазный рабочий процесс: анализ (распознать лицо + удалить фон), затем генерация (обрезка, изменение размера, замощение). Поддерживает 37+ стран в 6 регионах.

Фаза 1: анализ

POST /api/v1/tools/image/passport-photo/analyze

Принимает файл изображения (multipart). Возвращает данные ключевых точек лица, base64-превью и размеры изображения.

Фаза 2: генерация

POST /api/v1/tools/image/passport-photo/generate

Принимает JSON-тело с результатами фазы 1 плюс настройки генерации:

Параметр	Тип	По умолчанию	Описание
`jobId`	string	(обязательно)	Идентификатор задания из фазы 1
`filename`	string	(обязательно)	Исходное имя файла из фазы 1
`countryCode`	string	(обязательно)	ISO-код страны (например, `US`, `GB`, `IN`)
`documentType`	string	`"passport"`	Тип документа
`bgColor`	string	`"#FFFFFF"`	Hex-цвет фона
`printLayout`	string	`"none"`	Макет печати: `none`, `4x6`, `a4`, `letter`
`maxFileSizeKb`	number	`0`	Максимальный размер файла в KB (0 = без ограничения)
`dpi`	number (72-1200)	`300`	DPI вывода
`customWidthMm`	number	-	Пользовательская ширина в мм (переопределяет спецификацию страны)
`customHeightMm`	number	-	Пользовательская высота в мм (переопределяет спецификацию страны)
`zoom`	number (0.5-3)	`1`	Коэффициент масштабирования
`adjustX`	number	`0`	Регулировка горизонтального положения
`adjustY`	number	`0`	Регулировка вертикального положения
`landmarks`	object	(обязательно)	Ключевые точки из фазы 1
`imageWidth`	number	(обязательно)	Ширина изображения из фазы 1
`imageHeight`	number	(обязательно)	Высота изображения из фазы 1

Удаление объектов (инпейнтинг)

Маршрут инструмента: erase-object
Модель: LaMa через ONNX Runtime

Маска отправляется как вторая файловая часть (имя поля mask), а не как base64. Белые пиксели в маске обозначают области для удаления. Настройки format и quality отправляются как поля формы верхнего уровня.

Параметр	Тип	По умолчанию	Описание
`file`	file	(обязательно)	Исходное изображение (multipart)
`mask`	file	(обязательно)	Изображение маски (multipart, имя поля `mask`, белое = удалить)
`format`	string	`"auto"`	Формат вывода: `auto`, `png`, `jpg`, `jpeg`, `webp`, `tiff`, `gif`, `avif`, `heic`, `heif`, `jxl`
`quality`	integer (1-100)	`95`	Качество вывода

Ускоряется через CUDA при наличии NVIDIA GPU.

AI-расширение холста

Маршрут инструмента: ai-canvas-expand
Модель: аутпейнтинг на базе LaMa

Расширяет холст изображения в любом направлении и заполняет новые области сгенерированным AI-содержимым, совпадающим с существующим изображением.

Параметр	Тип	По умолчанию	Описание
`extendTop`	integer	`0`	Пикселей для расширения сверху
`extendRight`	integer	`0`	Пикселей для расширения справа
`extendBottom`	integer	`0`	Пикселей для расширения снизу
`extendLeft`	integer	`0`	Пикселей для расширения слева
`tier`	`"fast"` \| `"balanced"` \| `"high"`	`"balanced"`	Уровень качества
`format`	string	`"auto"`	Формат вывода: `auto`, `png`, `jpg`, `jpeg`, `webp`, `tiff`, `gif`, `avif`, `heic`, `heif`, `jxl`
`quality`	integer (1-100)	`95`	Качество вывода

Хотя бы одно направление расширения должно быть больше 0.

Умная обрезка

Маршрут инструмента: smart-crop
Модель: распознавание лиц MediaPipe (только режим лиц)

Параметр	Тип	По умолчанию	Описание
`mode`	string	`"subject"`	Стратегия обрезки: `subject`, `face`, `trim`
`strategy`	`"attention"` \| `"entropy"`	`"attention"`	Стратегия для режима объекта
`width`	integer	-	Ширина вывода
`height`	integer	-	Высота вывода
`padding`	integer (0-50)	`0`	Процент отступа вокруг объекта
`facePreset`	string	`"head-shoulders"`	Предустановка кадрирования, когда `mode=face`
`sensitivity`	number (0-1)	`0.5`	Порог распознавания лиц
`threshold`	integer (0-255)	`30`	Порог определения фона (режим обрезки)
`padToSquare`	boolean	`false`	Дополнить обрезанный результат до квадрата
`padColor`	string	`"#ffffff"`	Цвет фона для квадратного дополнения
`targetSize`	integer	-	Целевой размер для дополненного вывода (пиксели)
`quality`	integer (1-100)	-	Качество вывода

Устаревшие значения mode attention и content принимаются и сопоставляются с subject и trim соответственно.

Предустановки для лиц:

Предустановка	Лучше всего для
`closeup`	Портретные фото
`head-shoulders`	Фото профиля
`upper-body`	LinkedIn / официальные
`half-body`	Вся верхняя часть тела

Транскрибирование аудио

Маршрут инструмента: transcribe-audio
Модель: faster-whisper

Преобразует речь в текст. Поддерживает вывод в форматах простого текста, SRT и VTT.

Параметр	Тип	По умолчанию	Описание
`language`	string	`"auto"`	Язык: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko`, `id`, `th`, `vi`
`outputFormat`	`"txt"` \| `"srt"` \| `"vtt"`	`"txt"`	Формат вывода

Автоматические субтитры

Маршрут инструмента: auto-subtitles
Модель: faster-whisper (извлекает аудио из видео, затем транскрибирует)

Генерирует файлы субтитров из звуковой дорожки видео.

Параметр	Тип	По умолчанию	Описание
`language`	string	`"auto"`	Язык: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko`, `id`, `th`, `vi`
`format`	`"srt"` \| `"vtt"`	`"srt"`	Формат вывода субтитров

Исправление прозрачности PNG

Маршрут инструмента: transparency-fixer
Модель: BiRefNet HR-matting (разрешение 2048x2048)

Исправляет «псевдопрозрачные» PNG, где фон был удалён, но остались бахрома, ореолы или полупрозрачные артефакты. Использует высокоразрешающую модель матирования BiRefNet для создания чистого альфа-канала, затем применяет настраиваемую обработку удаления бахромы для устранения цветового загрязнения вдоль краёв.

Цепочка запасных вариантов при нехватке памяти (OOM): Если BiRefNet HR-matting превышает доступную память, инструмент автоматически переходит на birefnet-general, затем на u2net.

Параметр	Тип	По умолчанию	Описание
`defringe`	number (0-100)	`30`	Сила удаления бахромы по краям для устранения цветового загрязнения
`outputFormat`	`"png"` \| `"webp"`	`"png"`	Формат выходного изображения
`removeWatermark`	boolean	`false`	Применить предобработку удаления водяных знаков (медианный фильтр)

bash

curl -X POST http://localhost:1349/api/v1/tools/image/transparency-fixer \
  -H "Authorization: Bearer <token>" \
  -F "[email protected]" \
  -F 'settings={"defringe":30,"outputFormat":"png"}'

Инструменты с опциональными AI-возможностями

Следующие инструменты не являются инструментами Python-сайдкара, но используют AI-возможности, когда включены определённые опции.

Улучшение изображений

Маршрут инструмента: 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`	Применить коррекцию резкости
`corrections.denoise`	boolean	`true`	Применить шумоподавление
`deepEnhance`	boolean	`false`	Включить AI-удаление шума через SCUNet (требует пакет `upscale-enhance`)

Дополнительная конечная точка анализа доступна по адресу POST /api/v1/tools/image/image-enhancement/analyze, которая возвращает обнаруженные коррекции без их применения.

Контентно-зависимое изменение размера (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`	Порог чувствительности к краям
`square`	boolean	`false`	Принудительный квадратный вывод

Essentials

Optimization

Adjustments

Watermark & Overlay

Utilities

Layout

Format

AI Tools

Справочник по AI-движку

Архитектура

Пакеты возможностей

Удаление фона

Замена фона

Размытие фона

Апскейлинг изображений

OCR / извлечение текста

OCR для PDF

Размытие лиц / персональных данных

Улучшение лиц

AI-раскрашивание

Удаление шума

Удаление эффекта красных глаз

Реставрация фотографий

Фото на паспорт

Фаза 1: анализ

Фаза 2: генерация

Удаление объектов (инпейнтинг)

AI-расширение холста

Умная обрезка

Транскрибирование аудио

Автоматические субтитры

Исправление прозрачности PNG

Инструменты с опциональными AI-возможностями

Улучшение изображений

Контентно-зависимое изменение размера (Seam Carving)

Справочник по AI-движку ​

Архитектура ​

Пакеты возможностей ​

Удаление фона ​

Замена фона ​

Размытие фона ​

Апскейлинг изображений ​

OCR / извлечение текста ​

OCR для PDF ​

Размытие лиц / персональных данных ​

Улучшение лиц ​

AI-раскрашивание ​

Удаление шума ​

Удаление эффекта красных глаз ​

Реставрация фотографий ​

Фото на паспорт ​

Фаза 1: анализ ​

Фаза 2: генерация ​

Удаление объектов (инпейнтинг) ​

AI-расширение холста ​

Умная обрезка ​

Транскрибирование аудио ​

Автоматические субтитры ​

Исправление прозрачности PNG ​

Инструменты с опциональными AI-возможностями ​

Улучшение изображений ​

Контентно-зависимое изменение размера (Seam Carving) ​

Справочник по AI-движку

Архитектура

Пакеты возможностей

Удаление фона

Замена фона

Размытие фона

Апскейлинг изображений

OCR / извлечение текста

OCR для PDF

Размытие лиц / персональных данных

Улучшение лиц

AI-раскрашивание

Удаление шума

Удаление эффекта красных глаз

Реставрация фотографий

Фото на паспорт

Фаза 1: анализ

Фаза 2: генерация

Удаление объектов (инпейнтинг)

AI-расширение холста

Умная обрезка

Транскрибирование аудио

Автоматические субтитры

Исправление прозрачности PNG

Инструменты с опциональными AI-возможностями

Улучшение изображений

Контентно-зависимое изменение размера (Seam Carving)