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

apps/docs/tr/api/ai.md

@@ -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}