LLM評価バッチに使用量記録と停止レバーを入れる

LLMを使った評価バッチは、少数の入力なら便利でも、対象件数が増えると実行時間とトークン消費が読みづらくなる。特に毎日動く評価処理では、「品質を上げたい」だけでなく「必要な時に止められる」「後から使用量を見られる」ことも運用機能の一部になる。今回は、銘柄評価のような多数件バッチに、LLM使用量の記録と呼び出し抑制の安全弁を追加した取り組みをまとめる。

> 本記事は自動化基盤の実装記録です。投資判断や銘柄推奨ではありません。LLM出力を業務・投資・会計判断に使う場合は、人が一次情報と前提条件を確認してください。

実際に行ったことと確認できた結果

手元の記録では、既存の評価基盤に「LLMトークンコスト削減レバー0+1」として、CLI遮断フラグ、usage記録、ダッシュボード対応が実装された。さらに、テーマ株予測、通知改善、プライム市場対応などと混在していた変更を機能単位のコミットに分け、このコスト削減は独立した改善として整理された。

確認結果として、2026-08-19の記録には、最終ツリーで全532テスト成功、ruffクリーンが確認されたと残っている。今回のブログ作成時にも、関連するHermes Agentプロジェクト側のテストを再実行し、111件と4サブテストが成功した。つまり、単なる節約アイデアではなく、運用上の新しい制御能力として実装・検証された取り組みとして扱える。

仕組みまたは処理の流れ

基本方針は、LLM呼び出しを完全にブラックボックス化しないことだ。バッチの入口で「今回LLMを呼ぶか」を判定し、呼んだ場合は対象件数、モデル、入力・出力トークン相当の使用量、失敗理由を記録する。ダッシュボードでは、評価品質だけでなく、どの実行が重かったのか、どの処理を止めたのかを見られるようにする。

一般化すると、流れは次のようになる。

1. cronまたは手動CLIから評価バッチを開始する。
2. 環境変数や設定ファイルで、LLM呼び出し許可フラグを読む。
3. 禁止中なら、既存データだけで実行できる処理に限定し、スキップ理由を記録する。
4. 許可中ならLLM評価を実行し、usage情報と対象件数を保存する。
5. 終了時に、成功・失敗・スキップ・使用量をレポートへ出す。
6. ダッシュボードや通知で、品質指標とコスト指標を分けて確認する。

Claude Codeの公式ドキュメントでも、コスト管理では`/usage`による利用確認、コンテキスト管理、モデル選択、前処理hookなどによる削減が案内されている。今回はそれを、日次バッチ側の「止める」「記録する」「見える化する」レバーへ落とし込んだ形だ。

再現手順

公開例では実パス、通知先、データベース名は置き換える。

“`bash
cd /path/to/project
uv sync
python -m pytest
ruff check .
“`

次に、LLM呼び出しの制御フラグを用意する。最初はドライランで、実際にLLMを呼ばない状態の出力を確認する。

“`bash
export LLM_EVAL_ENABLED=false
export USAGE_LOG=/path/to/usage.jsonl
python evaluation_batch.py –date 2026-08-19 –dry-run
“`

スキップ理由、対象件数、保存先が想定どおりなら、少数件だけ許可して実行する。

“`bash
export LLM_EVAL_ENABLED=true
python evaluation_batch.py –date 2026-08-19 –limit 3
python dashboard.py –usage-log "$USAGE_LOG"
“`

Hermes cronへ載せる場合は、朝の本番バッチと検証バッチを分け、プロジェクトの作業ディレクトリを明示する。Hermes公式ドキュメントでは、cronは自然言語またはcron式で作成でき、プロジェクト内で実行する場合は`–workdir`を指定できる。

“`bash
hermes cron create "0 8 * * 1-5" \
"Run the evaluation batch with usage logging and report failures only" \
–name "evaluation batch with usage guard" \
–workdir /path/to/project
“`

失敗しやすい点、安全策、未完了事項

最初の落とし穴は、使用量を後から推測しようとすることだ。バッチ完了後にログが残っていなければ、どの入力が重かったのか分からない。LLM呼び出しの直後にusageを追記し、失敗時も途中までの記録を残すのが安全だ。

次に、停止フラグを「失敗」と混同しない。意図的にLLM呼び出しを止めた実行は、エラーではなくスキップとして記録する。ダッシュボードでも、品質未評価とシステム障害を分けて表示する。

未完了事項としては、実運用での閾値調整が残る。1件あたりの許容トークン、1日あたりの上限、通知を出すしきい値は、データ量と予算によって変わる。まずは小さな上限から始め、テストとログを見ながら広げるのが現実的だ。

再現チェックリスト

• [ ] LLM呼び出しの許可フラグを環境変数または設定で切り替えられる。
• [ ] 禁止中はエラーではなくスキップとして記録される。
• [ ] usageログに日時、対象件数、モデル、成功・失敗、使用量が残る。
• [ ] ダッシュボードで品質結果とコスト指標を分けて見られる。
• [ ] 少数件ドライラン、本番相当テスト、lintをcron登録前に通している。
• [ ] 投資・会計など人の判断が必要な出力は、自動通知だけで確定しない。

公式一次情報

• [Claude Code: Manage costs effectively](https://docs.anthropic.com/en/docs/claude-code/costs)
• [Claude Code: Monitoring](https://docs.anthropic.com/en/docs/claude-code/monitoring-usage)
• [Hermes Agent: Scheduled Tasks (Cron)](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron)