Claude Code + LiteLLM + Gemini API：コンテキストキャッシュを活用したAPIコスト最適化の実践

はじめに

近年、Claude Codeをはじめとする自律型AIコーディングエージェントの活用が進んでいます。これらのツールはプロジェクトのファイル群や会話履歴など、膨大なコンテキストをLLMに送信することで精度の高いコーディング支援を実現します。しかし、コンテキスト量に比例してAPIの利用コストが高騰しやすいという課題があります。

本記事では、プロキシサーバーである「LiteLLM」を介して「Gemini API（Gemini 3 Flash / 3.1 Pro等）」をバックエンドとして利用し、Geminiのコンテキストキャッシュ（Context Caching）を有効活用することで、APIコストを劇的に削減した事例と具体的な設定手順をご紹介します。

アーキテクチャと目的

今回の検証環境は以下の通りです。

  • クライアント: Claude Code (Anthropic仕様のAPIリクエストを発行)
  • プロキシ: LiteLLM (Anthropic仕様をGemini仕様へ変換・ルーティング)
  • LLMバックエンド: Gemini API (今回は gemini-3-flash-preview などを利用)

目的: Gemini APIには、一定の条件（2,048トークン以上で、プロンプトの先頭が完全一致すること）を満たすと自動的に適用される「暗黙的キャッシュ（Implicit Caching）」という仕組みがあります。キャッシュにヒットした場合、入力トークンの料金が通常価格の10分の1（90%オフ）となるため、この仕様をClaude Code上で確実に機能させることを目指しました。

課題：LiteLLMのログが示す「cache_hit=False」

構築の過程で一つの躓きがありました。LiteLLMのデバッグログを有効にしてClaude Codeからリクエストを送信したところ、以下のようなログが出力されました。

Logging Details LiteLLM-Async Success Call, cache_hit=False
Async success callbacks: Got a complete streaming response

一見すると「Geminiのキャッシュが効いていない」ように見えます。しかし、これはLiteLLM自身の内部キャッシュ（過去のレスポンスの使い回し機能）の状態を示しているに過ぎず、Gemini API側のコンテキストキャッシュの成否を示すものではありませんでした。

さらに、Claude Codeはストリーミング通信を行うため、ターミナルのログだけでは正確なトークン使用量やキャッシュのヒット状況を把握するのが困難でした。

解決策：適切なLiteLLM設定とAI Studioでの確認

Gemini側のキャッシュを確実に機能させ、エラーを防ぐために、LiteLLMの config.yaml を以下のように最適化しました。

model_list:
  - model_name: claude-sonnet-4-6
    litellm_params:
      model: gemini/gemini-3-flash-preview
      api_key: "os.environ/GEMINI_API_KEY"
      max_tokens: 65536
      temperature: 0.0 # 1. キャッシュヒット率を安定させるため固定
      safety_settings: # 2. コード実行時の誤ブロックを防止
        - category: HARM_CATEGORY_HARASSMENT
          threshold: BLOCK_NONE
        - category: HARM_CATEGORY_HATE_SPEECH
          threshold: BLOCK_NONE
        - category: HARM_CATEGORY_SEXUALLY_EXPLICIT
          threshold: BLOCK_NONE
        - category: HARM_CATEGORY_DANGEROUS_CONTENT
          threshold: BLOCK_NONE

litellm_settings:
  drop_params: true # 3. Anthropic特有のパラメータを適切に処理
  set_verbose: true
  num_retries: 2

設定のポイント

  1. temperature の固定: Geminiのキャッシュは「リクエスト条件の完全一致」を好むため、パラメータを固定することでキャッシュミスを防ぎます。
  2. safety_settings の緩和: コーディングエージェントはシステムコマンドやファイル操作を行うため、これらが誤って安全フィルターにブロックされないよう調整します。
  3. drop_params: true: Claude Codeが送信するAnthropic固有のキャッシュコントロールタグ（ephemeral など）をLiteLLM側で適切に無視し、Gemini APIでのエラーを回避します。

効果測定：APIコストを約88%削減

上記の設定後、Google AI Studioのダッシュボードにて実際のAPI使用量を確認しました。結果は以下の通りです。

  • Input tokens (全体入力): 33,097
  • Cached content tokens (キャッシュヒット): 32,441
  • Uncached content tokens (新規入力): 656

実に約98%のトークンがコンテキストキャッシュから読み込まれていました。

これを実際のAPI利用料金（Gemini 3 Flash-preview の入力単価を、通常時 $0.50 / 100万トークン、キャッシュ適用時 $0.05 / 100万トークンとして算出）に換算すると、コストの差は歴然となります。

  • キャッシュなしの場合の想定コスト: 33,097 tokens × $0.50 / 1M = 約 $0.0165
  • 今回の実際のコスト: (キャッシュ分 32,441 × $0.05 / 1M) + (新規分 656 × $0.50 / 1M) = 約 $0.00195

約3.3万トークンのリクエストに対して、通常の約1/8以下（約88%のコスト削減）での推論を実現できました。試行錯誤を繰り返し、塵も積もれば山となるエージェント開発時のAPIコールにおいて、この削減効果は非常に絶大です。

Claude Codeは「プロジェクトの全体像やツール定義」をプロンプトの先頭に配置し、「ユーザーの最新の質問」を末尾に追加する構造をとっています。このアーキテクチャが、Geminiの「プロンプト前方一致」を条件とするキャッシュ仕様と完璧に噛み合った結果と言えます。

まとめ

Claude CodeとLiteLLM、そしてGemini APIの組み合わせは、設定に少しの工夫が必要ですが、一度構築してしまえば非常に強力かつ経済的なAI開発環境となります。

「プラットフォーム側（Google AI Studio）のメトリクスで真のトークン消費を確認する」というアプローチは、LLMルーティングツールを活用する上で重要な知見となりました。大規模なコードベースを扱うチーム開発において、本構成はコストパフォーマンスを最大化する有力な選択肢となるでしょう。

おまけ：Claude Sonnet 4.6とGemini 3のキャッシュ機能比較

Claude CodeはAnthropic社のClaude Sonnet 4.6などの純正モデルを利用することを前提に設計されています。Sonnet 4.6にも「プロンプトキャッシング（Prompt Caching）」という強力な機能が備わっており、最新バージョンではキャッシュの保持時間（TTL）を柔軟に設定できるようになりました。

では、LiteLLMを介してGeminiにルーティングする構成と、純正のSonnet 4.6を利用する構成では、どのような違いがあるのでしょうか。両者の仕様と価格感を公平に比較してみましょう。（価格は一般的なクラウドAPIの提供価格に基づく比較用モデルです）

項目Gemini 3 Flash-previewClaude Sonnet 4.6
通常入力料金$0.50 / 1M tokens$3.00 / 1M tokens
キャッシュ作成 (Write)$0.50 / 1M tokens (割増なし)$3.75 / 1M tokens (25%割増)
キャッシュ読取 (Read)$0.05 / 1M tokens$0.30 / 1M tokens
キャッシュ有効期限 (TTL)暗黙的:自動 / 明示的:1時間〜設定により柔軟に変更可能
  1. コスト構造の違い
    Gemini 3 Flash-previewはベースとなる単価が安価に設定されており、暗黙的キャッシュを利用する限り、最初のキャッシュ作成（Write）時に割増料金が発生しないのが特徴です。一方、Sonnet 4.6はキャッシュ作成時に通常料金の25%割増となりますが、読み取り（Read）料金は通常時の10分の1まで下がるため、一度キャッシュに乗せてしまえば高度な推論結果を効率的かつ安価に使い回せるというメリットがあります。
  2. 保持時間（TTL）と管理方式
    Sonnet 4.6ではTTLが設定変更可能となったことで、数分間の短期タスクから、数時間にわたる長期の開発セッションまで、プロジェクトの要件に合わせて柔軟にキャッシュ寿命をコントロールできるようになりました。対するGeminiは、システム側で自動管理される「暗黙的キャッシュ（ストレージ無料）」と、APIで時間を指定してコンテキストを固定する「明示的キャッシュ（1時間あたり保存料発生）」の2つのアプローチが用意されています。
  3. どちらを選ぶべきか
    ・Sonnet 4.6が適しているケース:
    Claude Codeのネイティブなツール連携能力や、最高峰の推論能力が必要な場面。TTLが柔軟に設定できるため、複雑なリファクタリングやアーキテクチャ設計など、高度な思考が連続するタスクにおいて強力なパフォーマンスを発揮します。
    ・Gemini 3 Flash-previewが適しているケース:
    コストパフォーマンスを最優先しつつ、広大なコンテキストを扱いたい場面。ベース単価の安さを活かし、巨大なリポジトリの全コードや大量のログを日常的に読み込ませるようなタスクに適しています。

結論

どちらか一方が絶対的に優れているというわけではなく、用途と予算に応じた適材適所の使い分けが重要です。
　本記事で紹介したLiteLLMによるルーティング設定（エラー時や用途に応じたフォールバック機能など）を活用すれば、複雑な中核タスクはSonnet 4.6に任せ、大量のファイル探索や日常的なコーディング支援はGemini 3に任せるといった、両者の強みを活かしたハイブリッドな開発環境を構築することも可能です。

タイトルとURLをコピーしました