External/SnapOtter
1
0
Fork 0
mirror of https://github.com/snapotter-hq/SnapOtter.git synced 2026-08-03 07:46:42 +02:00
Code Issues Packages Projects Releases Wiki Activity

fix: make OCR portable and reliable across AMD64 and ARM64 (#519)

Browse Source 
* 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
This commit is contained in:
SnapOtter
2026-07-15 03:34:24 +08:00
committed by GitHub
parent 58121f205f
commit 991c981529
409 changed files with 67151 additions and 8076 deletions
Download Patch File Download Diff File Expand all files Collapse all files
apps/docs/id/guide/architecture.md
+6 -6
View File
@@ -1,8 +1,8 @@
---
description: "Struktur monorepo, arsitektur aplikasi dan paket, siklus hidup permintaan, dan jejak sumber daya SnapOtter."
i18n_source_hash: 9e8f80499a37
i18n_provenance: human
i18n_output_hash: d4bd8ceef301
i18n_source_hash: 733cb3c10884
i18n_provenance: human
---
# Arsitektur {#architecture}
@@ -36,13 +36,13 @@ Paket ini tidak memiliki dependensi jaringan dan berjalan sepenuhnya dalam prose
### `@snapotter/ai` {#snapotter-ai}
Lapisan penghubung yang memanggil skrip Python untuk operasi ML. Pada penggunaan pertama, penghubung memulai proses dispatcher Python yang persisten yang mengimpor terlebih dahulu pustaka berat (PIL, NumPy, MediaPipe, rembg) sehingga panggilan AI berikutnya melewati overhead impor. Jika dispatcher belum siap, penghubung mundur ke pemunculan subproses Python baru per permintaan.
Lapisan jembatan yang memanggil runtime asli dan Python ML. Sebagian besar alat Python menggunakan dispatcher persisten yang melakukan pra-impor pustaka berat (PIL, NumPy, MediaPipe, rembg) sehingga panggilan berikutnya melewati overhead impor. OCR diisolasi dari lingkungan bersama yang dapat diubah: `fast` memanggil Tesseract asli, sementara `balanced` dan `best` menggunakan JSONL dispatcher persisten khusus yang disematkan pada generasi RapidOCR/ONNX aktif yang tidak dapat diubah. Setiap permintaan memiliki generation lease. Aktivasi pertama-tama menjalankan smoke test pada kandidat, kemudian beralih secara atom ke dispatcher-nya. Saluran air dispatcher sebelumnya sebelum pembangkitannya dikumpulkan sampahnya.
**Model tidak dimuat terlebih dahulu.** Setiap skrip tool memuat bobot modelnya dari disk pada waktu permintaan dan membuangnya saat permintaan selesai. Lihat [Jejak sumber daya](#resource-footprint) untuk profil memori lengkap.
Operasi yang didukung: penghapusan latar belakang (rembg/BiRefNet), upscaling (RealESRGAN), blur wajah (MediaPipe), penyempurnaan wajah (GFPGAN/CodeFormer), penghapusan objek (LaMa ONNX), OCR (PaddleOCR/Tesseract), pewarnaan (DDColor), penghapusan derau, penghapusan mata merah, restorasi foto, pembuatan foto paspor, pemperbaiki transparansi (matting HR BiRefNet), dan pengubahan ukuran sadar-konten (biner Go caire).
Operasi yang didukung: penghapusan latar belakang (rembg/BiRefNet), peningkatan (RealESRGAN), keburaman wajah (MediaPipe), penyempurnaan wajah (GFPGAN/CodeFormer), penghapusan objek (LaMa ONNX), OCR (Tesseract dan RapidOCR dengan model PP-OCR ONNX), pewarnaan (DDColor), penghilangan noise, penghilangan mata merah, restorasi foto, pembuatan foto paspor, perbaikan transparansi (BiRefNet HR-matting), dan pengubahan ukuran berdasarkan konten (Go caire biner).
Skrip Python berada di `packages/ai/python/`. Image Docker mengunduh terlebih dahulu semua bobot model selama build sehingga kontainer bekerja sepenuhnya offline.
Skrip Python ada di `packages/ai/python/`. Paket model opsional berukuran besar dipasang sesuai permintaan ke dalam volume `/data/ai` yang persisten. OCR yang akurat menggunakan artefak khusus platform yang ditandatangani; tingkat Tesseract bawaan tidak memerlukan pengunduhan paket model.
### `@snapotter/shared` {#snapotter-shared}
@@ -87,7 +87,7 @@ Situs VitePress ini. Di-deploy ke Cloudflare Pages secara otomatis saat push ke
2. Frontend mengirim POST multipart ke `/api/v1/tools/:section/:toolId` dengan file dan pengaturan.
3. Route API memvalidasi input dengan Zod, lalu mengirim pemrosesan.
4. Untuk tool standar, job dimasukkan ke antrean ke pool BullMQ yang sesuai (image, media, atau docs berdasarkan modalitas). Worker BullMQ dalam proses secara otomatis mengorientasikan gambar berdasarkan metadata EXIF, menjalankan fungsi proses tool, dan mengembalikan hasilnya.
5. Untuk tool AI, penghubung TypeScript mengirim permintaan ke dispatcher Python yang persisten (atau memunculkan subproses baru sebagai fallback), menunggunya selesai, dan membaca file keluaran.
5. Untuk sebagian besar alat AI, jembatan TypeScript mengirimkan permintaan ke Python dispatcher yang persisten. OCR yang cepat malah memanggil Tesseract, dan OCR yang akurat memulai eksekusi yang disematkan dari generasi OCR aktif yang tidak dapat diubah. Tingkat OCR yang diminta ditetapkan saat masuk dan tidak pernah diubah secara diam-diam selama eksekusi.
6. Progres job dipertahankan ke tabel `jobs` di PostgreSQL sehingga state bertahan saat kontainer dimulai ulang. Pembaruan waktu nyata dikirimkan melalui SSE di `/api/v1/jobs/:jobId/progress`.
7. API mengembalikan `jobId` dan `downloadUrl`. Pengguna mengunduh file yang telah diproses dari `/api/v1/download/:jobId/:filename`.
apps/docs/id/guide/deployment.md
+42 -10
View File
@@ -1,8 +1,8 @@
---
description: "Deploy SnapOtter ke produksi dengan Docker. Persyaratan perangkat keras, penyiapan GPU, dan konfigurasi reverse proxy untuk Nginx, Traefik, dan Cloudflare."
i18n_source_hash: 6b6957060fa6
i18n_provenance: machine
i18n_output_hash: 45dafa6467df
i18n_output_hash: 5ed614569b73
i18n_source_hash: e0d8d5f6fc87
i18n_provenance: human
---
# Deployment {#deployment}
@@ -11,6 +11,12 @@ SnapOtter diterapkan sebagai stack Docker Compose 3 kontainer: image aplikasi Sn
Lihat [Docker Image](./docker-tags) untuk penyiapan GPU, contoh Docker Compose, dan penyematan versi.
<!-- korean-ocr-contract:start -->
::: info Kompatibilitas OCR bahasa Korea
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`.
:::
<!-- korean-ocr-contract:end -->
## Quick Start (CPU) {#quick-start-cpu}
```yaml
@@ -113,7 +119,7 @@ Aplikasi kemudian tersedia di `http://localhost:1349`.
## Quick Start (NVIDIA CUDA) {#quick-start-nvidia-cuda}
Untuk akselerasi NVIDIA CUDA pada perkakas AI (penghapusan latar belakang, upscaling, penyempurnaan wajah, OCR):
Untuk akselerasi NVIDIA CUDA pada alat AI yang didukung (penghapusan latar belakang, peningkatan skala, penyempurnaan wajah):
```yaml
# docker-compose-gpu.yml - Requires: NVIDIA GPU + nvidia-container-toolkit
@@ -251,10 +257,10 @@ deploy:
|---|---|
| CPU | 4 core |
| RAM | 4 GB |
| Disk | 3 GB (image) + 24 GB (model AI) + workspace |
| Disk | 3 GB (gambar) + sekitar 20 GB (semua paket AI opsional) + ruang kerja |
| GPU | Tidak diperlukan (fallback CPU) |
**Memasang bundle AI-lah yang mendorong RAM ke 4 GB.** Tanpa AI terpasang, aplikasi menganggur di sekitar 360 MB; dengan ketujuh bundle terpasang aplikasi menahan ~2.6 GB resident, karena sidecar AI Python memuat model-modelnya di awal (penghapusan latar belakang, upscaling, OCR, transkripsi, deteksi wajah, restorasi) saat startup. Instalasi non-AI tetap ringan; instalasi AI membutuhkan ≥4 GB.
**Menginstal dan menjalankan paket AI yang lebih besar mendorong rekomendasi RAM menjadi 4 GB.** Tanpa paket opsional yang diinstal, aplikasi menganggur sekitar 360 MB. Alat Python yang lama berbagi sidecar, sedangkan OCR yang akurat menggunakan dispatcher khusus yang berumur panjang yang disematkan pada generasi aktif yang tidak dapat diubah. Sebelum aktivasi, penginstal menjalankan smoke test pada kandidat. Kemudian secara atom beralih ke dispatcher baru dan menguras dispatcher sebelumnya sebelum garbage collection. Setiap artefak OCR akurat resmi harus melewati release suite kasus terburuknya di dalam 4 GiB cgroup, sedangkan rekomendasi host 4 GB memberikan ruang utama untuk aplikasi Node.js, Postgres, Redis, antrean, dan pekerjaan bersamaan.
Sebagian besar perkakas AI sepenuhnya dapat digunakan di CPU; beberapa benar-benar menginginkan GPU. Diukur pada CPU 4-core modern:
@@ -271,7 +277,7 @@ SnapOtter sengaja tidak memasukkan unduhan model ini ke dalam image Docker. Bund
Beberapa perkakas bergantung pada lebih dari satu bundle bersama. Misalnya, Passport Photo membutuhkan `background-removal` dan `face-detection`; jika `background-removal` sudah terpasang, mengaktifkan Passport Photo hanya mengunduh bundle `face-detection` yang hilang. Penggunaan ulang yang sama berlaku di semua perkakas AI.
Ukuran unduhan model AI:
Perkiraan penyimpanan paket AI opsional:
| Bundle | Ukuran Disk |
|---|---|
@@ -279,9 +285,16 @@ Ukuran unduhan model AI:
| Upscale + Penyempurnaan wajah + Penghapusan noise | 5-6 GB |
| Deteksi wajah | 200-300 MB |
| Object eraser + Colorize | 1-2 GB |
| OCR | 5-6 GB |
| OCR yang akurat (`balanced`/`best`) | ~208-234 unduhan MiB / ~409-488 MiB terpasang |
| Restorasi foto | 4-5 GB |
| **Semua bundle** | **~24 GB** |
| Transkripsi | ~600 MB |
| **Semua paket** | **~20 GB terpasang** |
OCR yang cepat dimasukkan ke dalam gambar melalui Tesseract, menambahkan sekitar 25 MiB, dan tidak memerlukan paket OCR opsional atau persyaratan memori 4 GiB. Paket akurat tersedia dalam wadah resmi Linux amd64 dan arm64 dan menjalankan ONNX Runtime di CPU. Host NVIDIA menggunakan runtime CPU OCR yang sama, sehingga OCR tidak bergantung pada versi CUDA atau arsitektur GPU. Runtime yang akurat memerlukan setidaknya 4 GiB memori efektif: batas cgroup kontainer yang dikonfigurasi, jika tidak, memori host. SnapOtter menolak sistem di bawah minimum kompatibilitas yang ditandatangani sebelum mengunduh paket. Instalasi paket akurat juga ditolak pada arsip bare-metal/prebuilt yang libc dan Python ABI tidak dapat dijamin.
Replika yang berbagi `DATA_DIR` yang sama harus menggunakan arsitektur CPU yang sama; sematkan deployment multi-replika ke node yang kompatibel dengan node affinity. Replika campuran amd64/arm64 memerlukan volume data terpisah dan deployment SnapOtter yang independen.
Runtime yang akurat menjaga satu generasi tetap aktif dan membersihkan cache unduhannya setelah aktivasi. Untuk rilis ini, instalasi pertama untuk sementara memerlukan sekitar 620-720 MiB untuk arsip ditambah staging, dan peningkatan dapat mencapai puncaknya mendekati 1,2 GiB sementara generasi lama tetap aktif. Penginstal menghitung persyaratan yang tepat dari indeks yang ditandatangani dan generasi saat ini sebelum mengunduh atau mengekstraksi, dan gagal lebih awal jika volume data terlalu kecil.
```yaml
deploy:
@@ -353,7 +366,6 @@ Lihat [daftar format lengkap](/id/guide/supported-formats) untuk detail setiap f
- **Content-aware resize** crash pada gambar besar (>5 MP) karena batasan pada binary caire. Bekerja baik dengan gambar yang lebih kecil.
- **HEIF decode** memakan 13-23 detik. HEIC (varian Apple) jauh lebih cepat pada 0.3-0.9 detik.
- **OCR Jepang** gagal di CPU karena bug MKLDNN PaddlePaddle. Bekerja di GPU.
- **Upscale** kehabisan waktu di CPU untuk apa pun di luar gambar kecil. GPU diperlukan untuk penggunaan praktis.
- **CodeFormer** penyempurnaan wajah jauh lebih lambat daripada GFPGAN (53d vs 2d di GPU). GFPGAN direkomendasikan untuk sebagian besar kasus penggunaan.
@@ -434,6 +446,26 @@ Kesalahan startup menyebutkan UID persis yang harus digunakan, jadi jalur tercep
| `SESSION_DURATION_HOURS` | `168` | Masa berlaku sesi login (7 hari) |
| `CORS_ORIGIN` | (kosong) | Origin yang diizinkan dipisahkan koma, atau kosong untuk same-origin |
### Proksi keluar dan CA {#outbound-proxy-and-private-ca} pribadi
Kontainer resmi mengaktifkan dukungan proxy lingkungan Node. Jika SnapOtter harus mencapai repositori runtime OCR atau layanan HTTPS lainnya melalui proksi perusahaan, atur `HTTPS_PROXY` (dan `HTTP_PROXY` bila diperlukan). Setel `NO_PROXY` ke daftar host yang dipisahkan koma yang harus dijangkau secara langsung, seperti Postgres, Redis, dan penyimpanan objek internal.
Jika proksi atau layanan internal ditandatangani oleh otoritas sertifikat swasta, pasang sertifikat CA hanya-baca dan arahkan `NODE_EXTRA_CA_CERTS` ke sana. File tersebut harus ada ketika proses Node dimulai:
```yaml
services:
app:
environment:
HTTPS_PROXY: http://proxy.example.internal:3128
HTTP_PROXY: http://proxy.example.internal:3128
NO_PROXY: postgres,redis,minio,localhost,127.0.0.1
NODE_EXTRA_CA_CERTS: /etc/snapotter/custom-ca.pem
volumes:
- ./company-ca.pem:/etc/snapotter/custom-ca.pem:ro
```
Simpan kredensial proxy di luar file Compose (misalnya di file atau rahasia `.env` yang dilindungi). Jangan nonaktifkan verifikasi TLS: indeks OCR yang ditandatangani mengautentikasi metadata rilis, sementara validasi TLS normal masih melindungi transportasi dan setiap permintaan keluar lainnya.
## Health Check {#health-check}
Kontainer menyertakan health check bawaan:
apps/docs/id/guide/docker-tags.md
+4 -4
View File
@@ -1,8 +1,8 @@
---
description: "Tag image Docker SnapOtter, benchmark GPU, penyematan versi, dan dukungan multi-platform untuk AMD64 dan ARM64."
i18n_source_hash: 148b3608e11a
i18n_provenance: human
i18n_output_hash: 1285488cc707
i18n_source_hash: fda322e78b4b
i18n_provenance: human
---
# Image Docker {#docker-image}
@@ -41,7 +41,6 @@ Diuji pada NVIDIA RTX 4070 (VRAM 12 GB) dengan potret JPEG 572x1024.
| Penghapusan latar (isnet) | 2.457ms | 1.137ms | 2,2x |
| Upscale 2x | 350ms | 309ms | 1,1x |
| Upscale 4x | 910ms | 310ms | 2,9x |
| OCR (PaddleOCR) | 137ms | 94ms | 1,5x |
| Blur wajah | 139ms | 122ms | 1,1x |
#### Cold start (permintaan pertama setelah container mulai) {#cold-start-first-request-after-container-start}
@@ -50,7 +49,8 @@ Diuji pada NVIDIA RTX 4070 (VRAM 12 GB) dengan potret JPEG 572x1024.
|------|-----|-----|---------|
| Penghapusan latar | 22.286ms | 4.792ms | 4,7x |
| Upscale 2x | 3.957ms | 2.318ms | 1,7x |
| OCR (PaddleOCR) | 1.469ms | 1.090ms | 1,3x |
OCR tidak termasuk dalam perbandingan CUDA. Tingkat Tesseract bawaan dan tingkat RapidOCR/ONNX opsional menggunakan CPU, termasuk ketika kontainer memiliki akses NVIDIA GPU.
### Pemeriksaan kesehatan CUDA {#cuda-health-check}
apps/docs/id/guide/getting-started.md
+3 -3
View File
@@ -1,8 +1,8 @@
---
description: "Pasang SnapOtter dengan Docker dalam satu perintah. Termasuk penyiapan Docker Compose, membangun dari sumber, dan gambaran lengkap fitur."
i18n_source_hash: 4536d4558b8e
i18n_provenance: machine
i18n_output_hash: 6df615cedb03
i18n_source_hash: 24724b5595b2
i18n_provenance: human
---
# Memulai {#getting-started}
@@ -32,7 +32,7 @@ Untuk detail tentang apa yang dikumpulkan, lihat [Apa yang dikumpulkan SnapOtter
:::
::: tip Akselerasi NVIDIA CUDA
Tambahkan `--gpus all` untuk penghapusan latar belakang, upscaling, OCR, penyempurnaan wajah, dan restorasi yang diakselerasi NVIDIA CUDA:
Tambahkan `--gpus all` untuk penghapusan latar belakang yang dipercepat NVIDIA CUDA, peningkatan skala, penyempurnaan wajah, dan pemulihan. OCR tetap berbasis CPU dan bekerja pada image yang sama dengan atau tanpa akses GPU:
```bash
docker run -d --name SnapOtter -p 1349:1349 --gpus all -v SnapOtter-data:/data snapotter/snapotter:latest