gemini-token-optimization

Gemini のトークン最適化

🚨 必須：最初に gemini-cli-docs を呼び出す

停止 — Gemini のトークン使用量について回答する前に、必ず次の手順を実行してください：

1. gemini-cli-docs スキルを呼び出す
2. 該当するトークンまたは料金のトピックを検索する
3. 読み込んだ公式ドキュメントのみに基づいて回答する

概要

Gemini CLI に処理を委任する際のコストとトークン使用量を最適化するスキルです。効率的な一括操作と、コストを意識したワークフローに不可欠です。

このスキルを使用するタイミング

キーワード： トークン使用量、コスト最適化、Gemini のコスト、モデル選択、Flash と Pro の比較、キャッシュ、一括クエリ、トークン削減

次の場合にこのスキルを使用します：

• Gemini の一括操作を計画する場合
• 大規模な分析のコストを最適化する場合
• Flash モデルと Pro モデルのどちらを使うか選ぶ場合
• トークンキャッシュのメリットを把握する場合
• セッション間の使用状況を追跡する場合

トークンキャッシュ

Gemini CLI は、以前に処理したコンテンツを再利用してコストを抑えるため、コンテキストを自動的にキャッシュします。

利用可能な認証方式

認証方式	キャッシュの利用可否
API キー（Gemini API）	はい
Vertex AI	はい
OAuth（個人／エンタープライズ）	いいえ

仕組み

• システム指示と繰り返し使用するコンテキストがキャッシュされます
• キャッシュされたトークンは課金対象になりません
• /stats コマンドまたは JSON 出力で節約額を確認できます

キャッシュヒットを最大化する

1. 一貫したシステムプロンプトを使用する — 同じプレフィックスを使うとキャッシュを再利用しやすくなります
2. 類似したクエリをまとめる — 関連する分析をまとめて実行します
3. コンテキストファイルを再利用する — 同じファイルを同じ順序で使用します

キャッシュ使用量を監視する

result=$(gemini "query" --output-format json)
total=$(echo "$result" | jq '.stats.models | to_entries | map(.value.tokens.total) | add // 0')
cached=$(echo "$result" | jq '.stats.models | to_entries | map(.value.tokens.cached) | add // 0')
billable=$((total - cached))
savings=$((cached * 100 / total))

echo "Total: $total tokens"
echo "Cached: $cached tokens ($savings% savings)"
echo "Billable: $billable tokens"

モデル選択

モデルの比較

モデル	コンテキストウィンドウ	速度	コスト	品質
gemini-2.5-flash	大	高速	低い	良好
gemini-2.5-pro	非常に大きい	低速	高い	最高

選択基準

次の場合は Flash（-m gemini-2.5-flash）を使用します：

• 大きなファイルを処理する場合（一括分析）
• 単純な抽出タスク
• コストを最優先する場合
• 速度が重要な場合
• タスクが単純な場合

次の場合は Pro（-m gemini-2.5-pro）を使用します：

• 複雑な推論が必要な場合
• 品質が重要な場合
• 綿密な分析が必要な場合
• タスクに深い理解が求められる場合
• コンテキストが 1M トークンを超える場合

モデル選択の例

# Bulk file analysis - use Flash
for file in src/*.ts; do
  gemini "List all exports" -m gemini-2.5-flash --output-format json < "$file"
done

# Security audit - use Pro for quality
gemini "Deep security analysis" -m gemini-2.5-pro --output-format json < critical-auth.ts

# Cost tracking with model info
result=$(gemini "query" --output-format json)
model=$(echo "$result" | jq -r '.stats.models | keys[0]')
tokens=$(echo "$result" | jq '.stats.models | to_entries[0].value.tokens.total')
echo "Used $model: $tokens tokens"

一括処理の戦略

一括処理する理由

• API のオーバーヘッドを削減します
• キャッシュヒット率を高めます
• 一貫したコンテキストを提供します

一括処理のパターン

パターン 1：ファイルを連結する

# Instead of N separate calls
# Do one call with all files
cat src/*.ts | gemini "Analyze all TypeScript files for patterns" --output-format json

パターン 2：プロンプトをまとめて処理する

# Combine related questions
gemini "Answer these questions about the codebase:
1. What is the main architecture pattern?
2. How is authentication handled?
3. What database is used?" --output-format json

パターン 3：段階的に分析する

# First pass: Quick overview with Flash
overview=$(cat src/*.ts | gemini "List all modules" -m gemini-2.5-flash --output-format json)

# Second pass: Deep dive critical areas with Pro
echo "$overview" | jq -r '.response' | grep "auth\|security" | while read module; do
  gemini "Deep analysis of $module" -m gemini-2.5-pro --output-format json
done

コストの追跡

クエリごとの追跡

result=$(gemini "query" --output-format json)

# Extract all cost-relevant stats
total_tokens=$(echo "$result" | jq '.stats.models | to_entries | map(.value.tokens.total) | add // 0')
cached_tokens=$(echo "$result" | jq '.stats.models | to_entries | map(.value.tokens.cached) | add // 0')
models_used=$(echo "$result" | jq -r '.stats.models | keys | join(", ")')
tool_calls=$(echo "$result" | jq '.stats.tools.totalCalls // 0')
latency=$(echo "$result" | jq '.stats.models | to_entries | map(.value.api.totalLatencyMs) | add // 0')

echo "$(date): tokens=$total_tokens cached=$cached_tokens models=$models_used tools=$tool_calls latency=${latency}ms" >> usage.log

セッションごとの追跡

# Track cumulative usage across a session
total_session_tokens=0
total_session_cached=0
total_session_calls=0

track_usage() {
  local result="$1"
  local tokens=$(echo "$result" | jq '.stats.models | to_entries | map(.value.tokens.total) | add // 0')
  local cached=$(echo "$result" | jq '.stats.models | to_entries | map(.value.tokens.cached) | add // 0')

  total_session_tokens=$((total_session_tokens + tokens))
  total_session_cached=$((total_session_cached + cached))
  total_session_calls=$((total_session_calls + 1))
}

# Use in workflow
result=$(gemini "query 1" --output-format json)
track_usage "$result"

result=$(gemini "query 2" --output-format json)
track_usage "$result"

echo "Session total: $total_session_tokens tokens ($total_session_cached cached) in $total_session_calls calls"

最適化チェックリスト

大規模な操作の前

• 適切なモデルを選択する（Flash と Pro）
• キャッシュを利用できるか確認する（API キーまたは Vertex）
• 一括処理の戦略を立てる
• 使用状況の追跡を設定する

操作中

• キャッシュヒット率を監視する
• クエリごとのコストを追跡する
• 品質が不十分な場合はモデルを変更する
• 類似したクエリをまとめて処理する

操作後

• 合計使用量を確認する
• 実質コストを算出する
• 最適化の機会を特定する
• 得られた知見を記録する

クイックリファレンス

コスト削減コマンド

# Use Flash for bulk
gemini "query" -m gemini-2.5-flash --output-format json

# Check cache effectiveness
gemini "query" --output-format json | jq '{total: .stats.models | to_entries | map(.value.tokens.total) | add, cached: .stats.models | to_entries | map(.value.tokens.cached) | add}'

# Minimal output (fewer output tokens)
gemini "Answer in one sentence: {question}" --output-format json

コストの見積もり

トークン数の概算：

• 1 トークン ≈ 4 文字（英語）
• コード 1 ページ ≈ 500～1000 トークン
• 一般的なソースファイル ≈ 200～2000 トークン

キーワード一覧（gemini-cli-docs に委任）

トピック	クエリキーワード
キャッシュ	token caching、cached tokens、/stats
モデル選択	model routing、flash vs pro、-m flag
コスト	quota pricing、token usage、billing
出力制御	output format、json output

テストシナリオ

シナリオ 1：トークン使用量を確認する

クエリ：「Gemini が使用したトークン数を確認するにはどうすればよいですか？」 期待される動作：

• 「token usage」または「gemini cost」でスキルが起動する
• JSON 統計情報を抽出するパターンを提示する 成功基準：トークン数を抽出するための jq コマンドがユーザーに提示される

シナリオ 2：コストを削減する

クエリ：「一括分析の Gemini CLI のコストを削減するにはどうすればよいですか？」 期待される動作：

• 「コスト最適化」または「トークン削減」でスキルが起動する
• Flash モデルとバッチ処理を推奨する 成功基準：ユーザーがコスト最適化の戦略を受け取る

シナリオ 3：モデルの選択

クエリ：「このタスクには Flash と Pro のどちらを使うべきですか？」 期待される動作：

• 「Flash と Pro の比較」または「モデル選択」でスキルが起動する
• 選択基準の表を提示する 成功基準：ユーザーがモデルの比較と推奨を受け取る

参考資料

公式ドキュメントについて、gemini-cli-docs に次の項目を問い合わせます：

• 「トークンキャッシュ」
• 「モデルの選択」
• 「クォータと料金」

バージョン履歴

• v1.1.0 (2025-12-01)：テストシナリオのセクションを追加
• v1.0.0 (2025-11-25)：初回リリース