Claudeエージェント向けのより高速で低コストなPDF解析スキルの構築：LiteParseのケーススタディ

このブログ記事では、評価、トレース分析、反復によって、LiteParse文書解析スキルをClaudeエージェント向けに、より安く、速く、高品質なヘルパーに改善した方法を詳しく説明します。

セットアップ

pdfQA-Benchmark ClimateFinanceBenchデータセットを使用し、30の企業サステナビリティ/ESGレポートPDFと注釈付き質問応答ペアをダウンロードしました。次に、Claude Agent SDKを介して15の（PDF、質問）ペアに対してClaudeエージェントを実行しました。各実行で構造化JSON回答と完全なJSONL相互作用トレースが生成されます。各エージェントは標準ツールにアクセスでき、評価設定に基づいて条件付きでスキルを呼び出すことができます。

比較した構成は以下の通りです：

• raw — Claudeが組み込みのReadツールでPDFを直接読み取ります。
• liteparse — 高速なモデルフリーPDF解析のためのローカルlit CLIをラップしたスキルの初版。
• liteparse-targeted — より指示的な変種。ClaudeにLiteParseをより頻繁に使用させる試み。
• effective-liteparse — 評価トレースの分析に基づき、レイテンシを低減するために効果的なLiteParse使用に最適化されたスキル。

この記事は、最後のバージョンがどのように生まれたかについてです。

なぜスキルなのか？

LiteParseはコマンドラインアプリケーションまたはRust、Python、JavaScript/TypeScript用のライブラリとして使用できます。ドキュメント解析は本質的にI/Oバウンドであり、ファイルや生バイトへの直接アクセスが必要なため、LiteParseはファイルアップロードをサポートしないMCPサーバーには適していません。したがって、スキルが最も実用的な統合パターンです。使用手順をマークダウンファイルにパッケージ化してエージェントのコンテキストに注入することで、エージェントはLiteParse CLIをClaudeの組み込みPDFリーダーやPyMuPDF、pdftotextなどの代替として使用できます。CLIを使用すると、LiteParseをgrepやsedなどの標準Unixツールと簡単に組み合わせることができ、エージェントは追加のツールを必要とせずに解析出力をフィルタリング、検索、変換できます。

ただし、ツールを利用可能にするだけでは課題の一部に過ぎません。スキル命令は、エージェントが適切な場合にLiteParseを呼び出すだけでなく、効果的に使用するように注意深く設計・評価される必要があります。適切に作成されたスキルは、エージェントが文書をより速く処理し、トークンと計算コストを削減し、一般的な解析アプローチよりも高い抽出精度を達成するのに役立ちます。

アンチパターンの発見

最初の2回の評価サイクルの後、最初のスキルバージョンのJSONLトレースから、繰り返し発生する高コストのミスのクラスターを発見しました：

• 同じPDFを何度も再解析 — 最悪のトレースでは、1つの文書に対してlit parseが9回実行され、検索のたびにPDF全体を再抽出していました。
• デジタル生成PDFに対してOCRを有効化 — ほとんどのESGレポートには実際のテキストレイヤーがあり、OCRを実行するのは純粋な時間の無駄でした。
• 高DPIのページスクリーンショットをコンテキストに読み込み — 単一ページのPNGで約14万文字のコンテキストを消費し、エージェントは同じページを2回（デフォルト＋高解像度）レンダリングすることがよくありました。
• 無制限の散弾的grep — 大量のキーワード選択で1.5万〜2.5万文字を会話にダンプしていました。

これらのアンチパターンにもかかわらず、LiteParseアプローチは大きな可能性を示しました。解析はCLIを介して外部で実行されるため、Claudeのネイティブ文書リーダーの制限（現在は最大32MB、600ページ）に制約されません。実際には、これによりLiteParseは実質的に無制限の解析容量を提供し、利用可能なシステムリソースによってのみ制限されます。

そのため、effective-liteparseスキルを作成し、修正をハードルールとしてエンコードしました：解析は1回だけ行い一時ファイルに保存、その後ファイルを検索；デジタル生成PDFには--no-ocr；スクリーンショットは最後の手段としてのみ、1ページ、適度なDPI；結果を小さく保つ。

強化されたルールに加えて、Claudeエージェントが解析コンテンツ内で適切なコンテキストを見つけるためにgrep、sed、Readを何度も密接に反復することが多いことに気付きました。そのため、スキルの表面を拡張し、提供された内容に基づいて同時に読み取り、チャンク化、インデックス作成、BM25ベースの検索を実行する自己完結型のPythonスクリプトを含めました。スキル内で、より曖昧なキーワードを検索する際にはこのスクリプトを使用し、パターン/部分文字列検索にはデフォルトで語彙検索を使用するよう指示しました。

解析するが、脇道にそれない

最初の修正後、トレースの分析で新たなシグナルが際立ちました：effective-liteparseはraw Claude Codeより安価でしたが遅く、その原因は解析自体ではなくターン数でした。解析後に最も呼ばれたツールはgrepとsedで、直列ループ（grep→確認→grepを改良→sedでウィンドウを読み取り→再度grep）で使用され、各ターンが完全なAPIラウンドトリップでした。皮肉なことに、以前のルールのうち2つがこれを悪化させていました：「まず位置を特定し、次にsedでウィンドウを読み取る」はすべての検索を2ターンに分割し、「散弾的検索をしない」はモデルを多数の小さな直列grepに誘導しました。

そこで、ラウンドトリップを最小化するようガイダンスを変更しました：

• 同じコマンドでコンテキストを取得 — grep -n -i -C4 "term" で一致とそのウィンドウを1ターンで返し、後続のsedを不要に。
• 独立した検索を1つのコマンドにバッチ処理 — ラベル付きforループで複数の事実を一度にプローブ。
• ハードな検索予算 — 最大3コマンドで解決；2回のgrepが失敗したら、キーワードのバリエーションを無限に発射する代わりに、BM25ランカーを1回使用。

トレースは新しい行動を確認しました：解析後のツールミックスにforループのバッチパターンが現れ、平均ターン数が約15%減少（13.1→11.1）。

数字

LLM-as-judgeパネル（GeminiとGPT）で回答をスコアリングし、トレース分析で効率を測定しました。15問のマッチしたサブセットでの結果：

品質（LLM-as-judge、平均スコア、高いほど良い）：

| 指標 | raw | effective-liteparse | |------|-----|--------------------| | 全体的な回答 | 46.47 | 56.67 | | 全体的な推論 | 58.47 | 65.90 | | Gemini回答 | 58.53 | 78.33 | | Gemini推論 | 71.33 | 86.00 | | GPT回答 | 34.40 | 35.00 | | GPT推論 | 45.60 | 45.80 |

効率（トレース指標）：

| 指標 | raw | effective-liteparse | |------|-----|--------------------| | 1問あたりの平均コスト | $0.751 | $0.474（-37%） | | p95コスト | $1.323 | $0.746 | | 平均ターン数 | 8.47 | 11.08 | | 平均ターン時間 | 6.5秒 | 5.6秒（-14%） |

トークン使用量：

| 指標（実行あたり平均） | raw | effective-liteparse | |----------------------|-----|--------------------| | ベース入力トークン | 23 | 17 | | キャッシュ書き込み（5分）トークン | 86,666 | 29,623 | | キャッシュ読み取りトークン | 214,924 | 354,330 | | 出力トークン | 2,433 | 3,546 | | 総入力トークン | 301,612 | 383,970 | | コスト - キャッシュ書き込み（5分） | $0.542 | $0.185 | | コスト - キャッシュ読み取り | $0.107 | $0.177 | | コスト - 出力 | $0.061 | $0.089 | | 平均コスト（報告） | $0.751 | $0.452 |

このスキルは1問あたり37%安く、すべての評価指標で高いスコアを獲得しました。全タスクの所要時間はまだ数秒遅いですが、ターン時間は速くなり、より多くの反復が可能になりました。

トークン使用量に関する注意

一見すると、effective-liteparseバリアントはトークン使用量でより高価に見えます：実行あたり平均約384kの入力トークンに対して、rawベースラインは約302kです。しかし、その主要な数字は誤解を招きます。なぜなら、入力カテゴリをまとめており、課金方法が大きく異なるからです。入力を課金カテゴリ別に分解すると、状況は逆転します：liteparseの余分なボリュームは圧倒的にキャッシュ読み取り（割引レート$0.50/MTokで課金）であり、高価な部分であるキャッシュに書き込まれる新しいコンテンツ（$6.25/MTok）は、ベースラインの約3分の1（29.6k対86.7kトークン）です。rawアプローチは読み取りのたびに大きなPDF画像ページを再キャッシュしますが、liteparseはドキュメントをローカルで解析し、コンパクトなテキストをフィードバックするため、高価なキャッシュ書き込みが劇的に減少し、安価なキャッシュ読み取りが増加します。正味の効果として、liteparseは全体でより多くのトークンに触れるにもかかわらず、約40%低いコスト（平均$0.45対$0.75）で動作します。

コストは公開されているClaude Opus 4.7の料金レート（$5ベース入力/$6.25 5分キャッシュ書き込み/$10 1時間キャッシュ書き込み/$0.50 キャッシュ読み取り/$25出力、MTokあたり）を使用しています。報告されたコストはランタイムのtotal_cost_usdです；カテゴリ別の派生合計との小さな差は、トップレベルの使用記録が省略した二次的なHaiku呼び出しによるものです。

教訓

• トレースが真実です。すべての改善は、エージェントが実際に何をしたかを読み取ることから生まれました。
• スキルガイダンスには二次的効果があります。「位置を特定してから読み取る」や「散弾的検索をしない」は慎重に聞こえますが、それぞれラウンドトリップを追加しました。コマンドごとの整頓ではなく、総ターン数を最適化してください。
• ハーネスとスキルを分離してください。最大のコスト数値はハーネスのアーティファクトであり、スキルのプロパティではありません。帰属する前に注意深く測定してください。
• ここでは、より安くてより良いことはトレードオフではありません。規律あるローカル解析は、コストと回答品質の両方で生のPDF取り込みを上回りました。

完全なベンチマークは https://github.com/run-llama/benchmark-claude-pdfs で入手および再現可能です。