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 |
|---|---|---|---|
| Справочник по AI-движку со всеми локальными ML-инструментами. Удаление фона, апскейлинг, OCR, распознавание лиц, реставрация фотографий и другое. | 14728c1dcd05 | machine | 362d36a75c8d |
Справочник по 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 |
Применить предобработку удаления водяных знаков (медианный фильтр) |
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"}'
Инструменты с опциональными 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 |
Принудительный квадратный вывод |