FAQ

pdfvision は PDF-to-text ツールですか、それとも vision ツールですか？

両方ですが、中心にあるのは証拠です。pdfvision は利用できるネイティブテキストを抽出し、そのうえでレイアウト、画像/ベクターのジオメトリ、警告、レンダリング画像、OCR、検索一致、PDF 機能メタデータを公開します。エージェントは、それらを見てテキストだけで十分かどうかを判断できます。

抽出テキストが空になるのはなぜですか？

スキャン、画像中心、暗号化、独自グリフエンコーディングなどが原因です。概要フィールドと pages[].warnings を確認し、--render, --ocr, --layout を試してください。

ページに empty_but_visual_content がある場合は、レンダリングまたは OCR が必要です。グリフ関連の警告がある場合は、ネイティブテキストを信頼する前にレンダリング画像や OCR と比較してください。

--layout はいつ使いますか？

段組み、表、フォーム、脚注、繰り返しヘッダーやフッター、縦書き CJK、配置で意味が変わるページで使います。

--layout は、論文、レポート、財務諸表、フォーム、スライド書き出しのように、raw text stream が視覚順とずれる可能性がある PDF で特に有効です。

OCR はいつ使いますか？

ネイティブテキストが無い、少ない、スキャン風、またはレンダリング画像と明らかに違う場合に使います。

OCR はネイティブテキストの横に追加され、置き換えません。エージェントはネイティブテキスト、OCR テキスト、confidence、警告を比較するべきです。

ページ全体ではなく領域だけをレンダリングするのはいつですか？

検索、レイアウト、画像 bbox、ベクター bbox、visual regions で重要な領域を特定した後に --render-region を使います。1 つの条項、表のセル、グラフラベル、フォーム値、図だけを検証したい場合は、ページ全体よりクロップのほうが適しています。

visual regions とは何ですか？

visual regions は、図、グラフ、表、フォームセクション、注釈、ダイアグラム、ラスター/ベクターのまとまりを含む可能性が高い、クロップ可能なページ領域です。画像を vision model に送る前に、エージェントがどこを見るべきかを見つける助けになります。

pdfvision は PDF を検索できますか？

はい。--search は pages[].matches[] にページ、source、一致テキスト、前後文脈、利用可能な bbox を出力します。検索対象には、ネイティブテキスト、表示されるフォームフィールド値、FreeText 注釈、OCR 有効時の OCR テキストを含められます。

座標系はどうなっていますか？

bbox は PDF user-space points で、左上が原点です。x は右、y は下に増えます。

キャッシュはどこにありますか？

OS の一時ディレクトリ配下に保存されます。PDFVISION_CACHE_DIR=/path で変更でき、--no-cache で無効化、pdfvision --clear-cache で削除できます。

PDF パスワードはどう渡すべきですか？

プロセス引数に残らないよう --password-stdin を優先してください。

printf "your-password\n" | pdfvision encrypted.pdf --password-stdin --format json

どの出力形式を使うべきですか？

素早く人間が読む確認には Markdown、ツールやエージェント制御には JSON、タグ指向のプロンプトには XML、構造化出力が大きくトークン予算が厳しい場合には TOON を使います。