SnapOtterandGitHub
4963ab3bbd
All 181 docs markdown files translated into 20 languages (apps/docs/<locale>/**). Companion to the i18n code PR; admin-merged because the file count exceeds GitHub's per-PR CI trigger limit. Validated by pnpm i18n:check (all surfaces, 0 stale/missing) and a clean all-locale docs build.
32 KiB
description, i18n_source_hash, i18n_provenance, i18n_output_hash
| description | i18n_source_hash | i18n_provenance | i18n_output_hash |
|---|---|---|---|
| Довідник рушія ШІ з усіма локальними інструментами ML. Видалення фону, збільшення роздільної здатності, OCR, розпізнавання облич, реставрація фото та інше. | 14728c1dcd05 | machine | e36cdc2779d7 |
Довідник рушія ШІ
Пакет @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 "file=@fake-transparent.png" \
-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 |
Примусовий квадратний вивід |