PaddleOCR テキスト認識スキル

このスキルを使用する場合

トリガーキーワード (ルーティング): 二言語トリガー項 (中国語と英語) は上記 YAML description に記載されています。発見とルーティングにはそのフィールドを使用してください。

このスキルを使用する場合:

• 画像 (スクリーンショット、写真、スキャン) からテキストを抽出
• PDF またはドキュメント画像からテキストを抽出 (目標が 行/ボックスレベルのテキスト の場合。テーブルグリッド、数式、または完全な読み順レイアウトの復元が目標ではない場合)
• 画像/PDF を指す URL またはローカルファイルからテキストを抽出

このスキルを使用しない場合:

• テキストとして直接読み込める平文ファイル、コードファイル、またはマークダウンドキュメント
• テーブル、数式、チャート、複雑なレイアウトを含むドキュメント — Document Parsing を使用してください
• 画像からテキストへの変換が関係しないタスク

インストール

スクリプトはインライン依存関係を宣言します (PEP 723)。別のインストール手順は不要です — uv が依存関係を自動的に解決します:

uv run scripts/ocr_caller.py --help

このスキルの使い方

作業ディレクトリ: 以下のすべての uv run scripts/... コマンドは、このスキルのルートディレクトリ (このファイルを含むディレクトリ) から実行する必要があります。

基本的なワークフロー

1. 入力ソースを識別:

   • ユーザーが URL を提供: --file-url パラメータを使用
   • ユーザーがローカルファイルパスを提供: --file-path パラメータを使用

2. OCR を実行:

   uv run scripts/ocr_caller.py --file-url "ユーザーが提供した URL" --pretty
   

   またはローカルファイルの場合:

   uv run scripts/ocr_caller.py --file-path "ファイルパス" --pretty
   

   パフォーマンス注: 解析時間はドキュメントの複雑さでスケールします。1 ページの画像は通常 1～3 秒で完了します。大規模な PDF (50+ ページ) は数分かかる場合があります。タイムアウトと判断する前に十分な時間を確保してください。

   デフォルト動作: 生の JSON を一時ファイルに保存:

   • --output を省略した場合、スクリプトはシステム一時ディレクトリの下に自動的に保存します
   • デフォルトパスパターン: <system-temp>/paddleocr/text-recognition/results/result_<timestamp>_<id>.json
   • --output を指定した場合、デフォルトの一時ファイル格納先がオーバーライドされます
   • --stdout を指定した場合、JSON は stdout に出力され、ファイルは保存されません
   • 保存モードでは、スクリプトは stderr に絶対パスを出力します: Result saved to: /absolute/path/...
   • デフォルト/カスタム保存モードでは、応答する前に保存された JSON ファイルを読み込んで解析してください
   • --stdout は、ファイル永続化をスキップしたい場合のみ使用してください

3. JSON レスポンスを解析:

   • デフォルト/カスタム保存モードでは、スクリプトに表示されている保存ファイルパスから JSON をロード
   • ok フィールドを確認: true は成功を意味し、false はエラーを意味します
   • テキストを抽出: text フィールドにすべての認識テキストが含まれます
   • --stdout を使用した場合、stdout JSON を直接解析します
   • エラーを処理: ok が false の場合、error.message を表示します

4. ユーザーに結果を提示:

   • 認識されたテキストを読みやすい形式で表示します
   • テキストが空の場合、画像にテキストが含まれていない可能性があります
   • 保存モードでは、常にユーザーに保存ファイルパスと完全な生の JSON がそこで利用可能であることを伝えます

抽出後の対応

認識されたテキストを取得した後の一般的な次のステップ:

• ファイルに保存: text フィールドを .txt または .md ファイルに書き込みます
• コンテンツを検索: 保存された出力ファイルでキーワードを検索します
• 別のパイプラインに供給: text フィールドはクリーンなテキストであり、ダウンストリーム処理に対応可能です
• 結果が不良: 再試行する前に下の「より良い結果を得るためのコツ」を参照してください

完全な出力表示

認識されたテキスト全体をユーザーに表示してください。ユーザーは通常、完全なコンテンツがダウンストリーム使用に必要です — 切り詰めると、欠落していることにユーザーが気付かない可能性のあるデータが失われます。

• text フィールド全体を表示します。長さに関わらず表示してください
• 「これは要約です」や「テキストは次で始まります」のようなフレーズを使用しないでください
• テキストが真に合理的な表示限界を超えない限り (>10,000 文字でない限り)、"..." で切り詰めないでください

例 - 正しい:

ユーザー: 「この画像からテキストを抽出してください」
エージェント: 画像からテキストを抽出しました。完全なコンテンツをここに示します:

[ここに全テキストを表示]

例 - 正しくない:

ユーザー: 「この画像からテキストを抽出してください」
エージェント: 画像にいくつかのテキストが見つかりました。プレビューをここに示します:
「素早い茶色のキツネが...」(切り詰め)

出力の理解

スクリプトは ok、text、result、error フィールドを含む JSON エンベロープを返します。認識されたコンテンツには text を使用します。result にはデバッグ用の生の API レスポンスが含まれます。

完全なスキーマとフィールドレベルの詳細については、references/output_schema.md を参照してください。

生の結果の場所 (デフォルト): スクリプトが stderr に出力した一時ファイルパス

使用例

例 1: URL OCR

uv run scripts/ocr_caller.py --file-url "https://example.com/invoice.jpg" --pretty

例 2: ローカルファイル OCR

uv run scripts/ocr_caller.py --file-path "./document.pdf" --pretty

例 3: 明示的なファイルタイプを指定した OCR

uv run scripts/ocr_caller.py --file-url "https://example.com/input" --file-type 1 --pretty

• --file-type 0: PDF
• --file-type 1: 画像
• 省略した場合、タイプはファイル拡張子から自動検出されます。ローカルファイルの場合、認識された拡張子 (.pdf, .png, .jpg, .jpeg, .bmp, .tiff, .tif, .webp) が必要です。それ以外の場合は --file-type を明示的に指定してください。認識されない拡張子を持つ URL の場合、サービスは推論を試みます。

例 4: 保存せずに JSON を出力

uv run scripts/ocr_caller.py --file-url "https://example.com/input" --stdout --pretty

初回設定

API が設定されていない場合、スクリプトは次を出力します:

{
  "ok": false,
  "text": "",
  "result": null,
  "error": {
    "code": "CONFIG_ERROR",
    "message": "PADDLEOCR_OCR_API_URL not configured. Get your API at: https://paddleocr.com"
  }
}

設定ワークフロー:

1. ユーザーに正確なエラーメッセージを表示します。

2. ユーザーに認証情報の取得をガイド: PaddleOCR ウェブサイト にアクセス、API をクリック、PP-OCRv5 モデルを選択、言語を選択、API_URL と Token をコピーします。これらは以下の環境変数に対応します:

   • PADDLEOCR_OCR_API_URL — /ocr で終わる完全なエンドポイント URL
   • PADDLEOCR_ACCESS_TOKEN — 40 文字の英数文字列

   オプションで PADDLEOCR_OCR_TIMEOUT をリクエストタイムアウト用に設定します。チャットに認証情報を貼り付けるよりも、ホストアプリケーションの標準設定方法を使用することをお勧めします。

3. 認証情報を適用 — 以下のいずれかを実行:

   • ユーザーがホスト UI で設定: ユーザーに確認をお願いして、再試行します。
   • ユーザーがチャットに認証情報を貼り付け: 会話履歴に保存される可能性があることを警告し、ホストの標準設定方法を使用して永続化するよう支援し、再試行します。

エラーハンドリング

すべてのエラーは ok: false を含む JSON を返します。エラーメッセージを表示して停止します — 独自のビジョン機能にフォールバックしないでください。error.code と error.message から問題を特定します:

認証失敗 (403) — error.message に「Authentication failed」を含む

• トークンが無効です。正しい認証情報で再設定します

クォータ超過 (429) — error.message に「API rate limit exceeded」を含む

• 毎日の API クォータが枯渇しました。ユーザーに待機またはアップグレードするよう通知します

サポートされていない形式 — error.message に「Unsupported file format」を含む

• ファイル形式がサポートされていません。PDF/PNG/JPG に変換してください

テキストが検出されない:

• text フィールドが空です
• 画像が空白、破損している、またはテキストが含まれていない可能性があります

より良い結果を得るためのコツ

認識品質が低い場合:

• 低解像度: より高い解像度の画像を提供します (ほとんどの印字テキストに対して ≥300 DPI が推奨)
• ノイズの多い背景: クリーンなスキャンまたはスクリーンショットは通常、電話写真よりも良い結果をもたらします
• 信頼度を確認: 生の JSON (result.result.ocrResults[n].prunedResult.rec_scores) は行ごとの信頼度スコアを表示します — 低い値は確認する価値のある不確実な領域を示します

参考ドキュメント

• references/output_schema.md — 完全な出力スキーマ、フィールド説明、コマンド例

注: モデルバージョン、機能、サポートされているファイル形式は、API エンドポイント (PADDLEOCR_OCR_API_URL) とその公式 API ドキュメントによって決定されます。

スキルのテスト

スキルが正常に動作していることを確認するには:

uv run scripts/smoke_test.py
uv run scripts/smoke_test.py --skip-api-test
uv run scripts/smoke_test.py --test-url "https://..."

最初の形式は設定と API 接続性をテストします。--skip-api-test は設定のみをチェックします。--test-url はデフォルトのサンプル画像 URL をオーバーライドします。