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

* 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
2026-08-03 07:46:42 +02:00 · 2026-07-15 03:34:24 +08:00
parent 58121f205f
commit 991c981529
409 changed files with 67151 additions and 8076 deletions
@@ -1,18 +1,26 @@
 ---
 description: "Tüm yerel ML araçlarını içeren AI motoru referansı. Arka plan kaldırma, büyütme, OCR, yüz algılama, fotoğraf onarımı ve daha fazlası."
-i18n_source_hash: 14728c1dcd05
-i18n_provenance: machine
-i18n_output_hash: f5dc727495bf
+i18n_output_hash: 96b67b8bbec2
+i18n_source_hash: aa9a56cdddc7
+i18n_provenance: human
 ---

 # AI Motoru Referansı {#ai-engine-reference}

-`@snapotter/ai` paketi, tüm ML işlemleri için Node.js'i **kalıcı bir Python sidecar** ile köprüler. Dispatcher süreci, hızlı sıcak başlatma performansı için istekler arasında canlı kalır. NVIDIA CUDA, başlangıçta otomatik algılanır ve mevcut olduğunda kullanılır; aksi takdirde AI araçları CPU üzerinde çalışır.
+`@snapotter/ai` paketi, yerel ML işlemleri için yerel araçları ve Python çalışma zamanlarını koordine eder. Çoğu ML aleti, hızlı ısınma başlatmaları için kalıcı bir Python sidecar kullanır. OCR kasıtlı olarak ayrıdır: `fast`, yerel Tesseract ikili dosyasını çağırırken, `balanced` ve `best`, `/data/ai/v3` altında aktif değişmez RapidOCR nesline sabitlenmiş özel bir kalıcı JSONL dispatcher kullanır. Her istek bir generation lease içerir. Yükseltme sırasında SnapOtter, etkinleştirmeden önce aday üzerinde bir smoke test çalıştırır, atomik olarak yeni dispatcher'ye geçer ve ardından garbage collection'den önce eski nesli boşaltır.
+
+NVIDIA CUDA, onu destekleyen çalışma zamanları tarafından otomatik olarak algılanır ve kullanılır. OCR, her ana bilgisayarda CPU'yi kullanır, NVIDIA GPU'lu sistemler dahil, bu alet için CUDA ve sürücü bağlantısından kaçınılması.

 VA-API, Quick Sync veya OpenCL üzerinden Intel/AMD iGPU hızlandırma bugün AI çıkarımı için desteklenmiyor. `/dev/dri` öğesini bir konteynere eşlemek, CUDA yeteneğine sahip bir NVIDIA GPU mevcut olmadıkça bu Python sidecar araçlarını hızlandırmaz.

 Dört modalite (image, audio, video, document) genelinde 19 Python sidecar AI aracı, artı isteğe bağlı AI yetenekleri olan 2 araç. Tüm modeller yerel olarak çalışır; ilk model indirmesinden sonra internet gerekmez.

+
+<!-- korean-ocr-contract:start -->
+::: info Korece OCR uyumluluğu
+Hızlı OCR `auto`, `en`, `de`, `es`, `fr`, `zh` ve `ja` dillerini destekler, ancak Koreceyi (`ko`) desteklemez. Korece için doğru OCR paketi ve `balanced` ya da `best` gerekir. Paket resmi Linux amd64 ve arm64 kapsayıcılarında, OCR’nin CPU’da kaldığı NVIDIA ana bilgisayarları dahil çalışır. Desteklenmeyen sistemler açık bir uyumluluk hatası alır ve sessizce `fast` seçeneğine dönülmez. Korece ile `fast` veya eski `tesseract` diğer adı kuyruk öncesinde `FEATURE_INCOMPATIBLE` ve `fast-korean-unsupported` ile reddedilir.
+:::
+<!-- korean-ocr-contract:end -->
 ## Mimari {#architecture}

 ```
@@ -22,15 +30,17 @@ Node.js Tool Route
 @snapotter/ai bridge.ts
      | (stdin/stdout JSON + stderr progress events)
      v
- Python dispatcher (persistent process, "ai" profile)
+ +-- Native Tesseract + Ghostscript (fast image/PDF OCR)
+ |
+ +-- Isolated OCR runtime (persistent JSONL dispatcher)
+ |     `-- RapidOCR + ONNX Runtime CPU + pinned PP-OCR models
+ |
+ `-- 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)
@@ -52,7 +62,7 @@ AI modelleri, araç başına bir arşiv olarak değil, paylaşılan bağımlıl

 Docker imgesi, uygulamayı artı ortak çalışma zamanını içerir. Büyük model arşivleri, talep üzerine kalıcı `/data/ai` birimine indirilir, ardından ihtiyaç duyan her araç tarafından yeniden kullanılır. Bir paket, başka bir araç ihtiyaç duyduğu için zaten yüklüyse, ona bağımlı yeni bir aracı etkinleştirmek o paketi tekrar indirmez.

-Her AI aracı, çalışabilmesi için bir veya daha fazla özellik paketi gerektirir. Yönetici arayüzü, tam paket listesini çözen, zaten yüklü olan paketleri atlayan ve yalnızca eksik indirmeleri kuyruğa alan `POST /api/v1/admin/tools/:toolId/features/install` aracılığıyla araç bazında yükler. Örneğin, yeni bir örnekte Pasaport Fotoğrafı'nı etkinleştirmek `background-removal` ve `face-detection` paketlerini kuyruğa alır; Arka Plan Kaldırma zaten yüklüyken etkinleştirmek yalnızca `face-detection` paketini kuyruğa alır.
+Çoğu AI aracının çalıştırılmadan önce bir veya daha fazla özellik paketine ihtiyacı vardır. Yönetici kullanıcı arayüzü bunları `POST /api/v1/admin/tools/:toolId/features/install` aracılığıyla araçla yükler; bu, tam paket listesini çözer, önceden yüklenmiş olan paketleri atlar ve yalnızca eksik indirmeleri sıraya koyar. Örneğin, yeni bir örnekte Pasaport Fotoğrafını etkinleştirmek `background-removal` ve `face-detection` sıralarını oluşturur; Arka Plan Kaldırma zaten yüklendikten sonra etkinleştirildiğinde yalnızca `face-detection` sıraya alınır. OCR bir istisnadır çünkü `fast`'nin pakete ihtiyacı yoktur; isteğe bağlı doğru çalışma süresini kullanıcı arayüzü veya `POST /api/v1/admin/features/ocr/install` aracılığıyla yükleyin.

 | Paket | Boyut | Paylaşılan bağımlılık grubu | Onu kullanan araçlar |
 |--------|------|-------------------------|-------------------|
@@ -61,7 +71,7 @@ Her AI aracı, çalışabilmesi için bir veya daha fazla özellik paketi gerekt
 | `object-eraser-colorize` | 1-2 GB | LaMa inpainting/outpainting ve DDColor | erase-object, colorize, ai-canvas-expand |
 | `upscale-enhance` | 5-6 GB | RealESRGAN, GFPGAN / CodeFormer, gürültü giderme | upscale, enhance-faces, noise-removal |
 | `photo-restoration` | 4-5 GB | çizik onarımı ve restorasyon hattı | restore-photo |
-| `ocr` | 5-6 GB | PaddleOCR / Tesseract OCR yığını | ocr, ocr-pdf |
+| `ocr` | ~208-234 MiB indir / ~409-488 MiB kuruldu | İsteğe bağlı RapidOCR 3.9.1, ONNX Runtime 1.20.1 ve sabitlenmiş PP-OCR modelleri | ocr, ocr-pdf (yalnızca `balanced` ve `best`) |
 | `transcription` | ~600 MB | faster-whisper konuşmadan metne modelleri | transcribe-audio, auto-subtitles |

 Çapraz paket bağımlılıkları olan araçlar:
@@ -71,7 +81,17 @@ Her AI aracı, çalışabilmesi için bir veya daha fazla özellik paketi gerekt
 | `passport-photo` | `background-removal`, `face-detection` | Arka planı kaldırır, ardından kırpmayı pasaport ve kimlik fotoğrafı kurallarına göre çerçevelemek için yüz işaret noktalarını kullanır. |
 | `enhance-faces` | `upscale-enhance`, `face-detection` | Seçilen yüz bölgelerinde GFPGAN veya CodeFormer iyileştirmesini çalıştırmadan önce yüzleri algılar. |

-Bir araç yalnızca gerekli tüm paketleri yüklendiğinde kullanılabilir. Kısmi yüklemeler geçerlidir ve kademeli olarak işlenir: yüklü paketler yeniden kullanılır, eksik paketler indirme olarak gösterilir ve paylaşılan Python ortamı eş zamanlı olarak değiştirilmesin diye kuyruğa alınan yüklemeler birer birer çalışır.
+Bir araç yalnızca OCR hariç gerekli tüm paketler yüklendiğinde kullanılabilir: yerleşik `fast` katmanı, isteğe bağlı OCR paketi olmadan kullanılabilir durumda kalır. Kısmi kurulumlar geçerlidir ve artımlı olarak işlenir: kurulu paketler yeniden kullanılır, eksik paketler indirmeler olarak gösterilir ve sıraya alınmış kurulumlar birer birer çalıştırılır, böylece paylaşılan Python ortamı aynı anda değiştirilmez.
+
+### Doğru OCR çalışma zamanı kurulumu {#accurate-ocr-runtime-installation}
+
+Doğru OCR paketi, resmi Linux amd64 veya Linux arm64 konteyneri için platforma özel bir çalışma zamanıdır. amd64 yapısı Python 3.12'yi kullanır; arm64 yapısı Python 3.11'i kullanır. Her iki yapı da ONNX Runtime'nin `CPUExecutionProvider`'si aracılığıyla RapidOCR'yi çalıştırır, dolayısıyla aynı paket yalnızca CPU ve NVIDIA Docker ana bilgisayarlarında çalışır. Doğru çalışma zamanı en az 4 GiB etkili bellek gerektirir: yapılandırılmış kapsayıcı cgroup sınırı, aksi takdirde ana bilgisayar belleği. İmzalı uyumluluk minimumunun altındaki bir sistem indirmeden önce reddedilir. Bu gereksinim yerleşik Fast OCR için geçerli değildir. Bare-metal yapıları, libc ve Python ABI güvenli bir şekilde çıkarılamadığından reddedilir; Ana bilgisayar Tesseract ve Ghostscript sağladığında hızlı OCR kullanılabilir durumda kalır.
+
+İsteğe bağlı yapı, mimariye bağlı olarak yaklaşık 208-234 MiB sıkıştırılmış ve 409-488 MiB çıkartılmıştır. İmzalı dizin, yükleyici tarafından zorunlu kılınan sıkıştırılmış ve çıkartılmış bayt sayımlarını tam olarak bağlar. Yerleşik Tesseract, resmi görüntüye yaklaşık 25 MiB ekler ve `/data/ai`'de hiçbir dosyaya ihtiyaç duymaz.
+
+Çevrimiçi kurulum, imzalı bir sürüm dizinini ve geçerli platform için tam içerik adresli yapıyı getirir. SnapOtter, yeni nesli atomik olarak etkinleştirmeden önce Ed25519 dizin imzasını, yapı boyutunu, SHA-256 özetini, model özetlerini, yolları, dosya modlarını ve aşamalı smoke test'yi doğrular. Başarısız bir yükleme önceki sağlıklı nesli etkin bırakır.
+
+Hava boşluklu kurulum için, `index` ve `archive` adlı çok parçalı alanları kullanarak hem sürümün `ocr-runtime-index.json`'sini hem de eşleşen OCR çalışma zamanı arşivini `POST /api/v1/admin/features/import`'ye yükleyin. Çevrimdışı içe aktarma, çevrimiçi kurulumla aynı imza, karma, çıkarma, uyumluluk ve duman testi kontrollerini uygular; güvenilir imzalı dizini olmayan bir arşiv reddedilir.

 ---

@@ -143,16 +163,16 @@ Arka planı kaldırır ve düz bir renk veya gradyanla değiştirir.
 ## OCR / Metin Çıkarma {#ocr-text-extraction}

 **Araç rotası:** `ocr`  
-**Modeller:** Tesseract (hızlı), PaddleOCR PP-OCRv5 (dengeli), PaddleOCR-VL 1.5 (en iyi)
+**Modeller:** Tesseract (`fast`); PP-OCRv6 küçük modellerle (`balanced`) RapidOCR; Kalibre edilmiş varyant puanlamasına sahip PP-OCRv6 orta modeller (`best`)

 | Parametre | Tür | Varsayılan | Açıklama |
 |-----------|------|---------|-------------|
-| `quality` | `"fast"` \| `"balanced"` \| `"best"` | `"balanced"` | İşleme katmanı |
+| `quality` | `"fast"` \| `"balanced"` \| `"best"` | Dinamik | `quality` ve `engine` belirtilmezse SnapOtter kullanılabilir en iyi katmanı şu sırayla seçer: `best`, `balanced`, `fast`. Korece için `fast` hiçbir zaman seçilmez; `best`, ardından `balanced` kullanılır veya doğru çalışma zamanının kurulum ya da uyumluluk hatası döndürülür. |
 | `language` | string | `"auto"` | Dil: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko` |
-| `enhance` | boolean | `true` | OCR doğruluğunu artırmak için görüntüyü ön işle |
-| `engine` | string | - | Kullanımdan kaldırıldı. `tesseract` değerini `fast` ile, `paddleocr` değerini `balanced` ile eşler |
+| `enhance` | boolean | Seviyeye bağlı | Yerel kontrastı iyileştirin. Hızlı doğrudan uygular; doğru katmanlar, yalnızca kalibre edilmiş puanlama OCR'yi iyileştirdiğinde varyantı korur. En İyi için Varsayılanlar Açıktır |
+| `engine` | sicim | - | Kullanımdan kaldırılan uyumluluk takma adı. `tesseract`'yi `fast`'ye ve eski `paddleocr` değerini `balanced`'ye eşler; PaddlePaddle yüklenmiyor |

-Sınırlayıcı kutular, güven puanları ve çıkarılan metin blokları ile yapılandırılmış sonuçlar döndürür.
+Çıkarılan metni artı kaynak meta verilerini döndürür: motor, istenen ve gerçek kalite, cihaz, sağlayıcı, bozulma durumu, uyarılar ve uygun olduğunda doğru çalışma zamanı/model sürümleri. Açık kalite istekleri hiçbir zaman başka bir katmana geri dönmez. `balanced` veya `best` kullanılamıyorsa API, `fast`'yi sessizce çalıştırmak yerine `FEATURE_NOT_INSTALLED` veya `FEATURE_INCOMPATIBLE`'yi döndürür.

 ## PDF OCR {#pdf-ocr}

@@ -163,9 +183,13 @@ Yapay zeka destekli OCR kullanarak taranmış PDF belgelerinden sayfa sayfa meti

 | Parametre | Tür | Varsayılan | Açıklama |
 |-----------|------|---------|-------------|
-| `quality` | `"fast"` \| `"balanced"` \| `"best"` | `"balanced"` | İşleme katmanı |
+| `quality` | `"fast"` \| `"balanced"` \| `"best"` | Dinamik | `quality` ve `engine` belirtilmezse SnapOtter kullanılabilir en iyi katmanı şu sırayla seçer: `best`, `balanced`, `fast`. Korece için `fast` hiçbir zaman seçilmez; `best`, ardından `balanced` kullanılır veya doğru çalışma zamanının kurulum ya da uyumluluk hatası döndürülür. |
 | `language` | string | `"auto"` | Dil: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko` |
 | `pages` | string | `"all"` | Sayfa seçimi: `"all"`, `"1-3"`, `"1,3,5"` |
+| `enhance` | boolean | Seviyeye bağlı | Yerel kontrastı iyileştirin. Hızlı doğrudan uygular; doğru katmanlar, yalnızca kalibre edilmiş puanlama OCR'yi iyileştirdiğinde varyantı korur. En İyi için Varsayılanlar Açıktır |
+| `engine` | sicim | - | Kullanımdan kaldırılan uyumluluk takma adı. `tesseract`'yi `fast`'ye ve eski `paddleocr` değerini `balanced`'ye eşler; PaddlePaddle yüklenmiyor |
+
+Aynı sürüm düşürmeme kuralı PDF OCR için de geçerlidir. PDF sayfaları tanınmadan önce rasterleştirilir ve bir istek en fazla 50 sayfa seçebilir.

 ## Yüz / PII Bulanıklaştırma {#face-pii-blur}

@@ -1,8 +1,8 @@
 ---
 description: "Eksiksiz REST API başvurusu. Araç uç noktaları, toplu işleme, işlem hatları, dosya kitaplığı, kimlik doğrulama, ekipler ve yönetici işlemleri."
-i18n_source_hash: 8646977f7cc9
-i18n_provenance: machine
 i18n_output_hash: 4ae115bf377e
+i18n_source_hash: b89b5df16af5
+i18n_provenance: human
 ---

 # REST API Başvurusu {#rest-api-reference}
@@ -178,7 +178,7 @@ Tüm yapay zeka araçları kendi donanımınızda çalışır: varsayılan olara
 | `remove-background` | Arka Planı Kaldır | rembg (BiRefNet / U2-Net) | `model`, `backgroundType` (transparent/color/gradient/blur/image), `backgroundColor`, `gradientColor1`, `gradientColor2`, `gradientAngle`, `blurEnabled`, `blurIntensity`, `shadowEnabled`, `shadowOpacity` |
 | `upscale` | Görüntü Ölçek Büyütme | RealESRGAN | `scale` (2/4), `model`, `faceEnhance`, `denoise`, `format`, `quality` |
 | `erase-object` | Nesne Silici | LaMa (ONNX) | Maske ikinci dosya parçası olarak gönderilir (alan adı `mask`), `format`, `quality` |
-| `ocr` | OCR / Metin Çıkarma | PaddleOCR / Tesseract | `quality` (fast/balanced/best), `language`, `enhance` |
+| `ocr` | OCR / Metin Çıkarma | Tesseract (hızlı); RapidOCR + PP-OCR ONNX (dengeli/en iyi) | `quality` (hızlı/dengeli/en iyi), `language`, `enhance` |
 | `blur-faces` | Yüz / PII Bulanıklaştırma | MediaPipe | `blurRadius`, `sensitivity` |
 | `smart-crop` | Akıllı Kırpma | MediaPipe + Sharp | `mode` (subject/face/trim), `strategy` (attention/entropy), `width`, `height`, `padding`, `facePreset` (closeup/head-shoulders/upper-body/half-body), `sensitivity`, `threshold`, `padToSquare`, `padColor`, `targetSize`, `quality` |
 | `image-enhancement` | Görüntü İyileştirme | Analiz tabanlı | `mode` (auto/exposure/contrast/color/sharpness), `strength` |
@@ -425,7 +425,9 @@ Bazı araçlar standart `POST /api/v1/tools/<section>/<toolId>` dışında ek u

 ## Toplu İşleme {#batch-processing}

-Toplu işlem etkin genel bir aracı bir kerede birden çok dosyaya uygulayın. Bir ZIP arşivi döndürür. PDF imzalama, PDF OCR ve PDF'den görüntüye ön ayar yolları gibi özel çok dosyalı veya çok adımlı yollar, genel `/batch` yolu yerine kendi uç nokta sözleşmelerini kullanır.
+Toplu işlem etkin genel bir aracı bir kerede birden çok dosyaya uygulayın. Bir ZIP arşivi döndürür. PDF imzalama ve PDF'den görüntüye ön ayar yolları gibi özel çok dosyalı veya çok adımlı yollar, genel `/batch` yolu yerine kendi uç nokta sözleşmelerini kullanır.
+
+`ocr-pdf` aracı bu genel `/batch` yolunu destekler.

 ```bash
 curl -X POST http://localhost:1349/api/v1/tools/image/compress/batch \
@@ -594,6 +596,8 @@ Sorgu parametreleri:

 Yapay zeka özellik paketlerini yönetin (Docker ortamında yapay zeka modeli paketlerini kurun/kaldırın). Özel otomasyondan bir aracı etkinleştirirken araç düzeyindeki kurulum uç noktasını tercih edin: bazı yapay zeka araçları birden fazla paylaşılan pakete ihtiyaç duyar ve bu uç nokta zaten kurulu paketleri atlarken yalnızca eksik olanları kuyruğa alır.

+OCR, katı bir bağımlılık yerine isteğe bağlı bir geliştirmedir. `fast` Tesseract katmanı paket olmadan çalışır; `POST /api/v1/admin/features/ocr/install`, `balanced` ve `best` için imzalı RapidOCR paketini Linux amd64 veya arm64 üzerine yükler. Doğru OCR çalışma zamanı, yalnızca CPU ve NVIDIA ana bilgisayarlarında CPU kullanır ve en az 4 GiB etkin bellek gerektirir (yapılandırılmış kapsayıcı cgroup sınırı, aksi takdirde ana bilgisayar belleği). SnapOtter, `requiredMemoryBytes`, `effectiveMemoryBytes` ve `insufficient-memory` uyumluluk nedenini bildirir ve indirmeden önce uyumsuz bir yüklemeyi reddeder. Bu bellek gereksinimi `fast` için geçerli değildir. Paket, hedefe bağlı olarak yaklaşık 208-234 MiB indirilebilir ve 409-488 MiB kuruludur; imzalı dizin, yükleme sırasında uygulanan tam boyutları bağlar.
+
 | Yöntem | Yol | Erişim | Açıklama |
 |--------|------|--------|-------------|
 | `GET` | `/api/v1/features` | Kimlik doğrulamalı | Tüm özellik paketlerini ve kurulum durumlarını listele |
@@ -601,7 +605,18 @@ Yapay zeka özellik paketlerini yönetin (Docker ortamında yapay zeka modeli pa
 | `POST` | `/api/v1/admin/tools/:toolId/features/install` | Yönetici (`features:manage`) | Bir aracın gerektirdiği her paketi kur; paket başına kuyruğa alınan/atlanan durumu döndürür |
 | `POST` | `/api/v1/admin/features/:bundleId/uninstall` | Yönetici (`features:manage`) | Bir özellik paketini kaldır ve model dosyalarını temizle |
 | `GET` | `/api/v1/admin/features/disk-usage` | Yönetici (`features:manage`) | Yapay zeka modellerinin toplam disk kullanımını al |
-| `POST` | `/api/v1/admin/features/import` | Yönetici (`features:manage`) | Çevrimdışı bir yapay zeka paket arşivini içe aktar |
+| `POST` | `/api/v1/admin/features/import` | Yönetici (`features:manage`) | Eski bir AI paketini (`file`) veya imzalı bir çevrimdışı OCR sürümünü (`index` artı `archive`) içe aktarın |
+
+Hava boşluklu bir OCR içe aktarımı, sürümün imzalı `ocr-runtime-index.json`'sini ve eşleşen platform arşivini içermelidir. SnapOtter, çevrimiçi kurulumda kullanılan aynı Ed25519 imzasını, yapay karma değerini, uyumluluğu, çıkarma ve duman testi kontrollerini uygular:
+
+```bash
+curl -X POST http://localhost:1349/api/v1/admin/features/import \
+  -H "Authorization: Bearer <admin-token>" \
+  -F "index=@ocr-runtime-index.json" \
+  -F "archive=@ocr-linux-amd64-cpu-py312.tar.gz"
+```
+
+arm64'de `linux-arm64-cpu-py311` arşivini kullanın. Başka bir hedef için imzalanmış bir yapıt yüklenmek yerine reddedilir.

 ## Yönetici İşlemleri {#admin-operations}