Paket `@snapotter/ai` mengoordinasikan alat asli dan waktu proses Python untuk operasi ML lokal. Kebanyakan alat ML menggunakan Python sidecar yang persisten untuk pemanasan cepat. OCR sengaja dipisahkan: `fast` memanggil biner Tesseract asli, sedangkan `balanced` dan `best` menggunakan JSONL dispatcher persisten khusus yang disematkan pada generasi RapidOCR aktif yang tidak dapat diubah di bawah `/data/ai/v3`. Setiap permintaan memiliki generation lease. Selama peningkatan, SnapOtter menjalankan smoke test pada kandidat sebelum aktivasi, secara atom beralih ke dispatcher baru, lalu menguras generasi lama sebelum garbage collection.
NVIDIA CUDA terdeteksi secara otomatis dan digunakan oleh runtime yang mendukungnya. OCR menggunakan CPU di setiap host, termasuk sistem dengan GPU NVIDIA, menghindari CUDA dan kopling driver untuk alat ini.
Akselerasi iGPU Intel/AMD melalui VA-API, Quick Sync, atau OpenCL saat ini tidak didukung untuk inferensi AI. Memetakan `/dev/dri` ke dalam sebuah kontainer tidak mempercepat alat sidecar Python ini kecuali tersedia GPU NVIDIA yang mendukung CUDA.
19 alat AI sidecar Python di empat modalitas (gambar, audio, video, dokumen), plus 2 alat dengan kemampuan AI opsional. Semua model berjalan secara lokal - tidak diperlukan internet setelah unduhan model awal.
OCR Cepat mendukung `auto`, `en`, `de`, `es`, `fr`, `zh`, dan `ja`, tetapi tidak mendukung bahasa Korea (`ko`). Bahasa Korea memerlukan paket OCR Akurat dan `balanced` atau `best`. Paket berjalan pada kontainer resmi Linux amd64 dan arm64, termasuk host NVIDIA dengan OCR tetap memakai CPU. Sistem yang tidak didukung menerima kesalahan kompatibilitas yang jelas dan tidak pernah diam-diam kembali ke `fast`. Bahasa Korea dengan `fast` atau alias lama `tesseract` ditolak sebelum antre dengan `FEATURE_INCOMPATIBLE` dan `fast-korean-unsupported`.
Profil dispatcher "docs" yang terpisah menggantikan allowlist AI dengan skrip pemrosesan dokumen (`doc_pagecount`, `doc_health`, `doc_flatten`, `doc_redact`, `doc_text`, `doc_to_word`, `doc_metadata`, `doc_html_pdf`) dan melewati impor ML yang berat.
**Timeout:** 300 d default; OCR dan penghapusan latar belakang BiRefNet mendapat 600 d.
## Bundel Fitur {#feature-bundles}
Model AI dikemas berdasarkan tumpukan dependensi bersama, bukan satu arsip per alat. Sebuah bundel fitur dapat mengaktifkan beberapa alat saat mereka memakai keluarga model, wheel Python, atau pustaka native yang sama. Ini menjaga image Docker rilis tetap lebih kecil dan menghindari penyimpanan salinan duplikat dari model matting latar belakang, deteksi wajah, OCR, restorasi, dan model bicara yang sama.
Image Docker mengirimkan aplikasi ditambah runtime umum. Arsip model besar diunduh sesuai permintaan ke dalam volume `/data/ai` persisten, lalu dipakai ulang oleh setiap alat yang membutuhkannya. Jika sebuah bundel sudah terpasang karena alat lain memerlukannya, mengaktifkan alat dependen baru tidak mengunduh bundel itu lagi.
Sebagian besar alat AI memerlukan satu atau lebih paket fitur sebelum dapat dijalankan. UI admin menginstalnya dengan alat melalui `POST /api/v1/admin/tools/:toolId/features/install`, yang menyelesaikan daftar bundel lengkap, melewati bundel yang sudah diinstal, dan hanya mengantri unduhan yang hilang. Misalnya, mengaktifkan Foto Paspor pada antrian instans baru `background-removal` dan `face-detection`; mengaktifkannya setelah Penghapusan Latar Belakang sudah diinstal antrian hanya `face-detection`. OCR adalah pengecualian karena `fast` tidak memerlukan paket; instal runtime akurat opsionalnya melalui UI atau `POST /api/v1/admin/features/ocr/install`.
| `passport-photo` | `background-removal`, `face-detection` | Menghapus latar belakang, lalu memakai landmark wajah untuk membingkai crop sesuai aturan foto paspor dan KTP. |
| `enhance-faces` | `upscale-enhance`, `face-detection` | Mendeteksi wajah sebelum menjalankan peningkatan GFPGAN atau CodeFormer pada wilayah wajah yang dipilih. |
Alat hanya tersedia ketika semua bundel yang diperlukan telah diinstal, kecuali OCR: tingkat `fast` bawaannya tetap tersedia tanpa paket OCR opsional. Penginstalan sebagian valid dan ditangani secara bertahap: bundel yang terinstal digunakan kembali, bundel yang hilang ditampilkan sebagai unduhan, dan antrean penginstalan dijalankan satu per satu sehingga lingkungan Python yang dibagikan tidak diubah secara bersamaan.
### Instalasi runtime OCR {#accurate-ocr-runtime-installation} yang akurat
Paket OCR yang akurat adalah runtime khusus platform untuk kontainer resmi Linux amd64 atau Linux arm64. Versi amd64 menggunakan Python 3.12; build arm64 menggunakan Python 3.11. Kedua build menjalankan RapidOCR melalui `CPUExecutionProvider` ONNX Runtime, sehingga paket yang sama hanya berfungsi pada CPU dan host NVIDIA Docker. Runtime yang akurat memerlukan setidaknya 4 GiB memori efektif: batas cgroup kontainer yang dikonfigurasi, jika tidak, memori host. Sistem di bawah minimum kompatibilitas yang ditandatangani akan ditolak sebelum diunduh. Persyaratan ini tidak berlaku untuk Fast OCR bawaan. Build Bare-metal ditolak karena libc dan Python ABI tidak dapat disimpulkan dengan aman; OCR cepat tetap tersedia ketika host menyediakan Tesseract dan Ghostscript.
Artefak opsional adalah sekitar 208-234 MiB yang dikompresi dan 409-488 MiB yang diekstraksi, bergantung pada arsitektur. Indeks yang ditandatangani mengikat jumlah byte yang dikompresi dan diekstraksi secara tepat yang diterapkan oleh penginstal. Tesseract bawaan menambahkan sekitar 25 MiB ke gambar resmi dan tidak memerlukan file di `/data/ai`.
Instalasi online mengambil indeks rilis yang ditandatangani dan artefak alamat konten yang tepat untuk platform saat ini. SnapOtter memverifikasi tanda tangan indeks Ed25519, ukuran artefak, intisari SHA-256, intisari model, jalur, mode file, dan smoke test yang dipentaskan sebelum mengaktifkan generasi baru secara atom. Penginstalan yang gagal membuat generasi sehat sebelumnya tetap aktif.
Untuk instalasi dengan celah udara, unggah `ocr-runtime-index.json` rilis dan arsip runtime OCR yang cocok ke `POST /api/v1/admin/features/import` menggunakan bidang multibagian bernama `index` dan `archive`. Impor offline menerapkan pemeriksaan tanda tangan, hash, ekstraksi, kompatibilitas, dan uji asap yang sama seperti instalasi online; arsip tanpa indeks bertanda tangan tepercaya ditolak.
| `quality` | `"fast"` \| `"balanced"` \| `"best"` | Dinamis | Jika `quality` dan `engine` tidak diberikan, SnapOtter memilih tingkat terbaik yang tersedia dengan urutan `best`, `balanced`, lalu `fast`. Untuk bahasa Korea, `fast` tidak pernah dipilih; sistem memakai `best`, lalu `balanced`, atau mengembalikan kesalahan instalasi maupun kompatibilitas runtime akurat. |
| `enhance` | boolean | Bergantung pada tingkatan | Tingkatkan kontras lokal. Fast menerapkannya secara langsung; tingkatan akurat mempertahankan varian hanya ketika skor yang dikalibrasi meningkatkan OCR. Defaultnya aktif untuk yang Terbaik |
| `engine` | rangkaian | - | Alias kompatibilitas yang tidak digunakan lagi. Memetakan `tesseract` ke `fast` dan nilai `paddleocr` lama ke `balanced`; itu tidak memuat PaddlePaddle |
Mengembalikan teks yang diekstraksi ditambah metadata asal: mesin, kualitas yang diminta dan aktual, perangkat, penyedia, status degradasi, peringatan, dan versi runtime/model yang akurat bila berlaku. Permintaan kualitas eksplisit tidak pernah kembali ke tingkat lain. Jika `balanced` atau `best` tidak tersedia, API mengembalikan `FEATURE_NOT_INSTALLED` atau `FEATURE_INCOMPATIBLE` alih-alih menjalankan `fast` secara diam-diam.
| `quality` | `"fast"` \| `"balanced"` \| `"best"` | Dinamis | Jika `quality` dan `engine` tidak diberikan, SnapOtter memilih tingkat terbaik yang tersedia dengan urutan `best`, `balanced`, lalu `fast`. Untuk bahasa Korea, `fast` tidak pernah dipilih; sistem memakai `best`, lalu `balanced`, atau mengembalikan kesalahan instalasi maupun kompatibilitas runtime akurat. |
| `enhance` | boolean | Bergantung pada tingkatan | Tingkatkan kontras lokal. Fast menerapkannya secara langsung; tingkatan akurat mempertahankan varian hanya ketika skor yang dikalibrasi meningkatkan OCR. Defaultnya aktif untuk yang Terbaik |
| `engine` | rangkaian | - | Alias kompatibilitas yang tidak digunakan lagi. Memetakan `tesseract` ke `fast` dan nilai `paddleocr` lama ke `balanced`; itu tidak memuat PaddlePaddle |
Aturan larangan penurunan versi yang sama juga berlaku untuk PDF OCR. Halaman PDF diraster sebelum dikenali, dan satu permintaan dapat memilih maksimal 50 halaman.
Mask dikirim sebagai **bagian berkas kedua** (fieldname `mask`), bukan sebagai base64. Piksel putih dalam mask menandai area yang akan dihapus. Pengaturan `format` dan `quality` dikirim sebagai field form tingkat atas.
| Parameter | Tipe | Default | Deskripsi |
|-----------|------|---------|-------------|
| `file` | file | (wajib) | Gambar sumber (multipart) |
| `mask` | file | (wajib) | Gambar mask (multipart, fieldname `mask`, putih = hapus) |
Memperbaiki PNG "transparan palsu" di mana latar belakang telah dihapus tetapi meninggalkan fringing, halo, atau artefak semi-transparan. Menggunakan model matting resolusi tinggi BiRefNet untuk menghasilkan kanal alpha yang bersih, lalu menerapkan pemrosesan defringe yang dapat dikonfigurasi untuk menghilangkan kontaminasi warna di sepanjang tepi.
**Rantai fallback OOM:** Jika BiRefNet HR-matting melampaui memori yang tersedia, alat secara otomatis beralih ke `birefnet-general`, lalu ke `u2net`.
| Parameter | Tipe | Default | Deskripsi |
|-----------|------|---------|-------------|
| `defringe` | number (0-100) | `30` | Kekuatan defringe tepi untuk menghilangkan kontaminasi warna |
| `outputFormat` | `"png"` \| `"webp"` | `"png"` | Format gambar keluaran |
## Alat dengan Kemampuan AI Opsional {#tools-with-optional-ai-capabilities}
Alat berikut bukan alat sidecar Python tetapi memakai fitur AI saat opsi tertentu diaktifkan.
### Peningkatan Gambar {#image-enhancement}
**Rute alat:**`image-enhancement`
**Mesin:** Berbasis analisis (histogram dan statistik Sharp)
Menganalisis gambar dan menerapkan koreksi otomatis untuk eksposur, kontras, white balance, saturasi, ketajaman, dan derau. Mendukung mode spesifik-adegan.
| `deepEnhance` | boolean | `false` | Aktifkan penghapusan derau AI via SCUNet (memerlukan bundel `upscale-enhance`) |
Endpoint analisis tambahan tersedia di `POST /api/v1/tools/image/image-enhancement/analyze` yang mengembalikan koreksi yang terdeteksi tanpa menerapkannya.
### Ubah Ukuran Sadar-Konten (Seam Carving) {#content-aware-resize-seam-carving}
**Rute alat:**`content-aware-resize`
**Mesin:** biner Go `caire` (bukan Python - tidak ada manfaat GPU)
Mengubah ukuran gambar secara cerdas dengan menghapus seam berenergi rendah, mempertahankan konten penting.
| Parameter | Tipe | Default | Deskripsi |
|-----------|------|---------|-------------|
| `width` | number | - | Lebar target |
| `height` | number | - | Tinggi target |
| `protectFaces` | boolean | `false` | Lindungi wilayah wajah yang terdeteksi (memerlukan bundel `face-detection`) |
| `blurRadius` | number (0-20) | `4` | Pra-blur untuk perhitungan energi |
| `sobelThreshold` | number (1-20) | `2` | Ambang sensitivitas tepi |
