paddleocr-text-recognition

PaddleOCR テキスト認識スキル

このスキルを使用するタイミング

トリガーキーワード（ルーティング）：中国語と英語のトリガー用語は、上記の YAML description に記載されています。発見とルーティングには、このフィールドを使用してください。

このスキルを使用するケース：

• 画像（スクリーンショット、写真、スキャン画像）からテキストを抽出する
• PDF または文書画像からテキストを抽出する。ただし、目的が表のグリッド、数式、文書全体の読み取り順のレイアウトの復元ではなく、行／ボックス単位のテキストである場合
• 画像／PDF を指す URL またはローカルファイルからテキストを抽出する

使用しないケース：

• テキストとして直接読み取れるプレーンテキストファイル、コードファイル、Markdown 文書
• 表、数式、グラフ、複雑なレイアウトを含む文書 — 代わりに文書解析を使用してください
• 画像からテキストへの変換を伴わないタスク

インストール

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

uv run scripts/ocr_caller.py --help

このスキルの使用方法

作業ディレクトリ：以下の uv run scripts/... コマンドはすべて、このスキルのルートディレクトリ（この SKILL.md ファイルがあるディレクトリ）から実行してください。

基本的なワークフロー

1. 入力元を特定する：

   • ユーザーが URL を指定した場合：--file-url パラメーターを使用します
   • ユーザーがローカルファイルパスを指定した場合：--file-path パラメーターを使用します

2. OCR を実行する：

   uv run scripts/ocr_caller.py --file-url "URL provided by user" --pretty
   

   ローカルファイルの場合：

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

   パフォーマンスに関する注意：解析時間は文書の複雑さに応じて変わります。通常、1 ページの画像は 1～3 秒で完了します。大きな PDF（50 ページ以上）では数分かかる場合があります。タイムアウトと判断する前に、十分な時間を確保してください。

   デフォルトの動作：生の JSON を一時ファイルに保存します：

   • --output を省略すると、スクリプトはシステムの一時ディレクトリに自動的に保存します
   • デフォルトのパス形式：<system-temp>/paddleocr/text-recognition/results/result_<timestamp>_<id>.json
   • --output を指定すると、デフォルトの一時ファイル保存先が上書きされます
   • --stdout を指定すると、JSON が標準出力に表示され、ファイルは保存されません
   • 保存モードでは、スクリプトは保存先の絶対パスを標準エラー出力に表示します：Result saved to: /absolute/path/...
   • デフォルトまたはカスタムの保存モードでは、応答前に保存された JSON ファイルを読み込んで解析してください
   • ファイルへの保存を明示的に省略したい場合にのみ、--stdout を使用してください

3. JSON 応答を解析する：

   • デフォルトまたはカスタムの保存モードでは、スクリプトに表示された保存先のファイルパスから JSON を読み込みます
   • ok フィールドを確認します：true は成功、false はエラーを意味します
   • テキストを抽出します：text フィールドに認識されたテキスト全体が含まれます
   • --stdout を使用した場合は、標準出力の JSON を直接解析します
   • エラーに対処します：ok が false の場合は、error.message を表示します

4. 結果をユーザーに提示する：

   • 抽出したテキストを読みやすい形式で表示します
   • テキストが空の場合、画像にテキストが含まれていない可能性があります
   • 保存モードでは、保存先のファイルパスと、そこから生の JSON 全体を確認できることを必ずユーザーに伝えてください

抽出後に行うこと

認識したテキストを取得した後によく行われる作業：

• ファイルに保存する：text フィールドを .txt または .md ファイルに書き込みます
• コンテンツを検索する：保存した出力ファイル内のキーワードを検索します
• 別のパイプラインに渡す：text フィールドはクリーンなプレーンテキストで、後続の処理にそのまま使用できます
• 結果が不十分な場合：再試行する前に、以下の「結果を改善するためのヒント」を参照してください

出力全体の表示

認識されたテキスト全体を、必ずユーザーに表示してください。ユーザーは後続の作業に全文を必要とすることが多いため、省略すると、欠落に気づかれないままデータが失われます。

• 長さにかかわらず、text フィールド全体を表示します
• 「要約はこちらです」や「テキストの冒頭は……」などの表現は使用しないでください
• テキストが妥当な表示上限（10,000 文字超）を本当に超える場合を除き、「...」で省略しないでください

例 - 正しい形式：

User: "Extract the text from this image"
Agent: I've extracted the text from the image. Here's the complete content:

[Display the entire text here]

例 - 誤った形式：

User: "Extract the text from this image"
Agent: I found some text in the image. Here's a preview:
"The quick brown fox..." (truncated)

出力の理解

スクリプトは、ok、text、result、error フィールドを含む JSON エンベロープを返します。認識された内容には text を使用してください。result にはデバッグ用の未加工の API レスポンスが含まれます。

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

未加工の結果の場所（デフォルト）：スクリプトが標準エラー出力に表示する一時ファイルのパス

代替手段：paddleocr CLI

このミラーでは、同梱の scripts/ocr_caller.py をデフォルトの方法として使用します。上流の PaddleOCR プロジェクトでは、PR #18090 以降（2026-06-03）、同じ API を直接呼び出す公式 CLI も提供しています。paddleocr パッケージがインストールされていれば、uv run やローカルスクリプトを使わずに、ドロップインの代替手段として利用できます。

インストール（初回のみ）：

pip install "paddleocr>=3.7.0"

環境変数：CLI で必要なのは PADDLEOCR_ACCESS_TOKEN のみです。API エンドポイントは内部で解決されるため、CLI を使用する場合は PADDLEOCR_OCR_API_URL は不要です（スクリプトでは引き続き URL が必要です）。

基本的な OCR：

# From URL
paddleocr api --model_type ocr --file_url "https://example.com/image.png"

# From local file
paddleocr api --model_type ocr --file_path "./document.pdf"

一般的なオプション：

# Specific model
paddleocr api --model_type ocr --model PP-OCRv5 --file_path "./report.pdf"

# Disable preprocessing (faster, for flat/well-oriented images)
paddleocr api --model_type ocr --file_path "./document.pdf" \
  --use_doc_unwarping False --use_doc_orientation_classify False

# Page ranges
paddleocr api --model_type ocr --file_path "./large.pdf" --page_ranges "1-5,10,15-20"

# Save result to file
paddleocr api --model_type ocr --file_url "https://..." --output result.json

CLI の出力形式 — スクリプトのエンベロープとは異なります：

{
  "jobId": "job-xxx",
  "pages": [
    {
      "prunedResult": {
        "rec_texts": ["Line 1", "Line 2"],
        "rec_scores": [0.98, 0.95]
      },
      "ocrImageUrl": "https://..."
    }
  ]
}

CLI は {jobId, pages:[...]} を標準出力に表示します。スクリプトの {ok, text, result, error} エンベロープでレスポンスをラップせず、一時ファイルへの自動保存も行わず、text の連結も行いません。使用する方法を切り替える場合は、それに応じて解析ロジックを更新してください。

スクリプトと CLI — 概要：

	スクリプト（デフォルト）	paddleocr CLI（代替手段）
インストール	uv が PEP 723 のインライン依存関係を解決	pip install "paddleocr>=3.7.0"
必須の環境変数	PADDLEOCR_OCR_API_URL + PADDLEOCR_ACCESS_TOKEN	PADDLEOCR_ACCESS_TOKEN のみ
実行方法	uv run scripts/ocr_caller.py ...	paddleocr api --model_type ocr ...
出力	{ok, text, result, error} エンベロープ。一時ファイルに自動保存	{jobId, pages:[...]} を標準出力に表示
結果の場所	標準エラー出力に表示されるパス（または --output／--stdout）	標準出力（または --output）
おすすめの用途	Skills のランタイム、オフラインでの利用に適し、追加インストール不要	すでに paddleocr がインストールされており、上流の標準的な方法を使いたい場合

すべてのオプションについては、paddleocr api --help を実行してください。

使用例

例 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" が含まれています

• 1 日あたりの 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 を上書きします。