使い方

このページではよく使うコマンドパターンをまとめます。未知の PDF では、まず構造化された初回パスを取り、ページ overview を見てから、根拠が必要な箇所にだけレイアウト、レンダリング、OCR、検索、視覚領域を追加します。

推奨される初回パス

pdfvision document.pdf --json

この出力で次を判断します。

• どのページに使えるネイティブテキストがあるか。
• どのページが視覚的、スキャン風、または glyph-corrupted か。
• どのページに警告があるか。
• どのページにレイアウト復元、OCR、レンダリングクロップが必要か。

ローカル PDF

pdfvision document.pdf

リモート PDF

pdfvision --remote https://example.com/document.pdf --format json

リモート PDF はキャッシュされ、PDF として検証されてから抽出されます。URL が HTML、ログインページ、チャレンジページを返す場合はキャッシュ前に失敗します。

--remote は最初の URL として HTTP(S) のみ受け付け、リダイレクトを追跡し、レスポンス本文の先頭付近に PDF ヘッダーがない場合は拒否します。既定の制限は、本文が最大 100 MB、レスポンスヘッダーの待機と本文の転送を対象とする期限が 60 秒です。

--remote は、ユーザーが別途許可した接続先にだけ使ってください。レスポンスは検証しますが、接続先そのものは検証せず、プライベートアドレスやリダイレクト先も遮断しません。信頼できない URL は直接渡さず、解決された各 IP とリダイレクト先を許可リストで検証して接続先を固定できる fetcher で取得し、ローカルファイルとして pdfvision に渡してください。または、pdfvision の取得処理をネットワーク制御の内側に隔離してください。詳しくはセキュリティとプライバシーを参照してください。

リモートキャッシュは URL ごとに管理されます。安定した URL の中身が差し替えられる場合は、1 回だけ新しく取得するなら --no-cache、キャッシュを消すなら --clear-cache を使います。

pdfvision --remote https://example.com/document.pdf --no-cache --format json

ページ範囲

pdfvision document.pdf --pages 1-3
pdfvision document.pdf --pages 1,3,5 --format json

ページ範囲は 1 始まりの物理ページ番号です。カンマで複数の指定を組み合わせ、範囲は両端を含み、重複ページはソートされた出力にまとめられます。

有効な例:

• 1
• 1-5
• 1,3,5
• 2-4,7

空の区切り、0、負数、5-3 のような降順範囲、不正な範囲は推測せずにエラーになります。指定に文書末尾を超えるページが含まれていても、実在ページが 1 つ以上選ばれていれば、そのページを抽出し、スキップされたページについて警告を出します。

ページをレンダリング

pdfvision document.pdf --render --render-output ./images --format json

--render-scale で画像の詳細度を調整できます。

pdfvision document.pdf --render --render-scale 3

レイアウトと視覚構造

pdfvision document.pdf --layout --image-boxes --vector-boxes --visual-regions --format json

レイアウトブロック、画像ボックス、ベクターボックス、視覚領域、レイアウト警告を追加します。

2 段組み論文、スライド、財務レポート、表、フォーム、グラフ、ダイアグラムなど、視覚的な配置で意味が変わるページに使います。

重要領域だけをレンダリング

pdfvision document.pdf --render-visual-regions --render-output ./regions --format json

ページ全体ではなく、図、表、フォーム、チャートなどの領域だけを確認したいときに使います。

検索してズーム

pdfvision report.pdf --search "revenue" --format json
pdfvision report.pdf --pages 3 --render --render-region 120,180,360,140 --render-output ./crops --format json

検索結果には、位置を特定できる場合に bbox が含まれます。その bbox を --render-region に渡すと、視覚確認用の小さなクロップを作れます。

回答を監査可能な PDF 根拠に結びつけたい場合に有効です。用語を検索し、該当ページと bbox を選び、必要最小限のクロップだけをレンダリングします。

スキャンページの OCR

pdfvision scan.pdf --ocr --ocr-lang eng --format json
pdfvision japanese-scan.pdf --ocr --ocr-lang jpn+eng --format json

OCR 結果にはテキスト、信頼度、言語、単語ボックスが含まれます。

OCR はネイティブテキストの横に付与されます。pages[].text を置き換えないため、エージェントはネイティブ抽出と OCR を比較して、どちらの根拠を信頼するか判断できます。

フォーム、リンク、注釈

pdfvision form.pdf --layout --form-fields --annotations --links --format json

PDF にウィジェット値、チェックボックス、ラジオグループ、見えるコメント、リンク、またはページ上の位置に依存するフォームラベルが含まれる場合に使います。

アウトライン、ページラベル、文書機能

pdfvision document.pdf -p 1 --page-labels --outline --viewer --layers --format json

物理ページ番号と異なるページラベル、しおり、open action、optional content layer、viewer preference など、PDF viewer での見え方が意味を持つ場合は、このコマンドで確認します。ここでの -p 1 はページ抽出と出力だけを先頭ページに限定し、文書全体の読み込み・解析・実行時間まで限定するものではありません。指定しなければ、文書機能フラグは全ページを抽出します。文書レベルのフィールドは引き続き取得できます。ページ単位の JavaScript action は選択したページについてだけ返されるため、必要なら対象範囲を指定して --viewer を再実行してください。

暗号化 PDF

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

パスワードをシェル履歴やプロセス引数に残したくない場合は --password-stdin を優先してください。

キャッシュ制御

pdfvision document.pdf --no-cache --json
pdfvision --clear-cache

pdfvision は抽出結果、レンダリング画像、リモートダウンロード、OCR データをキャッシュし、エージェントが同じ PDF を繰り返し読むときの待ち時間を減らします。抽出結果とリモート PDF のバイト列をキャッシュしたくない場合は --no-cache、キャッシュ削除には --clear-cache を使います。

アプリケーション側でキャッシュ場所を固定したい場合は、専用ディレクトリを指す空でない絶対パスを PDFVISION_CACHE_DIR に設定します。相対パス、~、ファイルシステムのルート、ホームディレクトリ、作業ディレクトリ、共有の一時ディレクトリは拒否されます。

PDFVISION_CACHE_DIR=/secure/pdfvision-cache pdfvision document.pdf --json

所有者確認済みの .pdfvision-cache-root マーカーが再帰削除を許可します。--clear-cache がマーカーのないカスタムルートを採用することはありません。PDFVISION_CACHE_DIR が未指定のときに使われる従来の既定ルートだけは、認識済みの旧形式形状を権限強化の前後に走査してから採用できます。通常利用でも、すべてのマーカーなしルートに同じ走査を行います。POSIX では、group/other が書き込めるマーカーなしルートを拒否し、すべての祖先が読み取り・open 可能で、現在のユーザーまたは root の所有かつ書き込み不可または安全な sticky 状態であることを求めます。quarantine への移動後は st_dev を比較し、不一致なら再帰削除を拒否しますが、元のパスはすでに移動しており、同一 device の bind mount は検出できません。同一性確認が置き換えに耐えられるのは通常の POSIX mode semantics の範囲です。ACL やネットワークファイルシステムの権限は検査せず、最終確認後の root または同一 UID による置き換えも排除できません。Windows の置き換え耐性は best effort です。キャッシュ削除は実行中の OCR と協調しないため、中断された OCR は再実行してください。

--no-cache は抽出キャッシュとリモート PDF キャッシュをスキップしますが、--render-output を指定しないレンダリング PNG は OS の別の一時パスを使い、明示的な出力先は引き続き指定どおりに使われます。--ocr は検証済みキャッシュルート配下に traineddata と worker support files を永続化します。そのため、不正な PDFVISION_CACHE_DIR を指定した OCR 実行は、--no-cache を併用しても失敗します。

リモート PDF では、--no-cache はリモート PDF キャッシュもスキップし、新しくダウンロードしたバイト列を直接抽出に渡します。非公開または期限付きの URL では、ダウンロードした PDF のバイト列を残さずに済みます。同じ URL の内容が変わる場合にも再取得を強制しますが、許可されていないネットワーク接続先が安全になるわけではありません。