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,8 +1,8 @@
 ---
 description: "SnapOtter を Docker で本番環境にデプロイします。ハードウェア要件、GPU のセットアップ、Nginx、Traefik、Cloudflare 向けのリバースプロキシ設定を扱います。"
-i18n_source_hash: 6b6957060fa6
-i18n_provenance: machine
-i18n_output_hash: c1284847d134
+i18n_output_hash: 2b65cb4be9d1
+i18n_source_hash: e0d8d5f6fc87
+i18n_provenance: human
 ---

 # デプロイ {#deployment}
@@ -11,6 +11,12 @@ SnapOtter は 3 コンテナ構成の Docker Compose スタックとしてデプ

 GPU のセットアップ、Docker Compose の例、バージョン固定については [Docker Image](./docker-tags) を参照してください。

+
+<!-- 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 -->
 ## クイックスタート（CPU） {#quick-start-cpu}

 ```yaml
@@ -113,7 +119,7 @@ docker compose up -d

 ## クイックスタート（NVIDIA CUDA） {#quick-start-nvidia-cuda}

-AI ツール（背景除去、アップスケーリング、顔の補正、OCR）で NVIDIA CUDA アクセラレーションを使う場合：
+サポートされている AI ツールでの NVIDIA CUDA アクセラレーションの場合 (背景の削除、アップスケーリング、顔の強調):

 ```yaml
 # docker-compose-gpu.yml - Requires: NVIDIA GPU + nvidia-container-toolkit
@@ -251,10 +257,10 @@ deploy:
 |---|---|
 | CPU | 4 コア |
 | RAM | 4 GB |
-| ディスク | 3 GB（イメージ）+ 24 GB（AI モデル）+ 作業領域 |
+| Disk | 3 GB (イメージ) + 約 20 GB (すべてのオプションの AI パック) + ワークスペース |
 | GPU | 不要（CPU フォールバック） |

-**AI バンドルのインストールこそが RAM を 4 GB まで押し上げる要因です。** AI を何もインストールしていない状態では、アプリはおよそ 360 MB でアイドルします。7 つのバンドルをすべてインストールすると、約 2.6 GB を常駐で保持します。これは Python の AI サイドカーが起動時にモデル（背景除去、アップスケーリング、OCR、文字起こし、顔検出、復元）を事前読み込みするためです。非 AI のインストールは軽量なままです。AI のインストールには 4 GB 以上が必要です。
+**より大きな AI バンドルをインストールして実行すると、推奨値は 4 GB の RAM になります。** オプション パックがインストールされていない場合、アプリは約 360 MB でアイドル状態になります。 従来の Python ツールは sidecar を共有しますが、正確な OCR は、アクティブな不変世代に固定された専用の長寿命 dispatcher を使用します。 アクティブ化する前に、インストーラーは候補に対して smoke test を実行します。 次に、新しい dispatcher にアトミックに切り替え、garbage collection の前に以前の dispatcher を排出します。 すべての公式の正確な OCR アーティファクトは、4 GiB cgroup 内で最悪の release suite を通過する必要がありますが、4 GB のホスト推奨では、Node.js アプリケーション、Postgres、Redis、キュー、および同時作業のための余裕が残されています。

 ほとんどの AI ツールは CPU でも十分に使えますが、いくつかは GPU を強く望みます。最新の 4 コア CPU で測定した結果：

@@ -271,7 +277,7 @@ SnapOtter は意図的に、これらのモデルのダウンロードを Docker

 一部のツールは複数の共有バンドルに依存します。たとえば Passport Photo は `background-removal` と `face-detection` の両方を必要とします。`background-removal` がすでにインストールされていれば、Passport Photo を有効にしても不足している `face-detection` バンドルだけがダウンロードされます。この再利用はすべての AI ツールに同様に当てはまります。

-AI モデルのダウンロードサイズ：
+オプションの AI パックのストレージの見積もり:

 | バンドル | ディスクサイズ |
 |---|---|
@@ -279,9 +285,16 @@ AI モデルのダウンロードサイズ：
 | アップスケール + 顔の補正 + ノイズ除去 | 5〜6 GB |
 | 顔検出 | 200〜300 MB |
 | オブジェクト消去 + カラー化 | 1〜2 GB |
-| OCR | 5〜6 GB |
+| 正確な OCR (`balanced`/`best`) | ~208-234 MiB ダウンロード / ~409-488 MiB インストール済み |
 | 写真復元 | 4〜5 GB |
-| **すべてのバンドル** | **約 24 GB** |
+| 転写 | ~600MB |
+| **すべてのバンドル** | **~20 GB がインストールされています** |
+
+高速 OCR は、Tesseract を通じてイメージに組み込まれ、約 25 MiB を追加します。また、オプションの OCR パックやその 4 つの GiB メモリ要件は必要ありません。 正確なパックは、公式の Linux amd64 および arm64 コンテナーで入手でき、ONNX Runtime を CPU 上で実行します。 NVIDIA ホストは同じ CPU OCR ランタイムを使用するため、OCR は CUDA バージョンまたは GPU アーキテクチャに依存しません。 正確なランタイムには、少なくとも 4 GiB の有効メモリ (構成されたコンテナーの cgroup 制限、それ以外の場合はホスト メモリ) が必要です。 SnapOtter は、パックをダウンロードする前に、署名された互換性の最小値を下回るシステムを拒否します。 正確なパックのインストールは、libc および Python ABI が保証できない bare-metal/事前構築済みアーカイブでも拒否されます。
+
+同じ `DATA_DIR` を共有するレプリカは、同じ CPU アーキテクチャを使用する必要があります。複数レプリカのデプロイは、ノードアフィニティを使用して互換性のあるノードに固定してください。amd64 と arm64 が混在するレプリカには、個別のデータボリュームと独立した SnapOtter デプロイが必要です。
+
+正確なランタイムにより、1 つのアクティブな世代が維持され、アクティブ化後にそのダウンロード キャッシュが消去されます。 このリリースでは、最初のインストールには一時的にアーカイブとステージングに約 620 ～ 720 MiB が必要で、古い世代がアクティブなままアップグレードすると、ピークは 1.2 GiB 近くになる可能性があります。 インストーラーは、ダウンロードまたは抽出する前に署名付きインデックスと現在の世代から正確な要件を計算し、データ量が小さすぎる場合は早期に失敗します。

 ```yaml
 deploy:
@@ -353,7 +366,6 @@ SnapOtter は **55 以上の入力フォーマット** と **14 の出力フォ

 - **コンテンツ認識リサイズ** は、caire バイナリの制限により大きな画像（5 MP 超）でクラッシュします。より小さい画像では問題なく動作します。
 - **HEIF のデコード** には 13〜23 秒かかります。HEIC（Apple の派生形式）は 0.3〜0.9 秒とはるかに高速です。
- **OCR 日本語** は PaddlePaddle の MKLDNN のバグにより CPU で失敗します。GPU では動作します。
 - **アップスケール** は、小さい画像を超えるものについては CPU でタイムアウトします。実用には GPU が必要です。
 - **CodeFormer** の顔の補正は GFPGAN よりかなり遅いです（GPU で 53 秒に対して 2 秒）。ほとんどのユースケースには GFPGAN を推奨します。

@@ -434,6 +446,26 @@ securityContext:
 | `SESSION_DURATION_HOURS` | `168` | ログインセッションの有効期間（7 日） |
 | `CORS_ORIGIN` | （空） | カンマ区切りの許可オリジン、または同一オリジンの場合は空 |

+### 送信プロキシとプライベート CA {#outbound-proxy-and-private-ca}
+
+公式コンテナにより、Node の環境プロキシ サポートが有効になります。 SnapOtter が企業プロキシ経由で OCR ランタイム リポジトリまたは他の HTTPS サービスに到達する必要がある場合は、`HTTPS_PROXY` (必要に応じて `HTTP_PROXY`) を設定します。 `NO_PROXY` を、Postgres、Redis、内部オブジェクト ストレージなど、直接アクセスする必要があるホストのカンマ区切りのリストに設定します。
+
+プロキシまたは内部サービスがプライベート認証局によって署名されている場合は、CA 証明書を読み取り専用でマウントし、`NODE_EXTRA_CA_CERTS` をそれを指します。このファイルは、ノード プロセスの開始時に存在する必要があります。
+
+```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
+```
+
+プロキシ資格情報は、Compose ファイルの外に保管してください (たとえば、保護された `.env` ファイルまたはシークレット内)。 TLS 検証を無効にしないでください。署名された OCR インデックスはリリース メタデータを認証しますが、通常の TLS 検証は引き続きトランスポートとその他すべての送信リクエストを保護します。
+
 ## ヘルスチェック {#health-check}

 コンテナには組み込みのヘルスチェックが含まれています：