コスト意識型LLMパイプライン は何をしますか？
品質を維持しながらLLM APIのコストを制御するためのパターン。モデルルーティング、予算追跡、リトライロジック、プロンプトキャッシュを組み合わせた構成可能なパイプラインを提供します。
アクティブにするタイミング
- LLM API（Claude、GPTなど）を呼び出すアプリケーションを構築する場合
- 複雑さが異なるアイテムのバッチを処理する場合
- API支出の予算内に収める必要がある場合
- 複雑なタスクの品質を犠牲にせずにコストを最適化する場合
中核的概念
1. タスクの複雑さによるモデルルーティング
単純なタスクには自動的に安価なモデルを選択し、複雑なタスクには高価なモデルを予約します。
MODEL_SONNET = "claude-sonnet-5"
MODEL_HAIKU = "claude-haiku-4-5-20251001"
_SONNET_TEXT_THRESHOLD = 10_000 # 文字数
_SONNET_ITEM_THRESHOLD = 30 # アイテム数
def select_model(
text_length: int,
item_count: int,
force_model: str | None = None,
) -> str:
"""タスクの複雑さに基づいてモデルを選択します。"""
if force_model is not None:
return force_model
if text_length >= _SONNET_TEXT_THRESHOLD or item_count >= _SONNET_ITEM_THRESHOLD:
return MODEL_SONNET # 複雑なタスク
return MODEL_HAIKU # 単純なタスク（3～4倍安価）
2. 不変のコスト追跡
凍結データクラスを使用して累積支出を追跡します。各API呼び出しは新しいトラッカーを返します — 状態を決して変更しません。
from dataclasses import dataclass
@dataclass(frozen=True, slots=True)
class CostRecord:
model: str
input_tokens: int
output_tokens: int
cost_usd: float
@dataclass(frozen=True, slots=True)
class CostTracker:
budget_limit: float = 1.00
records: tuple[CostRecord, ...] = ()
def add(self, record: CostRecord) -> "CostTracker":
"""レコードを追加した新しいトラッカーを返します（自身を変更しません）。"""
return CostTracker(
budget_limit=self.budget_limit,
records=(*self.records, record),
)
@property
def total_cost(self) -> float:
return sum(r.cost_usd for r in self.records)
@property
def over_budget(self) -> bool:
return self.total_cost > self.budget_limit
3. 狭いリトライロジック
一時的なエラーの場合のみリトライします。認証エラーや不正なリクエストエラーでは即座に失敗します。
from anthropic import (
APIConnectionError,
InternalServerError,
RateLimitError,
)
_RETRYABLE_ERRORS = (APIConnectionError, RateLimitError, InternalServerError)
_MAX_RETRIES = 3
def call_with_retry(func, *, max_retries: int = _MAX_RETRIES):
"""一時的なエラーのみリトライし、その他のエラーでは即座に失敗します。"""
for attempt in range(max_retries):
try:
return func()
except _RETRYABLE_ERRORS:
if attempt == max_retries - 1:
raise
time.sleep(2 ** attempt) # 指数バックオフ
# AuthenticationError, BadRequestError など → 即座に例外を送出
4. プロンプトキャッシュ
長いシステムプロンプトをキャッシュして、リクエストのたびに再送信することを避けます。
messages = [
{
"role": "user",
"content": [
{
"type": "text",
"text": system_prompt,
"cache_control": {"type": "ephemeral"}, # これをキャッシュ
},
{
"type": "text",
"text": user_input, # 可変部分
},
],
}
]
構成
4つのテクニックすべてを単一のパイプライン関数に組み合わせます：
def process(text: str, config: Config, tracker: CostTracker) -> tuple[Result, CostTracker]:
# 1. モデルをルーティング
model = select_model(len(text), estimated_items, config.force_model)
# 2. 予算を確認
if tracker.over_budget:
raise BudgetExceededError(tracker.total_cost, tracker.budget_limit)
# 3. リトライ + キャッシュで呼び出し
response = call_with_retry(lambda: client.messages.create(
model=model,
messages=build_cached_messages(system_prompt, text),
))
# 4. コストを追跡（不変）
record = CostRecord(model=model, input_tokens=..., output_tokens=..., cost_usd=...)
tracker = tracker.add(record)
return parse_result(response), tracker
料金参考情報（2026年）
| モデル | 入力（$ / 100万トークン） | 出力（$ / 100万トークン） | 相対コスト |
|---|---|---|---|
| Haiku 3.5（レガシー） | $0.80 | $4.00 | 0.8x |
| Haiku 4.5 | $1.00 | $5.00 | 1x |
| Sonnet 5 | $2.00 | $10.00 | 2x |
| Sonnet 4.6 | $3.00 | $15.00 | 3x |
| Opus 4.8 | $5.00 | $25.00 | 5x |
| Fable 5 / Mythos 5 | $10.00 | $50.00 | 10x |
| Opus 4.0 / 4.1（レガシー） | $15.00 | $75.00 | 15x |
ベストプラクティス
- 最も安価なモデルから開始し、複雑さのしきい値を超えた場合のみ高価なモデルにルーティングする
- バッチ処理の前に明示的な予算制限を設定する — 予算超過になる前に早期に失敗させる
- モデル選択の決定をログに記録し、実際のデータに基づいてしきい値を調整できるようにする
- 1024トークンを超えるシステムプロンプトにはプロンプトキャッシュを使用する — コストとレイテンシの両方を削減
- 認証エラーや検証エラーでは決してリトライしない — 一時的な障害（ネットワーク、レート制限、サーバーエラー）のみリトライする
避けるべきアンチパターン
- 複雑さに関係なくすべてのリクエストに最も高価なモデルを使用する
- すべてのエラーでリトライする（永続的な障害で予算を浪費する）
- コスト追跡状態を変更可能にする（デバッグと監査が困難になる）
- コードベース全体でモデル名をハードコーディングする（定数または設定を使用する）
- 繰り返し使用されるシステムプロンプトのプロンプトキャッシュを無視する
使用すべきタイミング
- Claude、OpenAI、または類似のLLM APIを呼び出すあらゆるアプリケーション
- コストが急速に累積するバッチ処理パイプライン
- インテリジェントなルーティングが必要なマルチモデルアーキテクチャ
- 予算のガードレールが必要な本番システム