qianfanocr-document-intelligence

Qianfan OCR Document Intelligence

このスキルは画像と PDF の視覚的理解をオーケストレーションします。それ自体はビジョンモデルを実装しません。適切な分析モードを選択し、入力を準備し、同梱の CLI を呼び出し、上流のエージェント向けに構造化された結果を返します。

必須の実行順序

常に次の順序に従ってください:

1. QIANFAN_TOKEN がすでに利用可能かどうかを確認します。
2. トークンが存在しない場合は、直ちに停止し、ユーザーに API Key を尋ねます。
3. ユーザーが API Key を提供した場合は、QIANFAN_TOKEN=... として <skill-root>/.env に書き込みます。
4. トークンが利用可能になってから初めて、モードの選択、参照の読み込み、CLI の呼び出しに進みます。

このトークンの事前確認は、このスキル内の後続のすべてのルールよりも優先されます。トークン確認が通過するまで、references/*.md を読まず、モードを選択せず、同梱のスクリプトを呼び出さないでください。

API Key の設定

初回使用の前に、QIANFAN_TOKEN がプロセス環境または <skill-root>/.env のいずれかで利用可能であることを確認してください。

トークンが存在しない場合は、中国語でユーザーに尋ねます:

QIANFAN_TOKEN 环境变量未设置。请提供百度千帆 API Key。
如果您暂时没有 API Key，请到 https://cloud.baidu.com/product-s/qianfan_home 注册获取。

ユーザーがキーを提供した場合は、続行する前に <skill-root>/.env に永続化してください。一時的な export QIANFAN_TOKEN=... を唯一の保存手段として依存しないでください。

同梱のデフォルトトークンが存在すると仮定しないでください。

同梱ツール

• scripts/qianfan_ocr_cli.py: 1 つ以上の画像をバックエンドの VLM に送信します。
• scripts/pdf_to_images.py: VLM を呼び出す前に、1 つ以上の PDF をページごとの画像に変換します。
• scripts/render_doc_markdown.py: 文書解析の画像プレースホルダーを切り出した画像ファイルに置き換えます。
• scripts/run_document_parsing.py: 文書解析をエンドツーエンドで実行し、常に画像プレースホルダーをレンダリングします。
• scripts/run_pdf_document_parsing.py: PDF 文書解析をエンドツーエンドで実行し、結合された markdown、共有アセット、ページごとの markdown ファイルをエクスポートします。
• scripts/run_document_parsing_with_layout.py: レイアウト付きで文書解析を実行し、markdown、レイアウト JSON、レイアウトオーバーレイ画像をエクスポートします。
• scripts/run_layout_analysis.py: レイアウト分析を実行し、_layout.json とレイアウトオーバーレイ画像をエクスポートします。
• scripts/run_element_recognition.py: 要素認識を実行し、結果を兄弟 markdown ファイルとして保存します。

スクリプトは常に絶対パスで呼び出してください。Codex では、裸の相対パスではなく、インストールされた絶対スキルパスを使用してください。

例:

python3 "<skill-root>/scripts/qianfan_ocr_cli.py" "<prompt>" --image <path_or_url>
python3 "<skill-root>/scripts/pdf_to_images.py" <pdf_or_url> --output-dir <dir>
python3 "<skill-root>/scripts/render_doc_markdown.py" parsed.md --image <page_image> --output-dir <assets_dir> --output-markdown <rendered_md>
python3 "<skill-root>/scripts/run_document_parsing.py" <image_or_pdf>
python3 "<skill-root>/scripts/run_pdf_document_parsing.py" <pdf> --pages all
python3 "<skill-root>/scripts/run_document_parsing_with_layout.py" <image_or_pdf>
python3 "<skill-root>/scripts/run_layout_analysis.py" <image_or_pdf>
python3 "<skill-root>/scripts/run_element_recognition.py" <cropped_image_or_pdf> --element-type <text|formula|table>

トリガールール

次のすべてに該当する場合にのみ、このスキルをトリガーしてください:

• タスクが 1 つ以上の画像ファイルまたは URL、あるいは 1 つ以上の PDF ファイルまたは URL を対象としている。
• エージェントが、それらの画像または PDF 内のコンテンツを認識、理解、抽出、質問への回答、または位置特定する必要がある。
• 該当する情報が、エージェントがすでに利用可能な既存のプレーンテキストソースから取得できない。

次の場合はトリガーしないでください:

• ファイルが直接読み取り可能なプレーンテキスト、構造化データ、またはソースコードである。
• ユーザーが視覚的理解ではなく、画像処理や PDF 処理のコードを求めている。
• 画像/PDF のパスまたは URL が付随的に言及されているだけで、視覚的理解が要求されていない。
• 以前の呼び出しですでに同じ質問に回答しており、呼び出しを繰り返すことが冗長である。

入力の準備

画像入力

• ローカル画像パスまたは画像 URL を qianfan_ocr_cli.py に直接渡します。
• 無関係な画像ごとに 1 回の呼び出しを使用します。
• 画像をまたぐ推論が必要な場合にのみ、--image フラグを繰り返し使用してください。

PDF 入力

• 入力が PDF の場合は、まず scripts/pdf_to_images.py でページ画像に変換します。
• 単一ページの質問では、既知であれば該当ページのみを分析します。
• 複数ページの PDF では、ページ順を維持し、出力にページ番号を付けます。
• PDF にすでに信頼できる選択可能なテキストがあり、タスクが純粋なテキスト取得である場合は、このスキルを使用しないでください。テキストを直接読んでください。

推奨される PDF フロー:

python3 "<skill-root>/scripts/pdf_to_images.py" report.pdf --output-dir /tmp/report-pages
python3 "<skill-root>/scripts/qianfan_ocr_cli.py" "<prompt>" --image /tmp/report-pages/report-p001.png

解析モード

1 回の呼び出しにつき、必ず 1 つの主要モードを選択してください。必要に応じて、最初のパスを実行した後に、より具体的な 2 回目の呼び出しを行ってください。

モード	使用する場合	目的
document parsing	画像/PDF から文書構造、テキスト、数式、表、画像プレースホルダーが必要な場合	Markdown 解析結果を出力
layout analysis	位置とカテゴリを含むすべてのレイアウト要素が必要な場合	bbox とカテゴリを含むレイアウト要素を出力
element recognition	テキストブロック、数式、表など、切り出した要素に対して正確な認識が必要な場合	切り出した要素に対する正確な認識結果を出力
document parsing with layout	1 つのワークフローで構造解析とレイアウト検出の両方が必要な場合	Markdown 解析とレイアウト解析を出力
general ocr	文書構造を必要とせず、すべての可視テキストが必要な場合	すべての可視テキスト行を抽出
key information extraction	カード、フォーム、レシート、請求書、契約書などの文書から主要なフィールドが必要な場合	主要情報を構造化された形式で抽出
chart understanding	グラフのキャプション、構造化されたグラフ内容、またはグラフ QA が必要な場合	グラフ内容を理解して構造化
doc vqa	文書画像/PDF に関する特定の質問への回答が必要な場合	文書に基づいた回答

モード選択のヒューリスティック

• 出力が Markdown で階層を保持する必要がある、ページ全体の文書理解には document parsing を使用します。
• バウンディングボックスとカテゴリが主な出力である場合は layout analysis を使用します。
• element recognition は、対象領域を切り出した後、またはユーザーが単一の対象要素の画像を提供した場合にのみ使用します。
• element recognition には scripts/run_element_recognition.py を推奨します。これにより、結果は assets ディレクトリなしの単一の markdown ファイルとしてソースファイルの隣に書き出されます。
• Markdown の再構築とレイアウトボックスの両方が必要な場合は document parsing with layout を使用します。
• スクリーンショット、看板、ポスター、およびレイアウトが重要でない単純な文書テキスト抽出には general ocr を使用します。
• フォーム、証明書、ID、請求書、レシート、契約書、その他のフィールド中心の文書には key information extraction を使用します。
• key information extraction の場合、ユーザーが具体的なフィールドリストを指定せずにすべてのキーと値の情報またはすべてのフィールドを求めた場合は、明示的なスキーマをでっち上げるのではなく、スキーマフリーのプロンプトパスを使用します。
• プロット、ダッシュボード、グラフの多いレポートページには chart understanding を使用します。
• 合計、日付、条項、ページ内容、または文書に特定の項目が含まれているかどうかなど、的を絞った質問には doc vqa を使用します。

リファレンス読み込みルール

トークンのプリフライトが通過し、モードを選択した後にのみ、プロンプトを作成したりスクリプトを呼び出したりする前に、必ず references/ 内の対応するファイルを読んでください。

• document parsing -> references/document-parsing.md
• layout analysis -> references/layout-analysis.md
• element recognition -> references/element-recognition.md
• document parsing with layout -> references/document-parsing-with-layout.md
• general ocr -> references/general-ocr.md
• key information extraction -> references/key-information-extraction.md
• chart understanding -> references/chart-understanding.md
• doc vqa -> references/doc-vqa.md

一致するリファレンスが存在する場合、このステップを省略しないでください。

プロンプトの参照ルール

選択したリファレンスにプロンプトテンプレート、プロンプトルール、固定プロンプト、出力形式、またはパラメータの推奨が含まれている場合は、そのリファレンスを主要な信頼できる情報源として使用します。

• アドホックにプロンプトを書くよりも、対応する references/*.md ファイル内のプロンプトを優先してください。
• 固定プロンプトまたは標準プロンプトとしてマークされているリファレンスプロンプトは、そのまま再利用してください。
• 新しい形式を考案するのではなく、リファレンスの出力形式要件を再利用してください。
• ユーザーの質問、選択されたキー、ページ番号、入力スコープなど、タスク固有の詳細はリファレンスプロンプトの上に追加するだけにしてください。
• 意図的にリファレンスプロンプトから逸脱する場合は、その理由を中間推論で述べ、逸脱を最小限に抑えてください。

パラメータマッピングルール

選択したリファレンスが実行パラメータを定義している場合は、それらを実際の CLI フラグまたはリクエストフィールドに変換してください。ドキュメント上の注記としてのみ残さないでください。

例:

• min_dynamic_patch = 8 -> --min-dynamic-patch 8 を渡す
• max_dynamic_patch = 24 -> --max-dynamic-patch 24 を渡す
• thinking モード -> --thinking を渡す

qianfan_ocr_cli.py を実行する前に、最終的なコマンドに選択したモードで必要なパラメータ設定が含まれていることを確認してください。

プロンプトルール

• ユーザーが中国語でコミュニケーションしている場合は、VLM プロンプトを中国語で書いてください。それ以外の場合は英語を使用してください。
• プロンプト内でモードと出力形式を明示してください。
• 推測するのではなく、不確実なものは不明 / 判読不能としてマークするようモデルに指示してください。
• PDF の場合、複数のページを分析するときは必ずプロンプトにページ番号を含めてください。
• element recognition で使用する切り抜き入力の場合、要素タイプを指定してください: テキスト、数式、表、図のキャプション、印鑑、署名ブロックなど。
• ![label](<box>[[...]]</box>) プレースホルダーを含む document parsing 出力の場合、レンダリング可能なローカル画像を必要とするユーザーに Markdown を提示する前に scripts/render_doc_markdown.py を実行してください。
• タスクが標準的なドキュメント解析の場合は、qianfan_ocr_cli.py と render_doc_markdown.py を手動で連結するよりも scripts/run_document_parsing.py を優先してください。
• ユーザーが PDF 全体に対して 1 つの markdown とページごとの markdown ファイル、および共有アセットディレクトリを希望する場合の PDF ドキュメント解析には、scripts/run_pdf_document_parsing.py を優先してください。選択した PDF ページが意味的に関連しており、1 つのマルチイメージリクエストとして送信すべき場合は --request-mode joint を使用してください。ページを独立して解析でき、並行して実行すべき場合は --request-mode batch --concurrency <N> を使用してください。
• document parsing with layout には scripts/run_document_parsing_with_layout.py を優先してください。これにより、最終出力に markdown、_layout.json、およびレンダリングされたレイアウトオーバーレイ画像が含まれます。

CLI 戦略

• デフォルトでは画像またはページごとに 1 回の呼び出しを行ってください。
• 繰り返しの --image フラグは、結合コンテキストに真に依存するページ間または画像間の推論にのみ使用してください。
• 複数の画像を結合してではなく独立して処理すべき場合は、すべての画像を 1 つの結合リクエストとして送信するのではなく、scripts/qianfan_ocr_cli.py --batch --concurrency <N> または専用のランナーを使用してください。
• --thinking は、読み取り順序が曖昧な場合やフィールドの関係が密な難しいドキュメント理解タスクにのみ使用してください。
• 画像/ページごとに最大 1 回までリトライし、より具体的なプロンプトを使用する場合に限ってください。

必要に応じて関連するリファレンスファイルのみを読んでください。ただし、プロンプト構築の前にそのファイルを読んでください:

• references/document-parsing.md
• references/layout-analysis.md
• references/element-recognition.md
• references/document-parsing-with-layout.md
• references/general-ocr.md
• references/key-information-extraction.md
• references/chart-understanding.md
• references/doc-vqa.md

出力コントラクト

生のモデル文章ではなく、構造化された結果を返してください:

=== VISUAL ANALYSIS RESULT ===
mode: <mode>
confidence: <high|medium|low>
input_type: <image|pdf>
image_count: <N>
page_count: <N or n/a>

answer:
<direct answer or summary>

evidence:
- <directly observed fact>

warnings:
- <uncertainty or limitation>

markdown:
<for document parsing modes>

layout:
- page: <n>
  category: <label>
  bbox: [x1, y1, x2, y2]

structured_data:
<for key information extraction / chart understanding>

recognized_elements:
<for element recognition>
=== END VISUAL ANALYSIS ===

保守性のルール

• 観察と推論を分離します。
• テキスト、値、フィールド、ボックスを決して捏造しないでください。
• 判読できない領域は明示的にマークしてください。
• グラフについては、正確な値と推定値を区別してください。
• PDF の場合は、ページの帰属を明示的に保ってください: page_1、page_2 など。
• ページ変換や画質が不十分な場合は、warnings でその旨を言及してください。