Довідник рушія ШІ

Пакет @snapotter/ai з'єднує Node.js із постійним допоміжним процесом Python для всіх операцій ML. Процес диспетчера залишається активним між запитами задля швидкого «теплого» старту. NVIDIA CUDA автоматично визначається під час запуску та використовується за наявності; в іншому разі інструменти ШІ працюють на CPU.

Прискорення на iGPU Intel/AMD через VA-API, Quick Sync або OpenCL наразі не підтримується для інференсу ШІ. Прокидання /dev/dri в контейнер не прискорює ці інструменти допоміжного процесу Python, якщо немає NVIDIA GPU з підтримкою CUDA.

19 інструментів ШІ на допоміжному процесі Python у чотирьох модальностях (зображення, аудіо, відео, документ), а також 2 інструменти з необов'язковими можливостями ШІ. Усі моделі працюють локально: після початкового завантаження моделі інтернет не потрібен.

Архітектура

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» замінює список дозволених ШІ на скрипти обробки документів (doc_pagecount, doc_health, doc_flatten, doc_redact, doc_text, doc_to_word, doc_metadata, doc_html_pdf) і пропускає важкі імпорти ML.

Тайм-аути: 300 с за замовчуванням; OCR та видалення фону BiRefNet отримують 600 с.

Набори функцій

Моделі ШІ пакуються за спільним стеком залежностей, а не по одному архіву на інструмент. Набір функцій може вмикати декілька інструментів, коли вони використовують одну родину моделей, Python-колеса або нативні бібліотеки. Це зменшує розмір релізного Docker-образу й уникає зберігання дублікатів тих самих моделей матування фону, розпізнавання облич, OCR, реставрації та мовлення.

Docker-образ постачає застосунок разом зі спільним середовищем виконання. Великі архіви моделей завантажуються за потреби в постійний том /data/ai, а далі повторно використовуються кожним інструментом, якому вони потрібні. Якщо набір уже встановлено, бо його потребував інший інструмент, увімкнення нового залежного інструмента не завантажує цей набір повторно.

Кожен інструмент ШІ вимагає одного чи кількох наборів функцій, перш ніж зможе працювати. Адмін-інтерфейс встановлює за інструментом через POST /api/v1/admin/tools/:toolId/features/install, який розкриває повний список наборів, пропускає вже встановлені набори та ставить у чергу лише відсутні завантаження. Наприклад, увімкнення Passport Photo на новому екземплярі ставить у чергу background-removal і face-detection; увімкнення його після того, як уже встановлено Background Removal, ставить у чергу лише face-detection.

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

Інструменти з міжнабірними залежностями:

Інструмент	Потрібні набори	Чому
passport-photo	background-removal, face-detection	Видаляє фон, а потім за орієнтирами обличчя кадрує кроп під правила фото на паспорт та ID.
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-документів за допомогою 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"

Розмиття облич / PII

Маршрут інструмента: 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	Покращувати лише найцентральніше обличчя

Колоризація ШІ

Маршрут інструмента: 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	(обов'язково)	ID завдання з Фази 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	Макс. розмір файлу в КБ (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

Стирання об'єктів (Inpainting)

Маршрут інструмента: 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-canvas-expand
Модель: outpainting на базі LaMa

Розширює полотно зображення в будь-якому напрямку та заповнює нові області згенерованим ШІ вмістом, що відповідає наявному зображенню.

Параметр	Тип	За замовчуванням	Опис
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
Модель: матування HR BiRefNet (роздільна здатність 2048x2048)

Виправляє «псевдопрозорі» PNG, де фон було видалено, але залишилися облямівка, ореоли чи напівпрозорі артефакти. Використовує модель матування високої роздільної здатності BiRefNet для створення чистого альфа-каналу, а потім застосовує налаштовувану обробку прибирання облямівки, щоб усунути колірне забруднення вздовж країв.

Ланцюг резервів OOM: Якщо матування HR BiRefNet перевищує доступну пам'ять, інструмент автоматично переходить на birefnet-general, а потім на u2net.

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

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"}'

---

Інструменти з необов'язковими можливостями ШІ

Наведені нижче інструменти не є інструментами допоміжного процесу Python, але використовують функції ШІ, коли ввімкнено певні опції.

Покращення зображення

Маршрут інструмента: 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	Увімкнути видалення шуму ШІ через 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	Примусовий квадратний вивід