【検証】AIのAPI代は本当に減らせる？コンテキスト圧縮ツール「Headroom」を導入して実測してみた

こんにちは、七宮さん(@shichinomiya_s)です。

Claude CodeやCursorのようなAIエージェントを使っていると、地味に効いてくるのがトークン代。ログを読ませたり、巨大なJSONを返させたり、ファイルを丸ごと読ませたりするたびに、コンテキストがどんどん膨らんでAPI料金が積み上がっていきます。

そんな中で見つけたのが、「AIエージェントが読むコンテキストを60〜95%圧縮する」と謳うOSS、Headroom。本当にそんなに減るの？品質は落ちないの？というわけで、実際に自分のMacに導入して、ログ・JSON・コード・RAGの4種類のデータで圧縮率を実測してみました。

結論から言うと、「魔法のように何でも95%オフ」ではないが、嵩むデータは確かにガッツリ減る。今回の実測ではコードが79.8%、JSONが59.2%、ログが31.0%削減。多段ツール呼び出しのデバッグセッション全体では47.5%（約2.8万トークン）削減できました。一方で、自然文（RAG文書）は既定では圧縮されないなど、クセもあります。数字とあわせて正直にレビューします。

Headroomとは何か — 「AIが読むもの」を圧縮する

Headroomは、AIエージェントが処理するあらゆる入力（ツール出力・ログ・RAGチャンク・ファイル・会話履歴）をLLMに送る前に圧縮するツールです。Python（とRust）で書かれており、LLMプロバイダー（Anthropic / OpenAI / Bedrockなど）に依存しません。

ポイントは「ただ削るだけ」ではないこと。複数の専用コンプレッサーをパイプラインで組み合わせ、データの種類に応じて圧縮方法を切り替えます。

• SmartCrusher — JSONや構造化データを圧縮
• CodeCompressor / Kompress — AST（構文木）を理解したコード圧縮
• CacheAligner — プロバイダーのKVキャッシュヒット率を最適化
• CCR（Compress-Cache-Retrieve） — 圧縮前のオリジナルをローカル保存し、必要なときだけheadroom_retrieveツールで取り出せる可逆圧縮

使い方は4通り。①ライブラリ（compress()を呼ぶ）、②プロキシ（localhost:8787に挟むだけのゼロコード導入）、③CLIラップ（Claude Code / Cursor / Aiderに直接統合）、④MCPサーバー。今回は再現性の高い①ライブラリで定量計測し、②プロキシも触ってみました。

導入してみる — pip一発、ただし依存は重い

動作要件はPython 3.10以上。今回はmacOS（Apple Silicon）にPython 3.11の仮想環境を作って入れました。

python3.11 -m venv venv
source venv/bin/activate
pip install "headroom-ai[all]"

コマンド自体は一発ですが、[all]を付けるとPyTorch・Transformers・onnxruntime・sentence-transformersなど機械学習系の依存がごっそり入ります。インストールされたパッケージは200個以上、pipキャッシュは2GB超。回線によっては数分〜十数分かかるので、ここは覚悟しておきましょう。導入されたバージョンはheadroom-ai 0.22.3でした。

ライブラリの使い方はシンプルで、メッセージ配列を渡すだけです。

from headroom import compress

result = compress(messages, model="claude-sonnet-4-5")
print(result.tokens_before, "->", result.tokens_after)
print(f"{result.compression_ratio:.1%} 削減")
# 圧縮済みメッセージは result.messages に入る

検証環境

テストデータは機密を含まない汎用ダミーを決定論的に生成しました。AIエージェントが実際に「読まされる」典型として、次の4種類を用意しています。

• ログ — 冗長なアプリ/サーバーログ（約2.5万トークン）
• JSON — 大きめのREST APIレスポンス（約3.3万トークン）
• コード — Pythonソースコード
• RAG文書 — 技術ドキュメントの断片集（約1.2万トークン）

そして重要なのが、これらを「ツール結果（tool result）」としてエージェントの会話に渡した点。Headroomは「いま進行中のタスク（最新のユーザー発言）」は壊さないよう保護し、嵩んだツール出力を狙って圧縮する設計だからです（後述）。

検証結果① データ種別ごとの削減率

まずは4種類を個別に圧縮した結果（Claude Sonnet・デフォルト設定）。構造化されていて冗長なデータほど、よく縮みます。

圧巻はコードの79.8%。AST（構文木）を理解したkompressが効いて、877トークンが177トークンまで凝縮されました。JSONも約6割減、ログも3割減と、エンジニアが普段エージェントに読ませがちなデータほど効果が大きいのは嬉しいポイントです。

一方でRAG文書（自然文）は0%、まったく圧縮されませんでした。これはバグではなく仕様で、Headroomは意味が壊れやすい自然文プロースを既定では保護し、構造的な冗長性がある（=安全に縮められる）データを優先して圧縮します。「何でも縮む」わけではない、という正直なところです。

検証結果② デバッグセッション全体ではどうなる？

個別データだけでなく、実際の調査フローを1本の会話として再現してみました。「タイムアウトが多発→ログ取得→API状態確認→コード確認→原因特定」という、複数のツールを順に呼ぶよくあるパターンです。

結果は59,742トークン → 31,358トークン、47.5%削減（約2.8万トークン節約）。会話の中で積み上がった3つのツール結果（ログ・JSON・コード）がそれぞれ圧縮され、最新のユーザー質問とアシスタントの推論テキストはしっかり保持されていました。長い調査セッションほど、この効果は効いてきます。

検証結果③ 品質は保たれるのか・処理は重くないのか

「圧縮で大事な情報が消えたら本末転倒」なので、圧縮後のテキストにキーワードが残っているかを確認しました。

• ログ → 根本原因のTimeoutErrorは圧縮後も残存 ✅
• JSON → 特定ユーザーのemail値は残存 ✅
• RAG → キーワードKubernetesは残存（そもそも素通り）✅
• コード → kompressで別表現に変換されるが、CCRがオリジナルを保存し、LLMはheadroom_retrieveで必要時に全文を取り戻せる（可逆）

処理時間（レイテンシ）も計測しましたが、1回の圧縮は1ms以下〜数十ms程度。LLMの応答時間（秒単位）に比べれば事実上ゼロで、ここで詰まる心配はなさそうです。

検証結果④ 結局いくら浮くのか — コスト試算

削減トークンを実際の料金で円換算してみます。「エージェントが1日100回、今回のような文脈を読む（月3,000回）」と仮定し、入力料金（Claude Sonnet $3 / Opus $15 / GPT-4o $2.5・各100万トークンあたり、1ドル=157円）で計算しました。

あくまで仮定の試算ですが、高単価なOpusを多用するなら月20万円規模の節約もあり得る計算。エージェントをヘビーに回す現場ほど、効いてくるのが分かります（実際には出力トークンやキャッシュも絡むので、目安として捉えてください）。

「ゼロコード導入」のプロキシも触ってみた

ライブラリ以外に、既存のコードを一切変えずに挟むだけのプロキシ方式もあります。起動コマンドは1行です。

headroom proxy --port 8787

# Claude Code から使う場合
ANTHROPIC_BASE_URL=http://127.0.0.1:8787 claude
# OpenAI互換クライアントの場合
OPENAI_BASE_URL=http://127.0.0.1:8787/v1 your-app

起動すると、Anthropic / OpenAI / Google へのルーティング、token（圧縮優先）／cache（プレフィックスキャッシュ優先）の2モード、ヘルスチェックやPrometheusメトリクスのエンドポイントまで、しっかり用意されているのが確認できました。サブスク勢（API未契約）向けには、headroom mcp installでClaude CodeにMCPサーバーを入れ、headroom_retrieveで圧縮内容を取り戻す使い方も用意されています。

なお正直にお伝えすると、今回の筆者の環境ではプロキシが待受ポートを開かず、E2E（実際のAPI転送）までは検証できませんでした（APIキー未設定だったこともあり）。ただ、プロキシもライブラリと同じ圧縮エンジンを内部で使うため、本記事の削減率はそのまま当てはまると考えてよいでしょう。導入の手軽さ重視ならプロキシ、確実性重視ならライブラリ、という棲み分けです。

仕組みのキモ — 「最新は守り、嵩むものを削る」

実測中にいちばん納得したのが、Headroomのルーターの賢さです。デフォルトでは、

• ユーザーの最新メッセージ・直近のコンテキストは保護（進行中タスクを壊さない）
• 積み上がったツール結果や古い文脈を狙って圧縮

という挙動になっています。試しに「全部圧縮する（compress_user_messages=True, protect_recent=0）」設定にすると、保護されていたデータも圧縮され、JSONは単体で約52%削減できました。安全性を取るか圧縮率を取るか、設定で振れるのは実用的です。

向いている用途・注意点

向いている人：

• Claude CodeやCursorで大きなログ・JSON・コードを頻繁に読ませる人
• API課金でエージェントをヘビーに回していて、トークン代を本気で削りたい人
• 長い調査・デバッグセッションでコンテキストが膨らみがちな人

注意点：

• 依存が重い（ML系で2GB超）。お手軽ツールではない
• 自然文/RAGプロースは既定では圧縮されない（意味保持を優先）
• プロキシ方式は環境によって動作確認が必要（筆者環境では待受せず）
• 効果はデータの種類に強く依存。構造化・冗長なデータほど効く

まとめ

「トークンを95%削減」というキャッチコピーだけ見ると盛っているように感じますが、実際に測ってみると「狙った種類のデータは確かに大幅に縮む」ことが分かりました。

• コード79.8% / JSON59.2% / ログ31.0%削減（Claude Sonnet・デフォルト・実測）
• 多段デバッグセッション全体で47.5%削減（約2.8万トークン）
• 重要情報は保持され、コードはCCRで可逆
• 圧縮の処理オーバーヘッドは事実上ゼロ
• 自然文は既定で素通り。万能ではないが、ツボにハマると強い

AIエージェントをAPI課金でガンガン使っていて「トークン代が地味に痛い」という人は、一度ライブラリ版で自分のワークロードを測ってみる価値は十分にあります。導入はpip install "headroom-ai[all]"の一発。OSSなので無料で試せます。