mirror of
https://github.com/snapotter-hq/SnapOtter.git
synced 2026-08-03 07:46:42 +02:00
SnapOtterandGitHub
991c981529
* fix: make OCR portable and reliable * fix: harden OCR installation portability * fix: pin OCR partials across downloads * fix: make OCR execution reliably asynchronous * fix: harden OCR portability and docs routes * fix: preserve decoder and docs safeguards
463 lines
40 KiB
Markdown
463 lines
40 KiB
Markdown
---
|
||
description: "Довідник рушія ШІ з усіма локальними інструментами ML. Видалення фону, збільшення роздільної здатності, OCR, розпізнавання облич, реставрація фото та інше."
|
||
i18n_output_hash: 3a80b8a66b82
|
||
i18n_source_hash: aa9a56cdddc7
|
||
i18n_provenance: human
|
||
---
|
||
|
||
# Довідник рушія ШІ {#ai-engine-reference}
|
||
|
||
Пакет `@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 наразі не підтримується для інференсу ШІ. Прокидання `/dev/dri` в контейнер не прискорює ці інструменти допоміжного процесу Python, якщо немає NVIDIA GPU з підтримкою CUDA.
|
||
|
||
19 інструментів ШІ на допоміжному процесі Python у чотирьох модальностях (зображення, аудіо, відео, документ), а також 2 інструменти з необов'язковими можливостями ШІ. Усі моделі працюють локально: після початкового завантаження моделі інтернет не потрібен.
|
||
|
||
|
||
<!-- korean-ocr-contract:start -->
|
||
::: info Сумісність OCR для корейської мови
|
||
Швидкий 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`.
|
||
:::
|
||
<!-- korean-ocr-contract:end -->
|
||
## Архітектура {#architecture}
|
||
|
||
```
|
||
Node.js Tool Route
|
||
|
|
||
v
|
||
@snapotter/ai bridge.ts
|
||
| (stdin/stdout JSON + stderr progress events)
|
||
v
|
||
+-- Native Tesseract + Ghostscript (fast image/PDF OCR)
|
||
|
|
||
+-- Isolated OCR runtime (persistent JSONL dispatcher)
|
||
| `-- RapidOCR + ONNX Runtime CPU + pinned PP-OCR models
|
||
|
|
||
`-- Python dispatcher (persistent process, "ai" profile)
|
||
|
|
||
|-- remove_bg.py (rembg / BiRefNet)
|
||
|-- upscale.py (RealESRGAN)
|
||
|-- inpaint.py (LaMa ONNX)
|
||
|-- outpaint.py (LaMa canvas expansion)
|
||
|-- 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 с.
|
||
|
||
## Набори функцій {#feature-bundles}
|
||
|
||
Моделі ШІ пакуються за спільним стеком залежностей, а не по одному архіву на інструмент. Набір функцій може вмикати декілька інструментів, коли вони використовують одну родину моделей, Python-колеса або нативні бібліотеки. Це зменшує розмір релізного 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`.
|
||
|
||
| Набір | Розмір | Група спільних залежностей | Інструменти, що його використовують |
|
||
|--------|------|-------------------------|-------------------|
|
||
| `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` | ~208-234 MiB завантажити / ~409-488 MiB встановити | Додаткові RapidOCR 3.9.1, ONNX Runtime 1.20.1 і закріплені моделі PP-OCR | ocr, ocr-pdf (лише `balanced` і `best`) |
|
||
| `transcription` | ~600 МБ | моделі мовлення в текст faster-whisper | transcribe-audio, auto-subtitles |
|
||
|
||
Інструменти з міжнабірними залежностями:
|
||
|
||
| Інструмент | Потрібні набори | Чому |
|
||
|------|------------------|-----|
|
||
| `passport-photo` | `background-removal`, `face-detection` | Видаляє фон, а потім за орієнтирами обличчя кадрує кроп під правила фото на паспорт та ID. |
|
||
| `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`. Офлайн-імпорт використовує ті самі перевірки підпису, хешу, вилучення, сумісності та димового тесту, що й онлайн-інсталяція; архів без довіреного підписаного індексу відхилено.
|
||
|
||
---
|
||
|
||
## Видалення фону {#background-removal}
|
||
|
||
**Маршрут інструмента:** `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}
|
||
|
||
**Маршрут інструмента:** `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}
|
||
|
||
**Маршрут інструмента:** `blur-background`
|
||
**Модель:** rembg / BiRefNet (спільна з remove-background)
|
||
|
||
Розмиває фон, зберігаючи об'єкт чітким.
|
||
|
||
| Параметр | Тип | За замовчуванням | Опис |
|
||
|-----------|------|---------|-------------|
|
||
| `intensity` | integer (1-100) | `50` | Інтенсивність розмиття |
|
||
| `feather` | integer (0-20) | `0` | Радіус розтушовування країв |
|
||
| `format` | `"png"` \| `"webp"` | `"png"` | Формат виводу |
|
||
|
||
## Збільшення роздільної здатності зображення {#image-upscaling}
|
||
|
||
**Маршрут інструмента:** `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-text-extraction}
|
||
|
||
**Маршрут інструмента:** `ocr`
|
||
**Моделі:** Tesseract (`fast`); RapidOCR з маленькими моделями PP-OCRv6 (`balanced`); Середні моделі PP-OCRv6 з каліброваним варіантом балів (`best`)
|
||
|
||
| Параметр | Тип | За замовчуванням | Опис |
|
||
|-----------|------|---------|-------------|
|
||
| `quality` | `"fast"` \| `"balanced"` \| `"best"` | Динамічний | Якщо `quality` і `engine` не задано, SnapOtter вибирає найкращий доступний рівень у порядку `best`, `balanced`, `fast`. Для корейської мови `fast` ніколи не вибирається: використовується `best`, потім `balanced`, або повертається помилка встановлення чи сумісності точного середовища виконання. |
|
||
| `language` | string | `"auto"` | Мова: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko` |
|
||
| `enhance` | логічний | Залежно від рівня | Поліпшення локального контрасту. Fast застосовує його безпосередньо; точні рівні зберігають варіант лише тоді, коли калібрована оцінка покращує OCR. За замовчуванням для найкращого |
|
||
| `engine` | рядок | - | Застарілий псевдонім сумісності. Зіставляє `tesseract` на `fast` і застаріле значення `paddleocr` на `balanced`; він не завантажує PaddlePaddle |
|
||
|
||
Повертає витягнутий текст, а також метадані про походження: механізм, запитану та фактичну якість, пристрій, постачальника, стан деградації, попередження та точні версії часу виконання/моделі, якщо це можливо. Явні запити щодо якості ніколи не повертаються до іншого рівня. Якщо `balanced` або `best` недоступні, API повертає `FEATURE_NOT_INSTALLED` або `FEATURE_INCOMPATIBLE` замість тихого запуску `fast`.
|
||
|
||
## OCR для PDF {#pdf-ocr}
|
||
|
||
**Маршрут інструмента:** `ocr-pdf`
|
||
**Моделі:** Та сама система рівнів, що й для OCR зображень
|
||
|
||
Витягає текст зі сканованих PDF-документів за допомогою OCR на базі ШІ, сторінка за сторінкою.
|
||
|
||
| Параметр | Тип | За замовчуванням | Опис |
|
||
|-----------|------|---------|-------------|
|
||
| `quality` | `"fast"` \| `"balanced"` \| `"best"` | Динамічний | Якщо `quality` і `engine` не задано, SnapOtter вибирає найкращий доступний рівень у порядку `best`, `balanced`, `fast`. Для корейської мови `fast` ніколи не вибирається: використовується `best`, потім `balanced`, або повертається помилка встановлення чи сумісності точного середовища виконання. |
|
||
| `language` | string | `"auto"` | Мова: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko` |
|
||
| `pages` | string | `"all"` | Вибір сторінок: `"all"`, `"1-3"`, `"1,3,5"` |
|
||
| `enhance` | логічний | Залежно від рівня | Поліпшення локального контрасту. Fast застосовує його безпосередньо; точні рівні зберігають варіант лише тоді, коли калібрована оцінка покращує OCR. За замовчуванням для найкращого |
|
||
| `engine` | рядок | - | Застарілий псевдонім сумісності. Зіставляє `tesseract` на `fast` і застаріле значення `paddleocr` на `balanced`; він не завантажує PaddlePaddle |
|
||
|
||
Таке ж правило заборони на пониження версії застосовується до PDF OCR. Сторінки PDF растеризуються перед розпізнаванням, і один запит може вибрати не більше 50 сторінок.
|
||
|
||
## Розмиття облич / PII {#face-pii-blur}
|
||
|
||
**Маршрут інструмента:** `blur-faces`
|
||
**Модель:** розпізнавання облич MediaPipe
|
||
|
||
| Параметр | Тип | За замовчуванням | Опис |
|
||
|-----------|------|---------|-------------|
|
||
| `blurRadius` | number (1-100) | `30` | Радіус гаусового розмиття |
|
||
| `sensitivity` | number (0-1) | `0.5` | Поріг впевненості розпізнавання |
|
||
|
||
## Покращення облич {#face-enhancement}
|
||
|
||
**Маршрут інструмента:** `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-colorization}
|
||
|
||
**Маршрут інструмента:** `colorize`
|
||
**Модель:** DDColor (з резервним OpenCV DNN)
|
||
|
||
Перетворює чорно-білі або відтінково-сірі фото на повнокольорові.
|
||
|
||
| Параметр | Тип | За замовчуванням | Опис |
|
||
|-----------|------|---------|-------------|
|
||
| `intensity` | number (0-1) | `1.0` | Сила насиченості кольору |
|
||
| `model` | `"auto"` \| `"ddcolor"` \| `"opencv"` | `"auto"` | Варіант моделі |
|
||
|
||
## Видалення шуму {#noise-removal}
|
||
|
||
**Маршрут інструмента:** `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}
|
||
|
||
**Маршрут інструмента:** `red-eye-removal`
|
||
|
||
Розпізнає орієнтири обличчя, локалізує області очей і виправляє перенасичення червоного каналу.
|
||
|
||
| Параметр | Тип | За замовчуванням | Опис |
|
||
|-----------|------|---------|-------------|
|
||
| `sensitivity` | number (0-100) | `50` | Поріг розпізнавання червоних пікселів |
|
||
| `strength` | number (0-100) | `70` | Сила корекції |
|
||
| `format` | string | - | Перевизначення формату виводу (необов'язкове) |
|
||
| `quality` | number (1-100) | `90` | Якість виводу |
|
||
|
||
## Реставрація фото {#photo-restoration}
|
||
|
||
**Маршрут інструмента:** `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}
|
||
|
||
**Маршрут інструмента:** `passport-photo`
|
||
**Моделі:** орієнтири обличчя MediaPipe + видалення фону BiRefNet
|
||
|
||
Двофазний робочий процес: аналіз (розпізнати обличчя + видалити фон), потім генерація (кроп, зміна розміру, розкладка). Підтримує 37+ країн у 6 регіонах.
|
||
|
||
### Фаза 1: Аналіз {#phase-1-analyze}
|
||
|
||
`POST /api/v1/tools/image/passport-photo/analyze`
|
||
|
||
Приймає файл зображення (multipart). Повертає дані орієнтирів обличчя, попередній перегляд у base64 та розміри зображення.
|
||
|
||
### Фаза 2: Генерація {#phase-2-generate}
|
||
|
||
`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) {#object-erasing-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}
|
||
|
||
**Маршрут інструмента:** `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}
|
||
|
||
**Маршрут інструмента:** `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}
|
||
|
||
**Маршрут інструмента:** `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}
|
||
|
||
**Маршрут інструмента:** `auto-subtitles`
|
||
**Модель:** faster-whisper (витягає аудіо з відео, потім транскрибує)
|
||
|
||
Генерує файли субтитрів з аудіодоріжки відео.
|
||
|
||
| Параметр | Тип | За замовчуванням | Опис |
|
||
|-----------|------|---------|-------------|
|
||
| `language` | string | `"auto"` | Мова: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko`, `id`, `th`, `vi` |
|
||
| `format` | `"srt"` \| `"vtt"` | `"srt"` | Формат вихідних субтитрів |
|
||
|
||
## Виправлення прозорості PNG {#png-transparency-fixer}
|
||
|
||
**Маршрут інструмента:** `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` | Застосувати попередню обробку видалення водяного знака (медіанний фільтр) |
|
||
|
||
```bash
|
||
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"}'
|
||
```
|
||
|
||
---
|
||
|
||
## Інструменти з необов'язковими можливостями ШІ {#tools-with-optional-ai-capabilities}
|
||
|
||
Наведені нижче інструменти не є інструментами допоміжного процесу Python, але використовують функції ШІ, коли ввімкнено певні опції.
|
||
|
||
### Покращення зображення {#image-enhancement}
|
||
|
||
**Маршрут інструмента:** `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-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` | Примусовий квадратний вивід |
|