polyocr-service

PolyOCR Service は、PaddleOCR 3.x と FastAPI に基づいて構築された多言語 OCR、オプションの翻訳、および独立した PaddleOCR-VL サービスです。著者はこれがコミュニティプロジェクトであり、PaddleOCR の公式コンポーネントではないことを明記しています。 機能と制限 基本 OCR は PaddleOCR 3.x の predict() を呼び出し、3.x のマッピング/オブジェクト結果と旧リスト結果の両方に対応します。78 言語をサポートし、漢字、日本語、韓国語、ラテン文字、キリル文字、アラビア文字、デーヴァナーガリー文字、タイ文字、ギリシャ文字などの文字体系をカバーします。言語コード、英語名、中国語名の 3 種類のエイリアス（例：fr / french / 法文）を受け入れます。言語はリクエスト境界で検証され、未知の言語はモデル読み込みまで待たずに 422 unsupported_language を直接返します。画像は推論前にバイト数、デコード結果、ピクセル数、信頼度しきい値の検証を受けます。同期推論はスレッドプールで実行され、セマフォによって同時実行が制限されます。翻訳入力はエントリ数と総文字数が制限され、ベンダーが入力と一致する数を返すことが要求されます。HTTP、認証、リクエスト検証、ドメインエラーには統一された error 応答構造が使用されます。PaddleOCR-VL はアップロードされたコンテンツのみを受け付け、URL を拒否し、独立した API キーを要求し、アップロードサイズを制限します。ブラウザページは textContent を使用してサーバー結果をレンダリングし、返されたコンテンツを HTML として解釈しません。 インストールと実行 Python 3.10、3.11、3.12 をサポートし、CI でチェックされます。pip install -e ".[dev,ocr]" でインストールし、.env.example を .env にコピーして API キーを変更した後に起動します。コマンドラインエントリポイントはデフォルトで 127.0.0.1:8000 をリッスンし、POLYOCR_HOST / POLYOCR_PORT で設定できます。README は特に、--host 0.0.0.0 がすべてのネットワークインターフェースに公開されることを警告しています。コンテナ内ではこれが必要ですが、ノートパソコンや共有ネットワークで直接実行すると、LAN 内の誰でもインスタンスにアクセスできます。Web ページはルートパスにあり、API ドキュメントは /docs にあります。 API 概要 ヘルスチェック /v1/health は認証を要求しません。/v1/languages は言語コード、PaddleOCR 言語コード、文字体系、利用可能なエイリアスを返します。OCR リクエスト /v1/ocr は X-API-Key または Bearer Token をサポートし、フォームフィールドには file、language、score_threshold が含まれ、応答は正規化された言語コードをエコーし、items（text、score、bbox）、cost_ms、request_id、warnings を含みます。翻訳エンドポイント /v2/translate は texts と target_language を受け取ります。失敗応答は code、message、request_id を含む error オブジェクトに統一されます。 モーションブラー警告 画像のラプラシアン分散がしきい値（デフォルト 45.0、POLYOCR_BLUR_VARIANCE_FLOOR で調整可能）を下回るが、モデルが高い信頼度のテキストを返す場合、応答に suspected_blur 警告が付随し、detail にラプラシアン分散としきい値が示されます。README はその動機を説明しています。モーションブラーは信頼度は正常だが内容が誤ったテキストを返すため、呼び出し側は元々区別できませんでした。この警告により「区別できない」が「区別できる」に変わります。警告はモデルが実際にテキストを返した場合のみ評価され、空の結果では警告は生成されません。 設定項目 ドキュメントには、認証スイッチと API キー、CORS オリジン、アップロードサイズ上限（デフォルト 10MB）、デコード後のピクセル上限（デフォルト 2500 万）、同時推論数（デフォルト 2）、OCR ワーカースレッド数、ぼけ分散しきい値、翻訳エントリと文字数の上限、OpenAI 互換翻訳サービスのキー/ベース/モデル、VL サービスの独立したキーとアップロード上限が記載されています。認証が有効で POLYOCR_API_KEY が空の場合、基本サービスは起動を拒否します。VL サービスは常に POLYOCR_VL_API_KEY を要求します。資格情報付きの CORS はワイルドカードオリジンを許可しません。 Docker とテスト docker compose up --build によるデプロイ方法が提供され、イメージは Python 3.10 ベースラインに固定され、非 root ユーザーで実行され、ヘルスチェックが提供されます。最初の OCR でモデルがダウンロードされ、キャッシュは Compose ボリュームに保存されます。テストプロセスには、ruff フォーマットとチェック、pytest 非統合テスト、python -m build が含まれます。実際の OCR E2E には POLYOCR_RUN_OCR_E2E=1 の明示的な設定が必要で、モデルがダウンロードされる可能性があります。CI はモデルをダウンロードしない高速テストのみを実行します。 ベンチマークと実測結論 言語精度ベンチマークは、言語ごとに注釈付き画像を比較し、exact（行ごとの完全一致率）と cer（文字誤り率）の両方を報告し、検出順序の影響を受けません。堅牢性ベンチマークは、ぼけ、圧縮、回転、縮小、ノイズ、明暗コントラスト、モーションブラー、透視、不均一な照明、影、紙の質感などの撮影系劣化をカバーします。README の実測結論は次のとおりです。回転、透視、JPEG 圧縮、明暗コントラスト、不均一な照明、影、紙の質感は認識にほとんど影響せず、組み合わせた撮影シーンではむしろ満点です。真の失敗は詳細の喪失のみで、ぼけが約 σ2 を超えるか、25% 未満に縮小された場合です。唯一注意すべきはモーションブラーです。15px の変位では信頼度は正常だが誤ったテキスト（Hello World → Heelco Ncotec）が返され、9px 以内では完全に正常です。 preprocess パラメータは実装されていません。5 つの前処理パイプラインは 17 の劣化すべてで純粋な負の利益であり、自動コントラストは 17 項目のうち 11 項目で悪影響を与えたため、preprocess=true は静かに無視するのではなく 400 preprocess_unsupported を返します。実際の写真ベンチマークは CORD-v2（CC-BY-4.0、人手による単語ごとの注釈付き）を使用してテストされ、合成画像の平均は 0.975 exact、実際の写真は 0.841 単語再現率でした。README は合成画像のスコアが約 13 ポイント楽観的であると述べています。前処理は実際の写真で 3 つのパイプラインすべての平均が正でしたが、bootstrap 検定では 5 つのパイプラインすべての 95% 信頼区間が 0 をまたぎ、最小 p 値は 0.371 で、「統計的に検出可能な利益はない」という結論が維持されました。 ライセンス Apache License 2.0 を採用し、上流の PaddleOCR と一致し、第三者の帰属は NOTICE に記録されています。PaddleOCR モデルは実行時に元の配布元からダウンロードされ、それぞれのライセンスと利用規約の対象となります。