paddleocr-doc-parsing

PaddleOCR ドキュメント解析スキル

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

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

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

• 表を含むドキュメント（請求書、財務レポート、スプレッドシート）
• 数式を含むドキュメント（学術論文、科学文書）
• グラフや図を含むドキュメント
• 複数段組のレイアウト（新聞、雑誌、パンフレット）
• レイアウト解析が必要な複雑なドキュメント構造
• 構造化された理解が必要なあらゆるドキュメント

使用しないケース：

• シンプルなテキストのみの抽出
• 速度が重要な、すばやく処理する OCR タスク
• スクリーンショットや、テキストが明瞭なシンプルな画像

インストール

スクリプトは依存関係をインラインで宣言します（PEP 723）。別途インストールする必要はありません。依存関係は uv が自動的に解決します。

uv run scripts/layout_caller.py --help

このスキルの使用方法

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

基本的なワークフロー

1. 入力ソースを特定する：

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

2. ドキュメント解析を実行する：

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

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

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

   任意：ファイルタイプを明示的に設定する：

   uv run scripts/layout_caller.py --file-url "URL provided by user" --file-type 0 --pretty
   

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

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

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

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

3. JSON 応答を解析する：

   • ok フィールドを確認します。true は成功、false はエラーを意味します
   • 出力には、テキスト、表、数式（LaTeX）、図、印、ヘッダー／フッター、読み取り順序など、ドキュメントのデータ全体が含まれます
   • ユーザーの要望に応じて、適切なフィールドを使用します：
     • text — 全ページのドキュメント全文
     • result.result.layoutParsingResults[n].markdown.text — ページ単位の Markdown
     • result.result.layoutParsingResults[n].prunedResult — 位置と信頼度を含む構造化レイアウトデータ
   • エラーを処理します。ok が false の場合は、error.message を表示してください

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

   • ユーザーの要望に基づいて内容を表示します（下記の「出力全体の表示」を参照）
   • 内容が空の場合、ドキュメントには抽出可能なテキストが含まれていない可能性があります
   • 保存モードでは、保存したファイルのパスと、そこに生の JSON 全体があることを必ずユーザーに伝えてください

解析後に行うこと

構造化された出力を取得した後の一般的な手順：

• Markdown として保存：text フィールドを .md ファイルに書き込みます。表、見出し、数式が保持されます
• 特定の表を抽出：result.result.layoutParsingResults[n].prunedResult に移動すると、位置と信頼度のデータを含む個々のレイアウト要素にアクセスできます
• RAG／検索パイプラインに渡す：text フィールドは構造化された Markdown なので、チャンク分割とインデックス作成にすぐ使用できます
• 結果が不十分な場合：再試行する前に、以下の「より良い結果を得るためのヒント」を参照してください

出力全体の表示

ユーザーの依頼内容に基づいて、抽出したコンテンツをすべて表示してください。解析結果は、そのすべてをユーザーが受け取って初めて役立ちます。途中で切り詰めると、データが気付かれないまま失われます。

• ユーザーが「すべてのテキスト」を求めた場合は、text フィールド全体を表示します
• ユーザーが「表」を求めた場合は、ドキュメント内の表をすべて表示します
• ユーザーが「主な内容」を求めた場合は、ヘッダー／フッターを除外し、本文のテキストをすべて表示します
• コンテンツが極端に長い（10,000 文字超）場合を除き、「...」で省略しないでください
• ユーザーが完全な出力を期待している場合に、「プレビューを表示します」と言わないでください

正しい例：

User: "Extract all the text from this document"
Agent: I've parsed the complete document. Here's all the extracted text:

[Display entire text field or concatenated regions in reading order]

Document Statistics:
- Total regions: 25
- Text blocks: 15
- Tables: 3
- Formulas: 2
Quality: Excellent (confidence: 0.92)

誤った例：

User: "Extract all the text"
Agent: "I found a document with multiple sections. Here's the beginning:
'Introduction...' (content truncated for brevity)"

出力の理解

スクリプトは ok、text、result、error を含むエンベロープを返します。ドキュメント全体の内容には text を使用し、ページごとの構造化データには result.result.layoutParsingResults[n] に移動してアクセスします。

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

生の結果の場所（デフォルト）：スクリプトが stderr に出力する一時ファイルのパス

代替手段：paddleocr CLI

このミラーでは、デフォルトの方法として、同梱の scripts/layout_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_DOC_PARSING_API_URL は不要です（スクリプトでは引き続き URL が必要です）。

基本的なドキュメント解析：

# From URL
paddleocr api --model_type doc_parsing --file_url "https://example.com/report.pdf"

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

一般的なオプション：

# Specific model
paddleocr api --model_type doc_parsing --model PP-StructureV3 --file_path "./report.pdf"

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

# Page ranges (replaces split_pdf.py for most cases)
paddleocr api --model_type doc_parsing --file_path "./large.pdf" --page_ranges "1-5,10,15-20"

# Save result and extracted resources (images)
paddleocr api --model_type doc_parsing --file_url "https://..." \
  --output result.json --save_resources ./resources

# Prettify markdown output
paddleocr api --model_type doc_parsing --file_path "./document.pdf" --prettify_markdown True

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

{
  "jobId": "job-xxx",
  "pages": [
    {
      "markdownText": "# Title\n\nContent...",
      "markdownImages": { "img1": "https://...", "img2": "https://..." },
      "outputImages": { "layout1": "https://..." }
    }
  ]
}

CLI は {jobId, pages:[...]} を stdout に出力します。スクリプトの {ok, text, result, error} エンベロープで応答をラップせず、一時ファイルに自動保存せず、最上位の text フィールドを連結して提供することもありません。また、フィールド名もスクリプトの生の result.result.layoutParsingResults[n].markdown.text パスとは異なります。使用する方法を切り替える場合は、それに応じて解析ロジックを更新してください。

スクリプトと CLI — 比較：

	スクリプト（デフォルト）	paddleocr CLI（代替手段）
インストール	uv が PEP 723 のインライン依存関係を解決	pip install "paddleocr>=3.7.0"
必須の環境変数	PADDLEOCR_DOC_PARSING_API_URL + PADDLEOCR_ACCESS_TOKEN	PADDLEOCR_ACCESS_TOKEN のみ
エントリーポイント	uv run scripts/layout_caller.py ...	paddleocr api --model_type doc_parsing ...
ページの選択	scripts/split_pdf.py で事前に分割	ネイティブの --page_ranges "1-5,10"
画像の最適化	アップロード前に scripts/optimize_file.py	同じ方法を使用するか、CLI のデフォルト設定に任せる
出力	{ok, text, result, error} エンベロープ。一時ファイルに自動保存	{jobId, pages:[...]} を stdout に出力
結果の場所	stderr に出力されるパス（または --output／--stdout）	stdout（または --output）
最適な用途	Skills の実行環境、オフラインでの使用に適し、追加インストール不要	すでに paddleocr がインストールされており、上流で標準とされる方法を使いたい場合

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

使用例

例 1：ドキュメント全体のテキストを抽出する

uv run scripts/layout_caller.py \
  --file-url "https://example.com/paper.pdf" \
  --pretty

次に、以下を使用します。

• すばやく全文を出力するには、トップレベルの text を使用します
• ページ単位の出力が必要な場合は、result.result.layoutParsingResults[n].markdown を使用します

例 2：ページの構造化データを抽出する

uv run scripts/layout_caller.py \
  --file-path "./financial_report.pdf" \
  --pretty

次に、以下を使用します。

• 構造化された解析データ（レイアウト／コンテンツ／信頼度）には、result.result.layoutParsingResults[n].prunedResult を使用します

例 3：JSON をファイルに保存せず stdout に出力する

uv run scripts/layout_caller.py \
  --file-url "URL" \
  --stdout \
  --pretty

デフォルトでは、スクリプトは JSON を一時ファイルに書き込み、そのパスを stderr に出力します。--stdout を追加すると、完全な JSON を stdout に直接出力します。結果をその場で確認する場合や、別のツールにパイプで渡す場合に使用してください。

初回設定

API が設定されていない場合、スクリプトは次のように出力します。

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

設定手順：

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

2. 認証情報の取得方法を案内します：PaddleOCR のウェブサイトにアクセスし、API をクリックして、モデル（PP-StructureV3、PaddleOCR-VL、または PaddleOCR-VL-1.5）を選択してから、API_URL と Token をコピーします。これらは次の環境変数に対応します。

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

   必要に応じて、リクエストのタイムアウトには PADDLEOCR_DOC_PARSING_TIMEOUT を設定します。認証情報をチャットに貼り付けるのではなく、ホストアプリケーションの標準的な設定方法を使用するよう案内してください。

3. 認証情報を設定します — 次のいずれかの方法を使用します。

   • ユーザーがホストの UI で設定した場合：ユーザーに確認してから、再試行します。
   • ユーザーがチャットに認証情報を貼り付けた場合：会話履歴に保存される可能性があることを警告し、ホストの標準的な設定方法を使って永続化するよう案内してから、再試行します。

大きなファイルの処理

PDF の場合、1 リクエストあたりの上限は 100 ページです。

解析前に大きな画像を最適化する

大きな画像ファイルは、アップロード前に圧縮してください。アップロード時間を短縮し、処理の安定性を高められる場合があります。

uv run scripts/optimize_file.py input.png output.jpg --quality 85
uv run scripts/layout_caller.py --file-path "output.jpg" --pretty

--quality は JPEG／WebP の非可逆圧縮を制御します（1～100、デフォルトは 85）。PNG 出力には影響しません。--target-size（単位は MB、デフォルトは 20）で最大ファイルサイズを設定できます。スクリプトは目標サイズに達するまで、繰り返し縮小します。

大きなローカルファイルには URL を使用する（推奨）

非常に大きなローカルファイルでは、Base64 エンコードのオーバーヘッドを避けるため、--file-path より --file-url を優先してください。

uv run scripts/layout_caller.py --file-url "https://your-server.com/large_file.pdf"

特定のページを処理する（PDF のみ）

大きな PDF の特定のページのみが必要な場合は、先にページを抽出してください。

# Extract pages 1-5
uv run scripts/split_pdf.py large.pdf pages_1_5.pdf --pages "1-5"

# Mixed ranges are supported
uv run scripts/split_pdf.py large.pdf selected_pages.pdf --pages "1-5,8,10-12"

# Then process the smaller file
uv run scripts/layout_caller.py --file-path "pages_1_5.pdf"

エラー処理

すべてのエラーは 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 フィールドが空です
• ドキュメントが空白、画像のみ、または抽出可能なテキストを含まない可能性があります

より良い結果を得るためのヒント

解析品質が低い場合：

• 大きな画像や高解像度の画像：解析前に optimize_file.py で圧縮してください。過大な入力はレイアウト検出の精度を低下させる可能性があります。

  uv run scripts/optimize_file.py input.png optimized.jpg --quality 85
  

• 信頼度を確認する：result.result.layoutParsingResults[n].prunedResult にはレイアウト要素ごとの信頼度スコアが含まれています。値が低い領域は確認が必要です

リファレンスドキュメント

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

注：モデルのバージョンと機能は、API エンドポイント（PADDLEOCR_DOC_PARSING_API_URL）によって決まります。

スキルのテスト

スキルが正しく動作していることを確認するには、次を実行します。

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 を上書きします。