description:"Довідник рушія ШІ з усіма локальними інструментами ML. Видалення фону, збільшення роздільної здатності, OCR, розпізнавання облич, реставрація фото та інше."
Пакет `@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 інструменти з необов'язковими можливостями ШІ. Усі моделі працюють локально: після початкового завантаження моделі інтернет не потрібен.
Швидкий 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`.
Окремий профіль диспетчера «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`.
| `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`. Офлайн-імпорт використовує ті самі перевірки підпису, хешу, вилучення, сумісності та димового тесту, що й онлайн-інсталяція; архів без довіреного підписаного індексу відхилено.
| `quality` | `"fast"` \| `"balanced"` \| `"best"` | Динамічний | Якщо `quality`і`engine` не задано, SnapOtter вибирає найкращий доступний рівень у порядку `best`, `balanced`, `fast`. Для корейської мови `fast` ніколи не вибирається: використовується `best`, потім `balanced`, або повертається помилка встановлення чи сумісності точного середовища виконання. |
| `enhance` | логічний | Залежно від рівня | Поліпшення локального контрасту. Fast застосовує його безпосередньо; точні рівні зберігають варіант лише тоді, коли калібрована оцінка покращує OCR. За замовчуванням для найкращого |
| `engine` | рядок | - | Застарілий псевдонім сумісності. Зіставляє `tesseract` на `fast` і застаріле значення `paddleocr` на `balanced`; він не завантажує PaddlePaddle |
Повертає витягнутий текст, а також метадані про походження: механізм, запитану та фактичну якість, пристрій, постачальника, стан деградації, попередження та точні версії часу виконання/моделі, якщо це можливо. Явні запити щодо якості ніколи не повертаються до іншого рівня. Якщо `balanced` або `best` недоступні, API повертає `FEATURE_NOT_INSTALLED` або `FEATURE_INCOMPATIBLE` замість тихого запуску `fast`.
| `quality` | `"fast"` \| `"balanced"` \| `"best"` | Динамічний | Якщо `quality`і`engine` не задано, SnapOtter вибирає найкращий доступний рівень у порядку `best`, `balanced`, `fast`. Для корейської мови `fast` ніколи не вибирається: використовується `best`, потім `balanced`, або повертається помилка встановлення чи сумісності точного середовища виконання. |
| `enhance` | логічний | Залежно від рівня | Поліпшення локального контрасту. Fast застосовує його безпосередньо; точні рівні зберігають варіант лише тоді, коли калібрована оцінка покращує OCR. За замовчуванням для найкращого |
| `engine` | рядок | - | Застарілий псевдонім сумісності. Зіставляє `tesseract` на `fast` і застаріле значення `paddleocr` на `balanced`; він не завантажує PaddlePaddle |
Таке ж правило заборони на пониження версії застосовується до PDF OCR. Сторінки PDF растеризуються перед розпізнаванням, і один запит може вибрати не більше 50 сторінок.
| `quality` | number (1-100) | `90` | Якість виводу |
## Реставрація фото {#photo-restoration}
**Маршрут інструмента:**`restore-photo`
Багатоетапний конвеєр для старих або пошкоджених фото: розпізнавання й ремонт подряпин/розривів, покращення облич, шумозаглушення та необов'язкова колоризація.
Двофазний робочий процес: аналіз (розпізнати обличчя + видалити фон), потім генерація (кроп, зміна розміру, розкладка). Підтримує 37+ країн у 6 регіонах.
### Фаза 1: Аналіз {#phase-1-analyze}
`POST /api/v1/tools/image/passport-photo/analyze`
Приймає файл зображення (multipart). Повертає дані орієнтирів обличчя, попередній перегляд у base64 та розміри зображення.
| `imageWidth` | number | (обов'язково) | Ширина зображення з Фази 1 |
| `imageHeight` | number | (обов'язково) | Висота зображення з Фази 1 |
## Стирання об'єктів (Inpainting) {#object-erasing-inpainting}
**Маршрут інструмента:**`erase-object`
**Модель:** LaMa через ONNX Runtime
Маска надсилається як **друга частина файлу** (ім'я поля `mask`), а не як base64. Білі пікселі в масці позначають області для стирання. Налаштування `format` та `quality` надсилаються як поля форми верхнього рівня.
**Модель:** матування HR BiRefNet (роздільна здатність 2048x2048)
Виправляє «псевдопрозорі» PNG, де фон було видалено, але залишилися облямівка, ореоли чи напівпрозорі артефакти. Використовує модель матування високої роздільної здатності BiRefNet для створення чистого альфа-каналу, а потім застосовує налаштовувану обробку прибирання облямівки, щоб усунути колірне забруднення вздовж країв.
**Ланцюг резервів OOM:** Якщо матування HR BiRefNet перевищує доступну пам'ять, інструмент автоматично переходить на `birefnet-general`, а потім на `u2net`.
| Параметр | Тип | За замовчуванням | Опис |
|-----------|------|---------|-------------|
| `defringe` | number (0-100) | `30` | Сила прибирання облямівки країв для усунення колірного забруднення |
## Інструменти з необов'язковими можливостями ШІ {#tools-with-optional-ai-capabilities}
Наведені нижче інструменти не є інструментами допоміжного процесу Python, але використовують функції ШІ, коли ввімкнено певні опції.
### Покращення зображення {#image-enhancement}
**Маршрут інструмента:**`image-enhancement`
**Рушій:** на основі аналізу (гістограма та статистика Sharp)
Аналізує зображення та застосовує автоматичні корекції експозиції, контрасту, балансу білого, насиченості, різкості та шуму. Підтримує режими для конкретних сцен.
Додатковий кінцевий пункт аналізу доступний за `POST /api/v1/tools/image/image-enhancement/analyze`, який повертає виявлені корекції без їх застосування.
### Зміна розміру з урахуванням вмісту (Seam Carving) {#content-aware-resize-seam-carving}
**Маршрут інструмента:**`content-aware-resize`
**Рушій:** бінарник Go `caire` (не Python: без вигоди від GPU)
Розумно змінює розмір зображень, видаляючи низькоенергетичні шви та зберігаючи важливий вміст.
