description:"Dokumentacja silnika AI ze wszystkimi lokalnymi narzędziami ML. Usuwanie tła, powiększanie, OCR, wykrywanie twarzy, renowacja zdjęć i więcej."
Pakiet `@snapotter/ai` koordynuje natywne narzędzia i środowiska wykonawcze Python dla lokalnych operacji ML. Większość narzędzi ML wykorzystuje trwały Python sidecar do szybkiego ciepłego startu. OCR jest celowo oddzielny: `fast` wywołuje natywny plik binarny Tesseract, podczas gdy `balanced` i `best` używają dedykowanego trwałego JSONL dispatcher przypiętego do aktywnej, niezmiennej generacji RapidOCR w ramach `/data/ai/v3`. Każde żądanie zawiera generation lease. Podczas aktualizacji SnapOtter uruchamia smoke test na kandydacie przed aktywacją, atomowo przełącza się na nowy dispatcher, a następnie opróżnia starą generację przed garbage collection.
NVIDIA CUDA jest automatycznie wykrywany i używany przez środowiska wykonawcze, które go obsługują. OCR używa CPU na każdym hoście, w tym na systemach z procesorami graficznymi NVIDIA, unikając łączenia CUDA i sterowników dla tego narzędzia.
Przyspieszenie iGPU Intel/AMD za pośrednictwem VA-API, Quick Sync lub OpenCL nie jest obecnie obsługiwane dla wnioskowania AI. Mapowanie `/dev/dri` do kontenera nie przyspiesza tych narzędzi procesu pomocniczego Pythona, chyba że dostępny jest GPU NVIDIA obsługujący CUDA.
19 narzędzi AI procesu pomocniczego Pythona w czterech modalnościach (obraz, dźwięk, wideo, dokument), plus 2 narzędzia z opcjonalnymi funkcjami AI. Wszystkie modele działają lokalnie - po początkowym pobraniu modeli internet nie jest wymagany.
Szybki OCR obsługuje `auto`, `en`, `de`, `es`, `fr`, `zh` i `ja`, ale nie język koreański (`ko`). Koreański wymaga dokładnego pakietu OCR i `balanced` lub `best`. Pakiet działa w oficjalnych kontenerach Linux amd64 i arm64, także na hostach NVIDIA, gdzie OCR nadal używa CPU. Nieobsługiwany system otrzymuje jawny błąd zgodności i nigdy po cichu nie przechodzi na `fast`. Koreański z `fast` lub starszym aliasem `tesseract` jest odrzucany przed zakolejkowaniem z `FEATURE_INCOMPATIBLE` i `fast-korean-unsupported`.
Oddzielny profil dyspozytora "docs" zastępuje listę dozwolonych AI skryptami do przetwarzania dokumentów (`doc_pagecount`, `doc_health`, `doc_flatten`, `doc_redact`, `doc_text`, `doc_to_word`, `doc_metadata`, `doc_html_pdf`) i pomija ciężkie importy ML.
**Limity czasu:** 300 s domyślnie; OCR i usuwanie tła BiRefNet otrzymują 600 s.
## Pakiety funkcji {#feature-bundles}
Modele AI są pakowane według współdzielonego stosu zależności, a nie jako jedno archiwum na narzędzie. Pakiet funkcji może włączyć kilka narzędzi, gdy używają tej samej rodziny modeli, tych samych pakietów wheel Pythona lub natywnych bibliotek. Utrzymuje to mniejszy rozmiar wydania obrazu Docker i pozwala uniknąć przechowywania zduplikowanych kopii tych samych modeli mattingu tła, wykrywania twarzy, OCR, renowacji i mowy.
Obraz Docker dostarcza aplikację oraz wspólne środowisko uruchomieniowe. Duże archiwa modeli są pobierane na żądanie do trwałego woluminu `/data/ai`, a następnie ponownie wykorzystywane przez każde narzędzie, które ich potrzebuje. Jeśli pakiet jest już zainstalowany, ponieważ inne narzędzie go potrzebowało, włączenie nowego zależnego narzędzia nie powoduje ponownego pobrania tego pakietu.
Większość narzędzi AI wymaga jednego lub więcej pakietów funkcji, zanim będą mogły zostać uruchomione. Interfejs administratora instaluje je za pomocą narzędzia `POST /api/v1/admin/tools/:toolId/features/install`, które rozpoznaje pełną listę pakietów, pomija już zainstalowane pakiety i umieszcza w kolejce tylko brakujące pliki do pobrania. Na przykład włączenie zdjęcia paszportowego w kolejkach świeżych instancji `background-removal` i `face-detection`; włączenie go po usunięciu tła jest już zainstalowanych kolejek tylko `face-detection`. OCR jest wyjątkiem, ponieważ `fast` nie wymaga pakietu; zainstaluj opcjonalne dokładne środowisko wykonawcze za pośrednictwem interfejsu użytkownika lub `POST /api/v1/admin/features/ocr/install`.
| `transcription` | ~600 MB | modele mowy na tekst faster-whisper | transcribe-audio, auto-subtitles |
Narzędzia z zależnościami międzypakietowymi:
| Narzędzie | Wymagane pakiety | Dlaczego |
|------|------------------|-----|
| `passport-photo` | `background-removal`, `face-detection` | Usuwa tło, a następnie używa punktów charakterystycznych twarzy do wykadrowania zgodnie z zasadami zdjęć paszportowych i dowodowych. |
| `enhance-faces` | `upscale-enhance`, `face-detection` | Wykrywa twarze przed uruchomieniem ulepszenia GFPGAN lub CodeFormer na wybranych obszarach twarzy. |
Narzędzie jest dostępne tylko wtedy, gdy zainstalowane są wszystkie wymagane pakiety, z wyjątkiem OCR: jego wbudowana warstwa `fast` pozostaje dostępna bez opcjonalnego pakietu OCR. Instalacje częściowe są ważne i obsługiwane przyrostowo: zainstalowane pakiety są ponownie wykorzystywane, brakujące pakiety są wyświetlane jako pliki do pobrania, a instalacje w kolejce są uruchamiane pojedynczo, więc współdzielone środowisko Python nie jest modyfikowane jednocześnie.
### Dokładna instalacja środowiska wykonawczego OCR {#accurate-ocr-runtime-installation}
Dokładny pakiet OCR to specyficzne dla platformy środowisko uruchomieniowe dla oficjalnego kontenera Linux amd64 lub Linux arm64. Kompilacja amd64 wykorzystuje Python 3.12; kompilacja arm64 wykorzystuje Python 3.11. Obie kompilacje działają od RapidOCR do ONNX Runtime `CPUExecutionProvider`, więc ten sam pakiet działa na hostach wyposażonych tylko w procesor i NVIDIA Docker. Dokładny czas działania wymaga co najmniej 4 GiB efektywnej pamięci: skonfigurowany limit kontenera cgroup, w przeciwnym razie pamięć hosta. System poniżej podpisanego minimum zgodności jest odrzucany przed pobraniem. Wymaganie to nie dotyczy wbudowanego Fast OCR. Kompilacje Bare-metal są odrzucane, ponieważ nie można bezpiecznie wywnioskować ich libc i Python ABI; Szybki OCR pozostaje dostępny, gdy host udostępnia Tesseract i Ghostscript.
Opcjonalny artefakt to około 208-234 skompresowany MiB i wyodrębniony 409-488 MiB, w zależności od architektury. Podpisany indeks wiąże dokładną liczbę skompresowanych i wyodrębnionych bajtów wymuszonych przez instalatora. Wbudowany Tesseract dodaje około 25 MiB do oficjalnego obrazu i nie wymaga żadnych plików w `/data/ai`.
Instalacja online pobiera podpisany indeks wersji i dokładny artefakt adresowany do treści dla bieżącej platformy. SnapOtter weryfikuje sygnaturę indeksu Ed25519, rozmiar artefaktu, podsumowanie SHA-256, podsumowania modelu, ścieżki, tryby plików i etapową smoke test przed atomową aktywacją nowej generacji. Nieudana instalacja pozostawia aktywną poprzednią, zdrową generację.
W przypadku instalacji z przerwą powietrzną prześlij zarówno wersję `ocr-runtime-index.json`, jak i pasujące archiwum wykonawcze OCR do `POST /api/v1/admin/features/import`, używając wieloczęściowych pól o nazwach `index` i `archive`. Import offline stosuje te same kontrole podpisu, skrótu, ekstrakcji, zgodności i testu dymu, co podczas instalacji online; archiwum bez zaufanego podpisanego indeksu jest odrzucane.
| `quality` | `"fast"` \| `"balanced"` \| `"best"` | Dynamiczny | Gdy pominięto `quality` i `engine`, SnapOtter wybiera najlepszy dostępny poziom w kolejności `best`, `balanced`, `fast`. Dla języka koreańskiego nigdy nie wybiera `fast`; używa `best`, następnie `balanced`, albo zwraca błąd instalacji lub zgodności dokładnego środowiska. |
| `enhance` | wartość logiczna | Zależne od poziomu | Popraw lokalny kontrast. Fast stosuje go bezpośrednio; dokładne poziomy utrzymują wariant tylko wtedy, gdy skalibrowana punktacja poprawia OCR. Domyślnie włączone dla Najlepsze |
| `engine` | smyczkowy | - | Przestarzały alias zgodności. Mapuje `tesseract` na `fast` i starszą wartość `paddleocr` na `balanced`; nie ładuje PaddlePaddle |
Zwraca wyodrębniony tekst oraz metadane pochodzenia: silnik, żądaną i rzeczywistą jakość, urządzenie, dostawcę, stan degradacji, ostrzeżenia i dokładne wersje środowiska wykonawczego/modelu, jeśli ma to zastosowanie. Wyraźne żądania jakości nigdy nie przechodzą na inny poziom. Jeżeli `balanced` lub `best` jest niedostępne, API zwraca `FEATURE_NOT_INSTALLED` lub `FEATURE_INCOMPATIBLE` zamiast cichego działania `fast`.
| `quality` | `"fast"` \| `"balanced"` \| `"best"` | Dynamiczny | Gdy pominięto `quality` i `engine`, SnapOtter wybiera najlepszy dostępny poziom w kolejności `best`, `balanced`, `fast`. Dla języka koreańskiego nigdy nie wybiera `fast`; używa `best`, następnie `balanced`, albo zwraca błąd instalacji lub zgodności dokładnego środowiska. |
| `enhance` | wartość logiczna | Zależne od poziomu | Popraw lokalny kontrast. Fast stosuje go bezpośrednio; dokładne poziomy utrzymują wariant tylko wtedy, gdy skalibrowana punktacja poprawia OCR. Domyślnie włączone dla Najlepsze |
| `engine` | smyczkowy | - | Przestarzały alias zgodności. Mapuje `tesseract` na `fast` i starszą wartość `paddleocr` na `balanced`; nie ładuje PaddlePaddle |
Ta sama zasada zakazu zmiany wersji ma zastosowanie do PDF OCR. Strony PDF są rasteryzowane przed rozpoznaniem, a jedno żądanie może wybrać maksymalnie 50 stron.
**Modele:** punkty charakterystyczne twarzy MediaPipe + usuwanie tła BiRefNet
Dwufazowy przepływ pracy: analiza (wykryj twarz + usuń tło), a następnie generowanie (kadrowanie, zmiana rozmiaru, kafelkowanie). Obsługuje ponad 37 krajów w 6 regionach.
### Faza 1: Analiza {#phase-1-analyze}
`POST /api/v1/tools/image/passport-photo/analyze`
Przyjmuje plik obrazu (multipart). Zwraca dane punktów charakterystycznych twarzy, podgląd base64 oraz wymiary obrazu.
| `adjustX` | number | `0` | Korekta położenia w poziomie |
| `adjustY` | number | `0` | Korekta położenia w pionie |
| `landmarks` | object | (wymagane) | Punkty charakterystyczne z Fazy 1 |
| `imageWidth` | number | (wymagane) | Szerokość obrazu z Fazy 1 |
| `imageHeight` | number | (wymagane) | Wysokość obrazu z Fazy 1 |
## Usuwanie obiektów (Inpainting) {#object-erasing-inpainting}
**Trasa narzędzia:**`erase-object`
**Model:** LaMa przez ONNX Runtime
Maska jest wysyłana jako **druga część pliku** (nazwa pola `mask`), a nie jako base64. Białe piksele w masce wskazują obszary do usunięcia. Ustawienia `format` i `quality` są wysyłane jako pola formularza najwyższego poziomu.
Naprawia "fałszywie przezroczyste" pliki PNG, w których tło zostało usunięte, ale pozostawiło obwódki, aureole lub półprzezroczyste artefakty. Używa modelu mattingu wysokiej rozdzielczości BiRefNet, aby uzyskać czysty kanał alfa, a następnie stosuje konfigurowalne przetwarzanie usuwające przebarwienia w celu usunięcia zanieczyszczenia kolorem wzdłuż krawędzi.
**Łańcuch rezerwowy OOM:** Jeśli BiRefNet HR-matting przekroczy dostępną pamięć, narzędzie automatycznie przechodzi na `birefnet-general`, a następnie na `u2net`.
| Parametr | Typ | Domyślnie | Opis |
|-----------|------|---------|-------------|
| `defringe` | number (0-100) | `30` | Siła usuwania obwódek krawędzi w celu usunięcia zanieczyszczenia kolorem |
| `outputFormat` | `"png"` \| `"webp"` | `"png"` | Format obrazu wyjściowego |
## Narzędzia z opcjonalnymi funkcjami AI {#tools-with-optional-ai-capabilities}
Poniższe narzędzia nie są narzędziami procesu pomocniczego Pythona, ale używają funkcji AI, gdy włączone są określone opcje.
### Ulepszanie obrazu {#image-enhancement}
**Trasa narzędzia:**`image-enhancement`
**Silnik:** oparty na analizie (histogram i statystyki Sharp)
Analizuje obraz i stosuje automatyczne korekcje ekspozycji, kontrastu, balansu bieli, nasycenia, ostrości i szumu. Obsługuje tryby dostosowane do sceny.
| Parametr | Typ | Domyślnie | Opis |
|-----------|------|---------|-------------|
| `mode` | `"auto"` \| `"portrait"` \| `"landscape"` \| `"low-light"` \| `"food"` \| `"document"` | `"auto"` | Tryb sceny do dostrajania korekcji |
| `deepEnhance` | boolean | `false` | Włącz usuwanie szumu AI przez SCUNet (wymaga pakietu `upscale-enhance`) |
Dodatkowy punkt końcowy analizy jest dostępny pod `POST /api/v1/tools/image/image-enhancement/analyze`, który zwraca wykryte korekcje bez ich stosowania.
### Zmiana rozmiaru z uwzględnieniem treści (Seam Carving) {#content-aware-resize-seam-carving}
**Trasa narzędzia:**`content-aware-resize`
**Silnik:** binarka Go `caire` (nie Python - brak korzyści z GPU)
Inteligentnie zmienia rozmiar obrazów, usuwając szwy o niskiej energii i zachowując ważną treść.
