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/ja/api/ai.md

@@ -1,18 +1,26 @@
 ---
 description: "すべてのローカル ML ツールを網羅した AI エンジンリファレンス。背景除去、アップスケーリング、OCR、顔検出、写真復元など。"
-i18n_source_hash: 14728c1dcd05
-i18n_provenance: machine
-i18n_output_hash: 721e8f11de40
+i18n_output_hash: aabfa7bf38f2
+i18n_source_hash: aa9a56cdddc7
+i18n_provenance: human
 ---
 
 # AI エンジンリファレンス {#ai-engine-reference}
 
-`@snapotter/ai` パッケージは、すべての ML 処理のために Node.js を**永続的な Python サイドカー**へ橋渡しします。ディスパッチャープロセスはリクエスト間で稼働し続けるため、高速なウォームスタート性能が得られます。NVIDIA CUDA は起動時に自動検出され、利用可能な場合に使用されます。それ以外の場合、AI ツールは CPU 上で動作します。
+`@snapotter/ai` パッケージは、ローカルの ML 操作のためにネイティブ ツールと Python ランタイムを調整します。 ほとんどの ML ツールは、高速ウォーム スタートのために永続的な Python sidecar を使用します。 OCR は意図的に分離されています。 `fast` はネイティブ Tesseract バイナリを呼び出します。 一方、`balanced` および `best` は、`/data/ai/v3` の下でアクティブで不変の RapidOCR 世代に固定された専用の永続 JSONL dispatcher を使用します。 各リクエストは generation lease を保持します。 アップグレード中、SnapOtter はアクティブ化する前に候補に対して smoke test を実行し、新しい dispatcher にアトミックに切り替えてから、garbage collection の前に古い世代を排出します。
+
+NVIDIA CUDA は自動検出され、それをサポートするランタイムによって使用されます。 OCR はすべてのホストで CPU を使用します。 NVIDIA GPU を搭載したシステムを含む、 このツールの CUDA とドライバーの結合を回避します。
 
 VA-API、Quick Sync、OpenCL を介した Intel/AMD の iGPU アクセラレーションは、現時点では AI 推論に対応していません。`/dev/dri` をコンテナにマッピングしても、CUDA 対応の NVIDIA GPU が利用できない限り、これらの Python サイドカーツールは高速化されません。
 
 4 つのモダリティ（画像、音声、動画、ドキュメント）にわたる 19 個の Python サイドカー AI ツールに加え、AI 機能をオプションで備えた 2 個のツールがあります。すべてのモデルはローカルで動作します。初回のモデルダウンロード後はインターネットは不要です。
 
+
+<!-- korean-ocr-contract:start -->
+::: info 韓国語 OCR の互換性
+高速 OCR は `auto`、`en`、`de`、`es`、`fr`、`zh`、`ja` に対応しますが、韓国語 (`ko`) には対応しません。韓国語には高精度 OCR パックと `balanced` または `best` が必要です。パックは公式 Linux amd64/arm64 コンテナで動作し、NVIDIA ホストでも OCR は CPU 上で実行されます。非対応システムでは明示的な互換性エラーを返し、暗黙に `fast` へ切り替えません。韓国語で `fast` または旧 `tesseract` エイリアスを指定すると、キュー投入前に `FEATURE_INCOMPATIBLE` と `fast-korean-unsupported` で拒否されます。
+:::
+<!-- korean-ocr-contract:end -->
 ## アーキテクチャ {#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 モデルは、ツールごとに 1 つのアーカイブとしてではな
 
 Docker イメージには、アプリケーションと共通ランタイムが同梱されています。大きなモデルアーカイブはオンデマンドで永続的な `/data/ai` ボリュームにダウンロードされ、それを必要とするすべてのツールで再利用されます。別のツールがすでに必要としたためにバンドルがインストール済みの場合、新たに依存するツールを有効化してもそのバンドルは再ダウンロードされません。
 
-各 AI ツールは、実行前に 1 つ以上のフィーチャーバンドルを必要とします。管理 UI は `POST /api/v1/admin/tools/:toolId/features/install` を通じてツール単位でインストールを行い、必要なバンドルの全リストを解決し、すでにインストール済みのバンドルをスキップして、不足しているダウンロードのみをキューに入れます。たとえば、新規インスタンスでパスポート写真を有効化すると `background-removal` と `face-detection` がキューに入りますが、背景除去がすでにインストールされた後に有効化すると `face-detection` のみがキューに入ります。
+ほとんどの AI ツールは、実行する前に 1 つ以上の機能バンドルを必要とします。 管理 UI は、`POST /api/v1/admin/tools/:toolId/features/install` を介してツールによってこれらをインストールします。これにより、完全なバンドル リストが解決され、すでにインストールされているバンドルがスキップされ、不足しているダウンロードのみがキューに入れられます。 たとえば、新しいインスタンス キュー `background-removal` および `face-detection` でパスポート写真を有効にすると、 バックグラウンド削除がすでにインストールされている後に有効にすると、`face-detection` のみがキューに追加されます。 OCR は例外です。 `fast` パックは必要ありません。 UI または `POST /api/v1/admin/features/ocr/install` を通じて、オプションの正確なランタイムをインストールします。
 
 | バンドル | サイズ | 共有依存関係グループ | 使用するツール |
 |--------|------|-------------------------|-------------------|
@@ -61,7 +71,7 @@ Docker イメージには、アプリケーションと共通ランタイムが
 | `object-eraser-colorize` | 1-2 GB | LaMa インペインティング/アウトペインティングと DDColor | erase-object, colorize, ai-canvas-expand |
 | `upscale-enhance` | 5-6 GB | RealESRGAN、GFPGAN / CodeFormer、ノイズ除去 | upscale, enhance-faces, noise-removal |
 | `photo-restoration` | 4-5 GB | 傷の修復と復元パイプライン | restore-photo |
-| `ocr` | 5-6 GB | PaddleOCR / Tesseract OCR スタック | ocr, ocr-pdf |
+| `ocr` | ~208-234 MiB ダウンロード / ~409-488 MiB インストール済み | オプションの RapidOCR 3.9.1、ONNX Runtime 1.20.1、および固定された PP-OCR モデル | ocr、ocr-pdf (`balanced` および `best` のみ) |
 | `transcription` | ~600 MB | faster-whisper 音声認識モデル | transcribe-audio, auto-subtitles |
 
 複数バンドルにまたがる依存関係を持つツール:
@@ -71,7 +81,17 @@ Docker イメージには、アプリケーションと共通ランタイムが
 | `passport-photo` | `background-removal`, `face-detection` | 背景を除去した後、顔のランドマークを使って、パスポートや ID 写真の規則に合わせてクロップを構図します。 |
 | `enhance-faces` | `upscale-enhance`, `face-detection` | 選択した顔の領域で GFPGAN または CodeFormer による補正を実行する前に、顔を検出します。 |
 
-ツールは、必要なすべてのバンドルがインストールされている場合にのみ利用可能になります。部分的なインストールは有効であり、段階的に処理されます。インストール済みのバンドルは再利用され、不足しているバンドルはダウンロードとして表示され、キューに入れられたインストールは共有 Python 環境が同時に変更されないよう 1 つずつ実行されます。
+ツールは、OCR を除き、必要なバンドルがすべてインストールされている場合にのみ使用できます。その組み込みの `fast` 層は、オプションの OCR パックがなくても引き続き使用できます。 部分インストールは有効であり、段階的に処理されます。インストールされたバンドルは再利用され、不足しているバンドルはダウンロードとして表示され、キューに入れられたインストールは一度に 1 つずつ実行されるため、共有 Python 環境は同時に変更されません。
+
+### 正確な OCR ランタイム インストール {#accurate-ocr-runtime-installation}
+
+正確な OCR パックは、公式 Linux amd64 または Linux arm64 コンテナー用のプラットフォーム固有のランタイムです。 amd64 ビルドは Python 3.12 を使用します。 arm64 ビルドは Python 3.11 を使用します。 どちらのビルドも ONNX Runtime の `CPUExecutionProvider` を介して RapidOCR を実行するため、同じパックが CPU のみおよび NVIDIA Docker ホストで動作します。 正確なランタイムには、少なくとも 4 GiB の有効メモリ (構成されたコンテナーの cgroup 制限、それ以外の場合はホスト メモリ) が必要です。 署名された互換性の最小値を下回るシステムは、ダウンロード前に拒否されます。 この要件は、組み込みの Fast OCR には適用されません。 Bare-metal ビルドは、libc および Python ABI を安全に推論できないため拒否されます。 ホストが Tesseract および Ghostscript を提供する場合、高速 OCR は引き続き利用可能です。
+
+オプションのアーティファクトは、アーキテクチャに応じて、圧縮すると約 208 ～ 234 MiB、抽出すると約 409 ～ 488 MiB になります。 署名付きインデックスは、インストーラーによって強制された正確な圧縮バイト数と抽出バイト数をバインドします。 組み込みの Tesseract は、約 25 の MiB を公式イメージに追加し、`/data/ai` 内のファイルは必要ありません。
+
+オンライン インストールでは、署名付きリリース インデックスと、現在のプラットフォームの正確なコンテンツ アドレス指定されたアーティファクトが取得されます。 SnapOtter は、新しい世代をアトミックにアクティブ化する前に、Ed25519 インデックス署名、アーティファクト サイズ、SHA-256 ダイジェスト、モデル ダイジェスト、パス、ファイル モード、およびステージングされた smoke test を検証します。 インストールが失敗すると、以前の正常な世代がアクティブなままになります。
+
+エアギャップ インストールの場合は、`index` および `archive` という名前のマルチパート フィールドを使用して、リリースの `ocr-runtime-index.json` と一致する OCR ランタイム アーカイブの両方を `POST /api/v1/admin/features/import` にアップロードします。 オフライン インポートでは、オンライン インストールと同じ署名、ハッシュ、抽出、互換性、およびスモーク テスト チェックが適用されます。 信頼された署名付きインデックスのないアーカイブは拒否されます。
 
 ---
 
@@ -143,16 +163,16 @@ Docker イメージには、アプリケーションと共通ランタイムが
 ## OCR / テキスト抽出 {#ocr-text-extraction}
 
 **ツールルート:** `ocr`  
-**モデル:** Tesseract（高速）、PaddleOCR PP-OCRv5（バランス）、PaddleOCR-VL 1.5（最高精度）
+**モデル:** Tesseract (`fast`); RapidOCR と PP-OCRv6 小型モデル (`balanced`)。調整されたバリアント スコアリングを備えた PP-OCRv6 中モデル (`best`)
 
 | パラメータ | 型 | デフォルト | 説明 |
 |-----------|------|---------|-------------|
-| `quality` | `"fast"` \| `"balanced"` \| `"best"` | `"balanced"` | 処理ティア |
+| `quality` | `"fast"` \| `"balanced"` \| `"best"` | 動的 | `quality` と `engine` を省略すると、SnapOtter は `best`、`balanced`、`fast` の順で利用可能な最上位の層を選びます。韓国語では `fast` を選択せず、`best`、次に `balanced` を使用し、どちらもなければ高精度ランタイムのインストールまたは互換性エラーを返します。 |
 | `language` | string | `"auto"` | 言語: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko` |
-| `enhance` | boolean | `true` | OCR 精度を高めるために画像を前処理 |
-| `engine` | string | - | 非推奨。`tesseract` を `fast` に、`paddleocr` を `balanced` にマッピングします |
+| `enhance` | ブール値 | ティアに依存 | 局所的なコントラストを改善します。高速ではそれを直接適用します。正確な階層は、調整されたスコアによって OCR が向上した場合にのみバリアントを保持します。デフォルトで最良の状態 |
+| `engine` | 弦 | - | 非推奨の互換性エイリアス。 `tesseract` を `fast` にマップし、従来の `paddleocr` 値を `balanced` にマップします。 PaddlePaddle はロードされません |
 
-バウンディングボックス、信頼度スコア、抽出されたテキストブロックを含む構造化された結果を返します。
+抽出されたテキストと来歴メタデータを返します: エンジン、要求された品質と実際の品質、デバイス、プロバイダー、劣化状態、警告、および該当する場合は正確なランタイム/モデルのバージョン。 明示的な品質要求が別の層にフォー​​ルバックすることはありません。 `balanced` または `best` が使用できない場合、API は、`fast` をサイレントに実行する代わりに、`FEATURE_NOT_INSTALLED` または `FEATURE_INCOMPATIBLE` を返します。
 
 ## PDF OCR {#pdf-ocr}
 
@@ -163,9 +183,13 @@ AI ベースの OCR を使用して、スキャンされた PDF ドキュメン
 
 | パラメータ | 型 | デフォルト | 説明 |
 |-----------|------|---------|-------------|
-| `quality` | `"fast"` \| `"balanced"` \| `"best"` | `"balanced"` | 処理ティア |
+| `quality` | `"fast"` \| `"balanced"` \| `"best"` | 動的 | `quality` と `engine` を省略すると、SnapOtter は `best`、`balanced`、`fast` の順で利用可能な最上位の層を選びます。韓国語では `fast` を選択せず、`best`、次に `balanced` を使用し、どちらもなければ高精度ランタイムのインストールまたは互換性エラーを返します。 |
 | `language` | string | `"auto"` | 言語: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko` |
 | `pages` | string | `"all"` | ページ選択: `"all"`, `"1-3"`, `"1,3,5"` |
+| `enhance` | ブール値 | ティアに依存 | 局所的なコントラストを改善します。高速ではそれを直接適用します。正確な階層は、調整されたスコアによって OCR が向上した場合にのみバリアントを保持します。デフォルトで最良の状態 |
+| `engine` | 弦 | - | 非推奨の互換性エイリアス。 `tesseract` を `fast` にマップし、従来の `paddleocr` 値を `balanced` にマップします。 PaddlePaddle はロードされません |
+
+同じダウングレードなしルールが PDF OCR にも適用されます。 PDF ページは認識前にラスタライズされ、1 つのリクエストで最大 50 ページを選択できます。
 
 ## 顔 / 個人情報のぼかし {#face-pii-blur}
 

apps/docs/ja/api/rest.md

@@ -1,8 +1,8 @@
 ---
 description: "完全な REST API リファレンス。ツールエンドポイント、バッチ処理、パイプライン、ファイルライブラリ、認証、チーム、管理者操作。"
-i18n_source_hash: 8646977f7cc9
-i18n_provenance: machine
 i18n_output_hash: aa42f6d4ddbe
+i18n_source_hash: b89b5df16af5
+i18n_provenance: human
 ---
 
 # REST API リファレンス {#rest-api-reference}
@@ -178,7 +178,7 @@ curl -X POST http://localhost:1349/api/v1/tools/<section>/<toolId>/batch \
 | `remove-background` | 背景の削除 | rembg（BiRefNet / U2-Net） | `model`, `backgroundType`（transparent/color/gradient/blur/image）, `backgroundColor`, `gradientColor1`, `gradientColor2`, `gradientAngle`, `blurEnabled`, `blurIntensity`, `shadowEnabled`, `shadowOpacity` |
 | `upscale` | 画像のアップスケール | RealESRGAN | `scale`（2/4）, `model`, `faceEnhance`, `denoise`, `format`, `quality` |
 | `erase-object` | オブジェクト消しゴム | LaMa（ONNX） | マスクは 2 番目のファイルパートとして送信（フィールド名 `mask`）, `format`, `quality` |
-| `ocr` | OCR / テキスト抽出 | PaddleOCR / Tesseract | `quality`（fast/balanced/best）, `language`, `enhance` |
+| `ocr` | OCR / テキスト抽出 | Tesseract (高速); RapidOCR + PP-OCR ONNX (バランス/ベスト) | `quality` (高速/バランス/最高)、`language`、`enhance` |
 | `blur-faces` | 顔 / PII ぼかし | MediaPipe | `blurRadius`, `sensitivity` |
 | `smart-crop` | スマートクロップ | 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` | 画像の強調 | 解析ベース | `mode`（auto/exposure/contrast/color/sharpness）, `strength` |
@@ -425,7 +425,9 @@ curl -X POST http://localhost:1349/api/v1/tools/image/html-to-image \
 
 ## バッチ処理 {#batch-processing}
 
-汎用のバッチ対応ツールを複数のファイルに一度に適用します。ZIP アーカイブを返します。PDF 署名、PDF OCR、PDF から画像へのプリセットルートなど、カスタムの複数ファイルまたは複数ステップのルートは、汎用の `/batch` ルートの代わりに独自のエンドポイント契約を使用します。
+汎用のバッチ対応ツールを複数のファイルに一度に適用します。ZIP アーカイブを返します。PDF 署名や PDF から画像へのプリセットルートなど、カスタムの複数ファイルまたは複数ステップのルートは、汎用の `/batch` ルートの代わりに独自のエンドポイント契約を使用します。
+
+`ocr-pdf` ツールは、この汎用 `/batch` ルートをサポートします。
 
 ```bash
 curl -X POST http://localhost:1349/api/v1/tools/image/compress/batch \
@@ -594,6 +596,8 @@ data: {"jobId":"...","type":"batch","status":"processing","completedFiles":2,"to
 
 AI 機能バンドル（Docker 環境での AI モデルパッケージのインストール/アンインストール）を管理します。カスタム自動化からツールを有効化する場合は、ツールレベルのインストールエンドポイントを推奨します。一部の AI ツールは複数の共有バンドルを必要とし、このエンドポイントはインストール済みのバンドルをスキップして、不足しているものだけをキューに入れます。
 
+OCR は、厳密な依存関係ではなく、オプションの拡張機能です。 `fast` Tesseract 層はパックなしで機能します。 `POST /api/v1/admin/features/ocr/install` は、`balanced` および `best` の署名付き RapidOCR パックを Linux amd64 または arm64 にインストールします。 正確な OCR ランタイムは、CPU のみおよび NVIDIA ホストで CPU を使用し、少なくとも 4 GiB の有効メモリ (構成されたコンテナーの cgroup 制限、それ以外の場合はホスト メモリ) を必要とします。 SnapOtter は、`requiredMemoryBytes`、`effectiveMemoryBytes`、および `insufficient-memory` 互換性理由を報告し、ダウンロード前に互換性のないインストールを拒否します。 このメモリ要件は、`fast` には適用されません。 このパックは、ターゲットに応じて、ダウンロードに 208 ～ 234 の MiB、インストールに 409 ～ 488 の MiB があります。 署名付きインデックスは、インストール中に適用される正確なサイズをバインドします。
+
 | メソッド | パス | アクセス | 説明 |
 |--------|------|--------|-------------|
 | `GET` | `/api/v1/features` | Auth | すべての機能バンドルとそのインストール状況を一覧表示 |
@@ -601,7 +605,18 @@ AI 機能バンドル（Docker 環境での AI モデルパッケージのイン
 | `POST` | `/api/v1/admin/tools/:toolId/features/install` | Admin（`features:manage`） | ツールが必要とするすべてのバンドルをインストール。バンドルごとの queued/skipped ステータスを返す |
 | `POST` | `/api/v1/admin/features/:bundleId/uninstall` | Admin（`features:manage`） | 機能バンドルをアンインストールし、モデルファイルをクリーンアップ |
 | `GET` | `/api/v1/admin/features/disk-usage` | Admin（`features:manage`） | AI モデルの合計ディスク使用量を取得 |
-| `POST` | `/api/v1/admin/features/import` | Admin（`features:manage`） | オフラインの AI バンドルアーカイブをインポート |
+| `POST` | `/api/v1/admin/features/import` | 管理者 (`features:manage`) | レガシー AI バンドル (`file`) または署名済みオフライン OCR リリース (`index` プラス `archive`) をインポートします。 |
+
+エアギャップされた OCR インポートには、リリースの署名付き `ocr-runtime-index.json` と一致するプラットフォーム アーカイブが含まれている必要があります。 SnapOtter は、オンライン インストールで使用されるものと同じ Ed25519 署名、アーティファクト ハッシュ、互換性、抽出、およびスモーク テスト チェックを適用します。
+
+```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 の `linux-arm64-cpu-py311` アーカイブを使用します。別のターゲットの署名付きアーティファクトはインストールされずに拒否されます。
 
 ## 管理者操作 {#admin-operations}