Files
SnapOtter/apps/docs/pl/api/ai.md
T
SnapOtterandGitHub 4963ab3bbd feat(docs-i18n): translate all documentation into 20 languages
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.
2026-07-11 13:52:47 +08:00

23 KiB

description, i18n_source_hash, i18n_provenance, i18n_output_hash
description i18n_source_hash i18n_provenance i18n_output_hash
Dokumentacja silnika AI ze wszystkimi lokalnymi narzędziami ML. Usuwanie tła, powiększanie, OCR, wykrywanie twarzy, renowacja zdjęć i więcej. 14728c1dcd05 machine d38bde507e84

Dokumentacja silnika AI

Pakiet @snapotter/ai łączy Node.js z trwałym procesem pomocniczym Pythona (sidecar) dla wszystkich operacji ML. Proces dyspozytora pozostaje aktywny między żądaniami, co zapewnia szybkie działanie z rozgrzanego startu. NVIDIA CUDA jest automatycznie wykrywana przy uruchomieniu i używana, gdy jest dostępna; w przeciwnym razie narzędzia AI działają na CPU.

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.

Architektura

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)

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

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.

Każde narzędzie AI wymaga jednego lub więcej pakietów funkcji, zanim będzie mogło działać. Interfejs administratora instaluje według narzędzia poprzez POST /api/v1/admin/tools/:toolId/features/install, które rozwiązuje pełną listę pakietów, pomija pakiety już zainstalowane i kolejkuje tylko brakujące pobrania. Na przykład włączenie Zdjęcia paszportowego na świeżej instancji kolejkuje background-removal i face-detection; włączenie go po zainstalowaniu już Usuwania tła kolejkuje tylko face-detection.

Pakiet Rozmiar Współdzielona grupa zależności Narzędzia, które go używają
background-removal 4-5 GB matting tła rembg / BiRefNet remove-background, passport-photo, transparency-fixer, background-replace, blur-background
face-detection 200-300 MB wykrywanie twarzy i punktów charakterystycznych MediaPipe blur-faces, red-eye-removal, smart-crop
object-eraser-colorize 1-2 GB inpainting/outpainting LaMa oraz DDColor erase-object, colorize, ai-canvas-expand
upscale-enhance 5-6 GB RealESRGAN, GFPGAN / CodeFormer, odszumianie upscale, enhance-faces, noise-removal
photo-restoration 4-5 GB naprawa rys i potok renowacji restore-photo
ocr 5-6 GB stos OCR PaddleOCR / Tesseract ocr, ocr-pdf
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 jego wymagane pakiety. Częściowe instalacje są prawidłowe i obsługiwane przyrostowo: zainstalowane pakiety są ponownie wykorzystywane, brakujące pakiety są pokazywane jako pobrania, a zakolejkowane instalacje uruchamiają się pojedynczo, aby współdzielone środowisko Pythona nie było modyfikowane równocześnie.


Usuwanie tła

Trasa narzędzia: remove-background
Model: rembg z BiRefNet (domyślnie) lub warianty U2-Net

Parametr Typ Domyślnie Opis
model string - Wariant modelu (opcjonalne nadpisanie)
backgroundType string "transparent" Jeden z: transparent, color, gradient, blur, image
backgroundColor string - Kolor hex dla jednolitego tła
gradientColor1 string - Pierwszy kolor gradientu
gradientColor2 string - Drugi kolor gradientu
gradientAngle number - Kąt gradientu w stopniach
blurEnabled boolean - Włącz efekt rozmycia tła
blurIntensity number (0-100) - Intensywność rozmycia
shadowEnabled boolean - Włącz cień pod obiektem
shadowOpacity number (0-100) - Krycie cienia
outputFormat string - Format wyjściowy: png, webp lub avif
edgeRefine integer (0-3) - Poziom wygładzania krawędzi
decontaminate boolean - Usuń przenikanie koloru z krawędzi

Zamiana tła

Trasa narzędzia: background-replace
Model: rembg / BiRefNet (współdzielony z remove-background)

Usuwa tło i zastępuje je jednolitym kolorem lub gradientem.

Parametr Typ Domyślnie Opis
backgroundType "color" | "gradient" "color" Tryb tła
color string "#ffffff" Kolor hex tła (gdy backgroundType to color)
gradientColor1 string - Pierwszy kolor hex gradientu
gradientColor2 string - Drugi kolor hex gradientu
gradientAngle integer (0-360) 180 Kąt gradientu w stopniach
feather integer (0-20) 0 Promień wtapiania krawędzi
format "png" | "webp" "png" Format wyjściowy

Rozmycie tła

Trasa narzędzia: blur-background
Model: rembg / BiRefNet (współdzielony z remove-background)

Rozmywa tło, zachowując ostrość obiektu.

Parametr Typ Domyślnie Opis
intensity integer (1-100) 50 Intensywność rozmycia
feather integer (0-20) 0 Promień wtapiania krawędzi
format "png" | "webp" "png" Format wyjściowy

Powiększanie obrazu

Trasa narzędzia: upscale
Model: RealESRGAN (z rezerwowym Lanczos, gdy niedostępny)

Parametr Typ Domyślnie Opis
scale number 2 Współczynnik powiększenia
model string "auto" Wariant modelu
faceEnhance boolean false Zastosuj przebieg ulepszania twarzy GFPGAN
denoise number 0 Siła odszumiania
format string "auto" Nadpisanie formatu wyjściowego
quality number 95 Jakość wyjściowa (1-100)

OCR / Wyodrębnianie tekstu

Trasa narzędzia: ocr
Modele: Tesseract (szybki), PaddleOCR PP-OCRv5 (zrównoważony), PaddleOCR-VL 1.5 (najlepszy)

Parametr Typ Domyślnie Opis
quality "fast" | "balanced" | "best" "balanced" Poziom przetwarzania
language string "auto" Język: auto, en, de, fr, es, zh, ja, ko
enhance boolean true Wstępnie przetwórz obraz, aby poprawić dokładność OCR
engine string - Przestarzałe. Mapuje tesseract na fast, paddleocr na balanced

Zwraca uporządkowane wyniki z ramkami ograniczającymi, wynikami pewności i wyodrębnionymi blokami tekstu.

OCR PDF

Trasa narzędzia: ocr-pdf
Modele: Ten sam system poziomów co OCR obrazu

Wyodrębnia tekst ze skanowanych dokumentów PDF przy użyciu OCR wspieranego przez AI, strona po stronie.

Parametr Typ Domyślnie Opis
quality "fast" | "balanced" | "best" "balanced" Poziom przetwarzania
language string "auto" Język: auto, en, de, fr, es, zh, ja, ko
pages string "all" Wybór stron: "all", "1-3", "1,3,5"

Rozmycie twarzy / danych osobowych

Trasa narzędzia: blur-faces
Model: wykrywanie twarzy MediaPipe

Parametr Typ Domyślnie Opis
blurRadius number (1-100) 30 Promień rozmycia gaussowskiego
sensitivity number (0-1) 0.5 Próg pewności wykrywania

Ulepszanie twarzy

Trasa narzędzia: enhance-faces
Modele: GFPGAN, CodeFormer

Parametr Typ Domyślnie Opis
model "auto" | "gfpgan" | "codeformer" "auto" Model ulepszania
strength number (0-1) 0.8 Siła ulepszania
sensitivity number (0-1) 0.5 Próg wykrywania twarzy
onlyCenterFace boolean false Ulepsz tylko najbardziej centralną twarz

Koloryzacja AI

Trasa narzędzia: colorize
Model: DDColor (z rezerwowym OpenCV DNN)

Przekształca zdjęcia czarno-białe lub w skali szarości na pełny kolor.

Parametr Typ Domyślnie Opis
intensity number (0-1) 1.0 Siła nasycenia kolorów
model "auto" | "ddcolor" | "opencv" "auto" Wariant modelu

Usuwanie szumu

Trasa narzędzia: noise-removal
Model: SCUNet (wielopoziomowy potok odszumiania)

Parametr Typ Domyślnie Opis
tier "quick" | "balanced" | "quality" | "maximum" "balanced" Poziom przetwarzania
strength number (0-100) 50 Siła odszumiania
detailPreservation number (0-100) 50 Ile detali zachować; wyższa wartość zachowuje więcej tekstury
colorNoise number (0-100) 30 Siła redukcji szumu kolorów
format string "original" Format wyjściowy: original, png, jpeg, webp, avif, jxl
quality number (1-100) 90 Jakość kodowania wyjścia

Usuwanie czerwonych oczu

Trasa narzędzia: red-eye-removal

Wykrywa punkty charakterystyczne twarzy, lokalizuje obszary oczu i koryguje nadmierne nasycenie kanału czerwonego.

Parametr Typ Domyślnie Opis
sensitivity number (0-100) 50 Próg wykrywania czerwonych pikseli
strength number (0-100) 70 Siła korekcji
format string - Nadpisanie formatu wyjściowego (opcjonalne)
quality number (1-100) 90 Jakość wyjściowa

Renowacja zdjęć

Trasa narzędzia: restore-photo

Wieloetapowy potok dla starych lub uszkodzonych zdjęć: wykrywanie i naprawa rys/rozdarć, ulepszanie twarzy, odszumianie oraz opcjonalna koloryzacja.

Parametr Typ Domyślnie Opis
scratchRemoval boolean true Wykryj i napraw rysy, rozdarcia
faceEnhancement boolean true Zastosuj przebieg ulepszania twarzy
fidelity number (0-1) 0.7 Siła ulepszania twarzy (wyższa = bardziej zachowawcza)
denoise boolean true Zastosuj przebieg odszumiania
denoiseStrength number (0-100) 25 Siła odszumiania
colorize boolean false Koloryzuj po renowacji
colorizeStrength number (0-100) 85 Intensywność koloryzacji

Zdjęcie paszportowe

Trasa narzędzia: passport-photo
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

POST /api/v1/tools/image/passport-photo/analyze

Przyjmuje plik obrazu (multipart). Zwraca dane punktów charakterystycznych twarzy, podgląd base64 oraz wymiary obrazu.

Faza 2: Generowanie

POST /api/v1/tools/image/passport-photo/generate

Przyjmuje treść JSON z wynikami Fazy 1 oraz ustawieniami generowania:

Parametr Typ Domyślnie Opis
jobId string (wymagane) Identyfikator zadania z Fazy 1
filename string (wymagane) Oryginalna nazwa pliku z Fazy 1
countryCode string (wymagane) Kod kraju ISO (np. US, GB, IN)
documentType string "passport" Typ dokumentu
bgColor string "#FFFFFF" Kolor tła hex
printLayout string "none" Układ wydruku: none, 4x6, a4, letter
maxFileSizeKb number 0 Maksymalny rozmiar pliku w KB (0 = brak limitu)
dpi number (72-1200) 300 DPI wyjścia
customWidthMm number - Niestandardowa szerokość w mm (nadpisuje specyfikację kraju)
customHeightMm number - Niestandardowa wysokość w mm (nadpisuje specyfikację kraju)
zoom number (0.5-3) 1 Współczynnik przybliżenia
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)

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.

Parametr Typ Domyślnie Opis
file file (wymagane) Obraz źródłowy (multipart)
mask file (wymagane) Obraz maski (multipart, nazwa pola mask, biały = usuń)
format string "auto" Format wyjściowy: auto, png, jpg, jpeg, webp, tiff, gif, avif, heic, heif, jxl
quality integer (1-100) 95 Jakość wyjściowa

Przyspieszane przez CUDA, gdy dostępny jest GPU NVIDIA.

Rozszerzanie kadru AI

Trasa narzędzia: ai-canvas-expand
Model: outpainting oparty na LaMa

Rozszerza kadr obrazu w dowolnym kierunku i wypełnia nowe obszary treścią wygenerowaną przez AI, która pasuje do istniejącego obrazu.

Parametr Typ Domyślnie Opis
extendTop integer 0 Piksele do rozszerzenia u góry
extendRight integer 0 Piksele do rozszerzenia po prawej
extendBottom integer 0 Piksele do rozszerzenia u dołu
extendLeft integer 0 Piksele do rozszerzenia po lewej
tier "fast" | "balanced" | "high" "balanced" Poziom jakości
format string "auto" Format wyjściowy: auto, png, jpg, jpeg, webp, tiff, gif, avif, heic, heif, jxl
quality integer (1-100) 95 Jakość wyjściowa

Co najmniej jeden kierunek rozszerzenia musi być większy niż 0.

Inteligentne kadrowanie

Trasa narzędzia: smart-crop
Model: wykrywanie twarzy MediaPipe (tylko tryb twarzy)

Parametr Typ Domyślnie Opis
mode string "subject" Strategia kadrowania: subject, face, trim
strategy "attention" | "entropy" "attention" Strategia dla trybu obiektu
width integer - Szerokość wyjścia
height integer - Wysokość wyjścia
padding integer (0-50) 0 Procent marginesu wokół obiektu
facePreset string "head-shoulders" Predefiniowane kadrowanie, gdy mode=face
sensitivity number (0-1) 0.5 Próg wykrywania twarzy
threshold integer (0-255) 30 Próg wykrywania tła (tryb przycinania)
padToSquare boolean false Dopełnij przycięty wynik do kwadratu
padColor string "#ffffff" Kolor tła dla dopełnienia kwadratowego
targetSize integer - Docelowy rozmiar dla dopełnionego wyjścia (piksele)
quality integer (1-100) - Jakość wyjściowa

Starsze wartości mode attention i content są akceptowane i mapowane odpowiednio na subject i trim.

Predefiniowane ustawienia twarzy:

Predefiniowane Najlepsze do
closeup Zdjęcia portretowe
head-shoulders Zdjęcia profilowe
upper-body LinkedIn / formalne
half-body Pełna górna część ciała

Transkrypcja dźwięku

Trasa narzędzia: transcribe-audio
Model: faster-whisper

Przekształca mowę na tekst. Obsługuje formaty wyjściowe zwykły tekst, SRT i VTT.

Parametr Typ Domyślnie Opis
language string "auto" Język: auto, en, de, fr, es, zh, ja, ko, id, th, vi
outputFormat "txt" | "srt" | "vtt" "txt" Format wyjściowy

Automatyczne napisy

Trasa narzędzia: auto-subtitles
Model: faster-whisper (wyodrębnia dźwięk z wideo, a następnie transkrybuje)

Generuje pliki napisów ze ścieżki dźwiękowej wideo.

Parametr Typ Domyślnie Opis
language string "auto" Język: auto, en, de, fr, es, zh, ja, ko, id, th, vi
format "srt" | "vtt" "srt" Format wyjściowy napisów

Naprawa przezroczystości PNG

Trasa narzędzia: transparency-fixer
Model: BiRefNet HR-matting (rozdzielczość 2048x2048)

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
removeWatermark boolean false Zastosuj wstępne przetwarzanie usuwania znaku wodnego (filtr medianowy)
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"}'

Narzędzia z opcjonalnymi funkcjami AI

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

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
intensity number (0-100) 50 Ogólna siła korekcji
corrections.exposure boolean true Zastosuj korekcję ekspozycji
corrections.contrast boolean true Zastosuj korekcję kontrastu
corrections.whiteBalance boolean true Zastosuj korekcję balansu bieli
corrections.saturation boolean true Zastosuj korekcję nasycenia
corrections.sharpness boolean true Zastosuj korekcję ostrości
corrections.denoise boolean true Zastosuj odszumianie
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)

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ść.

Parametr Typ Domyślnie Opis
width number - Docelowa szerokość
height number - Docelowa wysokość
protectFaces boolean false Chroń wykryte obszary twarzy (wymaga pakietu face-detection)
blurRadius number (0-20) 4 Wstępne rozmycie do obliczania energii
sobelThreshold number (1-20) 2 Próg czułości krawędzi
square boolean false Wymuś kwadratowe wyjście