← ADR 一覧へ残タスク一覧へ 最終更新: 2026/06/22 19:15
commonid: adr-0075type: adrstatus: proposed
pagemode: Standardkruchten: Existence/Executivescope: platformimplementation_status: Not Startedproposed_at: 2026-05-26 21:40approved_at: -deciders: [email protected] (単独)business: drp
型付き辺: 出 2 / 入 0
宿題に回答する: ADR-0056 関連: ADR-0101全体は INDEX →

ADR-0075: Decision Pipeline LLM コスト監視 + 撤退トリガー自動化

  • Status: Proposed
  • Mode: Standard
  • Kruchten Type: Existence/Executive
  • Scope: platform
  • Implementation Status: Not Started
  • 起案者: [email protected]
  • 起案日時 (JST): 2026-05-26 21:40
  • 承認日時 (JST): -
  • Deciders: [email protected] (単独)

コンテキスト

1.1 背景 (Background)

ADR-0056 §5.2 は工程別ハイブリッド戦略のコスト試算として月 $6 (現状比 +70%) を見積もり、§6.1 で「LLM コスト総額が予算の 30% 超 ($20/月想定) なら N 削減」の再評価トリガーを定義した。Jr 入社 (2026-10) に伴う ADR 件数増加を控え、コスト監視の自動化基盤整備が必要なタイミングとなっている。

1.2 現状 (Current State / As-Is)

現状、LiteLLM Gateway 経由の token 消費量を自動集計する仕組みがなく、コスト超過の検出は属人的な手動確認 (月次の LiteLLM ダッシュボード目視) に依存している。ノード別内訳の取得も手動で煩雑であり、撤退トリガーとの連動は人間の記憶に依存する状態。

1.3 課題 (Problem)

月 5 件運用では影響は限定的だが、Jr 入社 (2026-10) で月 15 件に増加すると推定 $18/月となり、ADR-0056 §6.1 の撤退トリガー ($20/月) に接近する。手動確認では (a) 確認漏れリスク、(b) ノード別最適化対象の特定困難、(c) 撤退トリガー発火の遅延、の 3 課題が顕在化する。

1.4 制約・要件 (Constraints & Requirements)

  • LiteLLM Gateway のログ (spend tracking API or DB) を一次データソースとする
  • ADR-0056 §6.1 の撤退トリガー ($20/月) より前に段階的に警告できること
  • ノード別コスト内訳を取得できること (LiteLLM config に metadata tag 追加前提)
  • 月次実行 (毎月 1 日) を GitHub Actions cron で自動化
  • 初期実装工数 2.0 人日以内

1.5 目標 (Goals / To-Be)

LiteLLM Gateway ログからの月次コスト集計と段階的アラート ($9 WARN / $12 ALERT) を自動化し、$12/月 2 ヶ月連続で N=5 → N=3 degrade PR を自動起案する。Non-Goals: Workers 実行コスト監視、リアルタイム (日次以下) 監視。

決定

scripts/pipeline-cost-report.mjs を新設し、LiteLLM Gateway ログから月次 token 消費量をノード別に集計、model 別単価テーブル ($/M token) でコスト換算する。段階的アラート ($9 WARN GitHub Issue / $12 ALERT degrade 検討起案) を実装し、$12/月が 2 ヶ月連続発生時に Gate 4 N=5 → N=3 degrade PR を自動起案する。レポートは docs/_internal/06_ops/pipeline_cost_reports/YYYY-MM.md に出力し、GitHub Actions cron (毎月 1 日) で実行する。

model 別単価テーブル (2026-05 時点):

  • Claude Sonnet 4.6: $3/M input + $15/M output
  • Claude Opus 4.7: $15/M input + $75/M output
  • Gemini 2.0 Flash: $0.10/M input + $0.40/M output
  • GPT-4o: $2.50/M input + $10/M output

判断基準 (Decision Drivers)

3.1 評価軸 (Q42 9 タグから 3-5 個選定)

#軸重要度 (係数)案件特有の解釈
1#operable[Must] (×2.0)月次自動集計・段階的アラート・自動 degrade PR 起案までを cron で完結できること
2#reliable[Must] (×2.0)cron 障害・LiteLLM API 仕様変更・自動 PR 暴走に対する検知/防御機構を備えること
3#suitable[High] (×1.0)ADR-0056 §6.1 撤退トリガー ($20/月) との連動、ノード別内訳の提供
4#maintainable[Medium] (×0.5)model 単価テーブル更新 (年 2-3 回) が低コストで実施可能
5#efficient[Medium] (×0.5)初期実装 2.0 人日 / 年間運用 0.8 人日以内

K.O. criterion: Must 軸 (#operable, #reliable) の score < 3 は不採用。

3.2 評価軸 × 案スコア表

軸係数採択案 (本提案)案 A (LiteLLM UI のみ)案 B (CF Workers Billing)案 C (手動継続)
#operable (Must)×2.05211
#reliable (Must)×2.04211
#suitable (High)×1.05312
#maintainable (Medium)×0.53535
#efficient (Medium)×0.53525
加重和 (正規化)0.8750.5500.2250.375
K.O. 通過 (Must ≥3)✓❌❌❌

検討した代替案 (Alternatives Considered)

  • 案 A: LiteLLM ダッシュボードのみ — LiteLLM 組み込み spend tracking UI を使用。不採用理由: 閾値アラートなし、N degrade トリガーとの連動なし、月次レポートの自動生成なし (#operable K.O. failure)。
  • 案 B: Cloudflare Workers Billing API — Workers 実行コストを Billing API で監視。不採用理由: LLM コストは Workers 実行コストとは別軸 (LiteLLM Gateway 経由の外部 API 呼び出し)。Workers Billing では LLM token 消費量を計測できない (#suitable K.O. failure)。
  • 案 C: 手動月次確認の継続 — 毎月末に LiteLLM ダッシュボードを手動確認し Slack にメモ。不採用理由: 忘れるリスク (属人化)、ノード別内訳の取得が手動で煩雑、撤退トリガーとの連動が人間の記憶依存 (#operable/#reliable K.O. failure)。

影響 (Consequences)

5.1 正の影響 (Good)

  • コスト超過を属人的手動確認から自動検出に移行
  • ADR-0056 §6.1 の撤退トリガー ($20/月) への到達を事前に段階的 ($9 WARN → $12 ALERT) に警告
  • ノード別コスト内訳により最適化対象の特定が容易
  • $12/月 2 ヶ月連続で degrade PR が自動起案され、人間判断を促す

5.2 負の影響 (Bad)

  • LiteLLM の spend tracking API 仕様変更時にスクリプト追随が必要
  • model 別単価テーブルの手動更新が必要 (provider 価格改定時、年 2-3 回程度)
  • 自動 PR 起案ロジックの暴走リスク (3 ヶ月連続 ALERT 時の停止機構が必要)

5.3 中立・トレードオフ (Neutral / Trade-offs)

  • 人的ステークホルダー:
    • 代表取締役 (Pipeline オーナー): WARN/ALERT 受信者、N degrade 判断者
    • Jr 開発者 (2026-10): ADR 件数増加に伴うコスト影響の当事者
  • 運用上の落とし穴:
    • cron 障害時の検知遅延: 月次スクリプトが実行されなかった場合、1 ヶ月分のコスト異常を見逃す → 前月レポート不在時に WARN 通知 (dead man's switch)
    • ノード識別子未設定: LiteLLM ログに node_id が含まれない場合、ノード別内訳が取得できない → LiteLLM config に metadata tag 追加が前提
    • 自動 PR 起案の暴走防止: 同一月に degrade PR が 2 件以上作成されないよう既存 open PR の重複チェックを実装。暴走検知: 3 ヶ月連続で ALERT → 自動起案停止 + 人間 review 必須に切替
  • コスト試算:
項目工数
pipeline-cost-report.mjs 実装 (LiteLLM API 連携 + 集計ロジック)1.0 人日
model 別単価テーブル初期作成0.2 人日
GitHub Actions cron workflow + Issue 自動作成0.3 人日
自動 PR 起案ロジック (degrade PR テンプレート + 重複チェック)0.5 人日
初期実装合計2.0 人日
年間運用: 単価テーブル更新 (年 2-3 回 × 0.1 人日)0.3 人日/年
年間運用: レポート確認 + 閾値調整0.5 人日/年

撤退条件 (Rollback Plan)

  • LiteLLM 以外の Gateway に移行した場合、ログ取得部分を置換
  • 12 ヶ月間コストが $6 未満で安定ならモニタリング頻度を月次 → 四半期に緩和
  • Jr 入社後 (2026-10) にコスト構造が変化したら閾値を再設定
  • 自動 PR 起案の停止手順: scripts/pipeline-cost-report.mjs の AUTO_PR_ENABLED フラグを false に設定 (環境変数 or config)。暴走検知時は GitHub Actions の workflow を disable
  • スクリプト撤回手順: 1) cron job 無効化、2) scripts/pipeline-cost-report.mjs 削除、3) model 単価テーブル削除、4) ADR-0056 §5.2 に廃止を追記
  • Review After: 2026-11-26 (6 ヶ月後)

Confirmation (準拠確認 / Fitness Function)

  • 検証手段:
    1. GitHub Actions cron workflow (.github/workflows/pipeline-cost-report.yml) の実行ログを月次レポート (docs/_internal/06_ops/pipeline_cost_reports/YYYY-MM.md) の生成有無で確認
    2. scripts/pipeline-cost-report.mjs 内に閾値判定ユニットテスト ($9/$12 boundary) を実装
    3. dead man's switch: 前月レポート不在時に WARN Issue 自動作成 (scripts/adr-lint.mjs 類似のチェックスクリプトでも代替可)
    4. 自動 PR 起案の暴走検知: 3 ヶ月連続 ALERT 時に AUTO_PR_ENABLED=false 強制切替ロジックの単体テスト
  • 実行頻度: 月次 (毎月 1 日 cron) + PR マージ前 CI (ユニットテスト)
  • 違反時の対応:
    • レポート未生成 (cron 障害): 起案者 (代表取締役) が GitHub Actions workflow 手動 re-run、3 営業日以内に原因調査
    • 閾値判定誤動作: AUTO_PR_ENABLED=false で自動 PR 起案を停止し、手動で N degrade 判断
    • 単価テーブル陳腐化: 四半期 review (年 4 回) で provider 価格ページと突合、差分を PR で更新

参照 (References)

  • 関連 ADR: ADR-0056 (§5.2 コスト試算 / §6.1 撤退トリガー)
  • 関連 PR/Issue: -
  • 外部資料: LiteLLM spend tracking API ドキュメント (要追記)