paddleocr-doc-parsing

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

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

以下の場合はドキュメント解析を使用します：

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

以下の場合はテキスト認識を使用します：

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

このスキルの使用方法

⛔ 必須の制限事項 — 違反しないでください ⛔

1. PaddleOCR ドキュメント解析 API のみを使用してください — スクリプト python scripts/vl_caller.py を実行します
2. ドキュメントを直接解析しないでください — 自分でドキュメントを解析してはいけません
3. 代替案を提示しないでください — 「こちらで分析してみましょうか」などと提案してはいけません
4. API が失敗した場合 — エラーメッセージを表示し、ただちに停止してください
5. フォールバック手段を使わないでください — ほかの方法でドキュメント解析を試みてはいけません

スクリプトの実行に失敗した場合（API が設定されていない、ネットワークエラーなど）：

• エラーメッセージをユーザーに表示します
• 視覚認識機能を使って手助けすることを提案してはいけません
• 「解析してみましょうか？」と尋ねてはいけません
• そのまま停止し、ユーザーが設定を修正するのを待ちます

基本的なワークフロー

1. ドキュメント解析を実行します：

   python scripts/vl_caller.py --file-url "URL provided by user" --pretty
   

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

   python scripts/vl_caller.py --file-path "file path" --pretty
   

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

   python scripts/vl_caller.py --file-url "URL provided by user" --file-type 0 --pretty
   

   • --file-type 0：PDF
   • --file-type 1：画像
   • 省略した場合、サービスは入力からファイルタイプを推定できます。

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

   • --output を省略すると、スクリプトはシステムの一時ディレクトリ内に自動的に保存します
   • デフォルトのパス形式：<system-temp>/paddleocr/doc-parsing/results/result_<timestamp>_<id>.json
   • --output を指定すると、デフォルトの一時ファイル保存先が上書きされます
   • --stdout を指定すると、JSON が stdout に出力され、ファイルは保存されません
   • 保存モードでは、スクリプトは保存先の絶対パスを stderr に出力します：Result saved to: /absolute/path/...
   • デフォルトの保存モードまたはカスタム保存モードでは、応答する前に保存された JSON ファイルを読み込んで解析します
   • 保存モードでは、保存されたファイルのパスと、完全な生の JSON がそのファイルにあることを必ずユーザーに伝えます
   • ファイルへの保存を明示的に省略したい場合に限り、--stdout を使用します

2. 出力 JSON には、すべてのドキュメントデータが完全な形で含まれています：

   • ヘッダー、フッター、ページ番号
   • 本文
   • 構造を含む表
   • 数式（LaTeX 形式）
   • 図やグラフ
   • 脚注や参考文献
   • 印章やスタンプ
   • レイアウトと読み取り順序

   入力タイプに関する注意：

   • 対応するファイルタイプは、モデルとエンドポイントの設定によって異なります。
   • 使用するエンドポイント API に記載されたファイルタイプの制約に必ず従ってください。

3. 出力 JSON の以下のフィールドを使って、ユーザーが必要とする情報を抽出します：

   • トップレベルの text
   • result[n].markdown
   • result[n].prunedResult

重要：コンテンツをすべて表示する

重要：ユーザーのニーズに応じて、抽出したコンテンツをすべて表示する必要があります。

• 出力 JSON には、構造化された形式ですべてのドキュメントコンテンツが含まれています
• 保存モードでは、保存された JSON ファイルでプロバイダーの生の結果を確認できます
• ユーザーが求めているコンテンツをすべて表示してください。切り捨てたり要約したりしないでください
• ユーザーが「すべてのテキスト」を求めた場合は、text フィールド全体を表示してください
• ユーザーが「表」を求めた場合は、ドキュメント内のすべての表を表示してください
• ユーザーが「本文」を求めた場合は、ヘッダーとフッターを除外し、本文のテキストをすべて表示してください

具体的には：

• すること：求められたテキスト、すべての表、すべての数式を表示する
• すること：トップレベルの text、result[n].markdown、result[n].prunedResult の各フィールドを使ってコンテンツを提示する
• しないこと：コンテンツが非常に長い（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)"

JSON レスポンスを理解する

出力 JSON は、生の API 結果を包むエンベロープを使用します。

{
  "ok": true,
  "text": "Full markdown/HTML text extracted from all pages",
  "result": { ... },  // raw provider response
  "error": null
}

主なフィールド：

• text — すべてのページから抽出した Markdown テキスト（テキストをすばやく表示する場合に使用）
• result - プロバイダーの生のレスポンスオブジェクト
• result[n].prunedResult - 各ページの構造化された解析結果（レイアウト／コンテンツ／信頼度および関連メタデータ）
• result[n].markdown — Markdown／HTML 形式でレンダリングされたページ全体の出力

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

使用例

例 1：ドキュメント全文を抽出する

python scripts/vl_caller.py \
  --file-url "https://example.com/paper.pdf" \
  --pretty

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

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

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

python scripts/vl_caller.py \
  --file-path "./financial_report.pdf" \
  --pretty

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

• 構造化された解析データ（レイアウト／コンテンツ／信頼度）には result[n].prunedResult
• レンダリングされたページコンテンツには result[n].markdown

例 3：保存せずに JSON を出力する

python scripts/vl_caller.py \
  --file-url "URL" \
  --stdout \
  --pretty

次に、以下を返します。

• ユーザーがドキュメントの全文を求めた場合は、text 全体
• 完全な構造化ページデータが必要な場合は、result[n].prunedResult と result[n].markdown

初回の設定

API が設定されていない場合：

次のエラーが表示されます：

PADDLEOCR_DOC_PARSING_API_URL not configured. Get your API at: https://paddleocr.com

設定の手順：

1. 正確なエラーメッセージを（URL を含めて）ユーザーに表示します。

2. 安全な設定方法を案内します：

   • チャットに認証情報を貼り付けるのではなく、ホストアプリケーションの標準的な方法（設定ファイルや環境変数の UI など）で設定することをおすすめします。
   • 必要な環境変数を示します：

     - PADDLEOCR_DOC_PARSING_API_URL
     - PADDLEOCR_ACCESS_TOKEN
     - Optional: PADDLEOCR_DOC_PARSING_TIMEOUT
     

3. それでもユーザーがチャットで認証情報を提供した場合（妥当な形式であれば受け付けます）：

   • PADDLEOCR_DOC_PARSING_API_URL=https://xxx.paddleocr.com/layout-parsing, PADDLEOCR_ACCESS_TOKEN=abc123...
   • Here's my API: https://xxx and token: abc123
   • コピー＆ペーストしたコード形式
   • その他の妥当な形式
   • セキュリティに関する注意：チャットで共有した認証情報は会話履歴に保存される可能性があることをユーザーに伝えます。可能な場合は、代わりにホストアプリケーションの設定から認証情報を設定することをおすすめします。

4. 値を解析して検証します：

   • PADDLEOCR_DOC_PARSING_API_URL を抽出します（paddleocr.com などを含む URL を探します）
   • PADDLEOCR_DOC_PARSING_API_URL が /layout-parsing で終わる完全なエンドポイントであることを確認します
   • PADDLEOCR_ACCESS_TOKEN を抽出します（40 文字以上の英数字で構成された文字列である場合が一般的です）
   • 設定が必要な環境変数を正確にユーザーに伝えます

5. 環境が設定済みかどうかユーザーに確認します：

   • ホストアプリケーション、ランタイム環境、または適切な設定ファイルにこれらの値を設定したことをユーザーが確認するまで待ちます
   • セキュリティ上の理由から、ホストアプリケーションのディレクトリ（例：~/.claude/skills）にスキルがインストールされている場合は、デフォルトでは configure.py を実行したり、ローカルの .env ファイルを作成したりしないでください

6. 確認後にのみ再試行します：

   • 環境変数が利用可能になったことをユーザーが確認したら、元の解析タスクを再試行します

重要：エラーメッセージの形式は厳密に定められており、スクリプトが出力したとおりに正確に表示する必要があります。変更したり、言い換えたりしないでください。

大きなファイルの処理

API にファイルサイズの上限はありません。PDF の場合、1 リクエストあたり最大 100 ページです。

大きなファイルを処理する際のヒント：

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

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

python scripts/vl_caller.py --file-url "https://your-server.com/large_file.pdf"

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

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

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

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

# Then process the smaller file
python scripts/vl_caller.py --file-path "pages_1_5.pdf"

エラー処理

認証に失敗しました（403）：

error: Authentication failed

→ トークンが無効です。正しい認証情報で再設定してください

API のクォータを超過しました（429）：

error: API quota exceeded

→ 1 日あたりの API クォータを使い切りました。待機するかアップグレードするようユーザーに伝えてください

未対応の形式：

error: Unsupported file format

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

重要な注意事項

• スクリプトはコンテンツを一切フィルタリングしません - 常に完全なデータを返します
• AI エージェントが提示する内容を決定します - ユーザーの具体的なリクエストに基づいて判断します
• すべてのデータを常に利用できます - ニーズに応じて別の解釈が可能です
• 情報が失われることはありません - ドキュメントの完全な構造が保持されます

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

• references/output_schema.md - 出力形式の仕様

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

次の場合は、これらのリファレンスドキュメントをコンテキストに読み込んでください：

• 複雑な解析の問題をデバッグする場合
• 出力形式を確認する必要がある場合
• プロバイダーの API 詳細を扱う場合

スキルのテスト

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

python scripts/smoke_test.py

このテストでは、設定と、必要に応じて API 接続を確認します。