LLM Cost Simulator
LLM を呼ぶアプリの 1 フローあたりのトークン数と費用を、根拠を持って算出する ための
ワークフローとツール群。「なんとなく高そう」を「この処理は $X、月 N 件で $Y、Haiku なら 1/30」
に変える。
いつ使うか
- アプリのコードを見て「この 1 回の処理でいくらかかるか」を知りたい
- モデル/プロバイダ別、件数別、DAU 別のコストを比較・投影したい
- 本番運用の ROI / 採算ラインを根拠付きで説明したい
- 単に「この処理に何トークンかかるか」を実測したい
中核の考え方 — グラウンディング・ラダー
数値には必ず 確度ラベル を付ける。安いものから順に積み上げる:
| Tier | 内容 | コスト | 使う場面 |
|---|
| T0 | 静的推定。コードを読みテンプレ長をトークナイザで数え、可変部は仮定 | 無料 | 最初の概算 |
| T1 | 無料の正確入力カウント。Claude=count_tokens(無料エンドポイント) / OpenAI=tiktoken(ローカル) | 無料 | 入力トークンを確定 |
| T2 | Claude Code/サブスク枠で代表処理を 1 回実行し usage から出力を実測。非 Claude なら proxy で出力長サンプル | サブスク内/極小 | 出力トークンを実測 |
| T3 | 実プロバイダで ground-truth | 実費発生 | 最終確認・厳密化 |
お金が発生する操作(T3, および API キー従量課金の実 API 呼び出し)は、必ず事前にユーザーへ
見積もりを提示し承諾を得てから実行する。 既定は T0→T1→T2 の無料経路。
ワークフロー
1. Discover — LLM 呼び出し箇所を全部洗い出す
コード全体を grep して呼び出し点・モデル・設定を特定する:
# プロバイダ SDK / エンドポイント / モデル名 / 主要パラメータ
rg -n -i \
-e 'anthropic|@anthropic-ai|messages\.create|messages\.stream|count_tokens|claude-[0-9]' \
-e 'openai|OpenAI\(|chat\.completions|responses\.create|\bgpt-[0-9]|\bo[1-4]\b' \
-e 'generativeai|genai|GenerativeModel|generateContent|gemini-[0-9]|vertexai' \
-e 'langchain|ChatOpenAI|ChatAnthropic|ChatGoogleGenerativeAI|llama_index|litellm' \
-e 'max_tokens|max_completion_tokens|tool_choice|tools\s*[:=]|system\s*[:=]|effort|thinking|budget_tokens' \
-e 'api\.openai\.com|api\.anthropic\.com|generativelanguage\.googleapis\.com|OPENAI_API_KEY|ANTHROPIC_API_KEY|GEMINI_API_KEY|GOOGLE_API_KEY' \
--glob '!**/node_modules/**' --glob '!**/.venv/**'
各ヒットについて記録: ファイル:行 / プロバイダ / モデル / どのユーザー操作(フロー)に属するか。
1 つのフローが複数呼び出しを誘発する(分類→生成→エージェントループ等)点に注意。
2. Characterize — 各呼び出しのトークン構成を読む
呼び出しごとに 入力を構成する全要素 を集める。詳細な計上ルールは
references/methodology.md:
- 入力: system プロンプト / ツール・関数定義の JSON スキーマ(毎回送られる。忘れやすい) /
few-shot / RAG 注入(チャンク tok × 件数 k) / 会話履歴 / ユーザー入力 / 画像・PDF(プロバイダ別式)
- 出力:
max_tokens は上限。可能なら T2 で実測。思考/推論(thinking/reasoning)トークンは
出力単価で課金され、しばしば支配的 — 必ず計上。
- 倍率: エージェントループの反復数(履歴が毎ターン累積する=コスト爆発要因) / リトライ /
ファンアウト / 1 フローあたり実行回数。
- 割引機構: プロンプトキャッシュ(安定 prefix の read ~0.1×) / Batch API(-50%)。
3. Assemble — シナリオ JSON を組み立てる
examples/scenario.example.json を雛形にする。スキーマと
重要な計上規約(キャッシュ prefix を component 側と二重計上しない等)は
references/methodology.md。最小構成:
{
"meta": {"app_name":"…","flow_name":"…","analyzed_at":"…","measurement_tier":"T1+T2"},
"compare_models": ["claude-opus-4-8","claude-sonnet-4-6","claude-haiku-4-5","gpt-4o","gemini-2.5-flash"],
"calls": [
{"id":"c1","label":"…","model":"claude-haiku-4-5","source_ref":"src/x.ts:12",
"confidence":"counted","tokens":{"system":350,"user_input":220,"output":40}}
],
"projection": {"monthly_volume":30000,"dau_scenarios":[100,1000,10000],
"flows_per_user_per_day":3,"cache_hit_rate":0.7}
}
4. Measure — 実測でグラウンディング(任意だが推奨)
代表的な入力で probe JSON を作り measure.py を実行:
# T1: 無料の正確入力カウントのみ
python3 scripts/measure.py probe.json
# T2: Claude(サブスク枠)で出力を 1 回実測。非 Claude 対象なら proxy を指定
python3 scripts/measure.py probe.json --run --proxy-model claude-haiku-4-5
# T3: 実プロバイダで ground-truth(実費。--yes-spend かつ対話確認が必要)
python3 scripts/measure.py probe.json --run --yes-spend
得た実測値(出力 min/avg/max、exact 入力)をシナリオの該当 call の tokens に反映し、
confidence を measured/counted に更新する。詳細は
references/measurement-modes.md。
5. Simulate — レポート/HTML/JSON を生成
python3 scripts/simulate.py scenario.json --out-dir <app>/cost_out/ \
--compare claude-opus-4-8,claude-sonnet-4-6,claude-haiku-4-5,gpt-4o,gpt-4o-mini,gemini-2.5-flash
出力(--out-dir):
cost_report.md — 結論(1 フロー単価)、呼び出し内訳、モデル比較、件数/DAU 投影、
キャッシュ感度、前提、推奨アクション、料金出典calculator.html — 自己完結の対話計算機(モデル切替・キャッシュ率・出力倍率・件数スライダー)cost_model.json — 機械可読のコストモデル
6. Report — ユーザーへ提示
1 フロー単価と月間/年間、最安候補との差、主要な前提と確度を要約。verify 確度の料金は
ROI 判断前に再確認するよう明示。
料金の鮮度ルール(重要)
data/pricing.json が唯一の料金ソース。Anthropic は claude-api スキル由来で authoritative。- OpenAI / Google など非 Anthropic は
verify 扱い。実際の ROI 判断の前に必ず公式ページで
再確認し、data/pricing.json を更新してから再計算する(URL は同ファイル meta.refresh)。
- 新モデル/新プロバイダは
data/pricing.json の models に追記すれば自動で計算対象になる。
料金詳細の意味(キャッシュ/バッチ/階層)は references/pricing-notes.md。
ファイル構成
scripts/engine.py — コスト計算エンジン(依存なし)scripts/measure.py — トークン実測(T1/T2/T3)scripts/simulate.py — シナリオ→レポート/HTML/JSONdata/pricing.json — 料金表(拡張可能)templates/calculator.html.template — 対話計算機テンプレートexamples/scenario.example.json — シナリオ雛形references/ — methodology / measurement-modes / pricing-notes
設計原則
- すべての数値に確度ラベルと出典。推測と実測を区別する。
- 無料がデフォルト。お金が動く前に必ず承諾を取る。
- 計上漏れを潰す: ツール定義・思考トークン・履歴累積・キャッシュ書込みは見落としやすい。
- 結論は常に「1 フロー単価 → 件数スケール」で示し、意思決定に直結させる。