コスト対応型 LLM パイプライン

品質を維持しながら LLM API のコストを制御するパターン。モデルルーティング、予算追跡、リトライロジック、プロンプトキャッシングを組み合わせて、構成可能なパイプラインを作成します。

いつ活用するか

• LLM API（Claude、GPT など）を呼び出すアプリケーションを構築するとき
• 異なる複雑度を持つ大量のアイテムを処理するとき
• API 支出を予算内に抑える必要があるとき
• 品質を犠牲にせずに複雑なタスクのコストを最適化する必要があるとき

コア概念

1. タスク複雑度に基づくモデルルーティング

単純なタスクには安価なモデルを自動的に選択し、複雑なタスク用に高価なモデルを確保します。

MODEL_SONNET = "claude-sonnet-4-6"
MODEL_HAIKU = "claude-haiku-4-5-20251001"

_SONNET_TEXT_THRESHOLD = 10_000  # chars
_SONNET_ITEM_THRESHOLD = 30     # items

def select_model(
    text_length: int,
    item_count: int,
    force_model: str | None = None,
) -> str:
    """Select model based on task complexity."""
    if force_model is not None:
        return force_model
    if text_length >= _SONNET_TEXT_THRESHOLD or item_count >= _SONNET_ITEM_THRESHOLD:
        return MODEL_SONNET  # Complex task
    return MODEL_HAIKU  # Simple task (3-4x cheaper)

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 new tracker with added record (never mutates self)."""
        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):
    """Retry only on transient errors, fail fast on others."""
    for attempt in range(max_retries):
        try:
            return func()
        except _RETRYABLE_ERRORS:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)  # Exponential backoff
    # AuthenticationError, BadRequestError etc. → raise immediately

4. プロンプトキャッシング

長いシステムプロンプトをキャッシュして、毎回のリクエストで再送信することを避けます。

messages = [
    {
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": system_prompt,
                "cache_control": {"type": "ephemeral"},  # Cache this
            },
            {
                "type": "text",
                "text": user_input,  # Variable part
            },
        ],
    }
]

構成

4つのテクニックすべてをパイプライン関数に組み合わせます：

def process(text: str, config: Config, tracker: CostTracker) -> tuple[Result, CostTracker]:
    # 1. Route model
    model = select_model(len(text), estimated_items, config.force_model)

    # 2. Check budget
    if tracker.over_budget:
        raise BudgetExceededError(tracker.total_cost, tracker.budget_limit)

    # 3. Call with retry + caching
    response = call_with_retry(lambda: client.messages.create(
        model=model,
        messages=build_cached_messages(system_prompt, text),
    ))

    # 4. Track cost (immutable)
    record = CostRecord(model=model, input_tokens=..., output_tokens=..., cost_usd=...)
    tracker = tracker.add(record)

    return parse_result(response), tracker

価格参考（2025-2026）

モデル	入力（USD/百万トークン）	出力（USD/百万トークン）	相対コスト
Haiku 4.5	$0.80	$4.00	1x
Sonnet 4.6	$3.00	$15.00	~4x
Opus 4.5	$15.00	$75.00	~19x

ベストプラクティス

• 最も安価なモデルから開始し、複雑度閾値に達したときのみ高価なモデルにルーティングします
• バッチ処理前に明確な予算制限を設定 —— オーバースペンドするのではなく早期に失敗します
• モデル選択の決定をログに記録して、実際のデータに基づいて閾値を調整できるようにします
• 1024トークンを超えるシステムプロンプトにはプロンプトキャッシングを使用 —— コストを削減し、レイテンシも低下させます
• 認証エラーや検証エラーではリトライしない —— 一時的な障害（ネットワーク、レート制限、サーバーエラー）のみリトライします

避けるべきアンチパターン

• 複雑度に関係なくすべてのリクエストに最も高価なモデルを使用する
• すべてのエラーに対してリトライする（永続的な障害で予算を浪費）
• コスト追跡の状態を変更する（デバッグと監査を困難にする）
• コードベース全体にモデル名をハードコーディングする（定数または設定を使用する）
• 繰り返されるシステムプロンプトに対してプロンプトキャッシングを無視する

適用シーン

• Claude、OpenAI、またはそれに類する LLM API を呼び出すあらゆるアプリケーション
• コストが急速に累積するバッチ処理パイプライン
• インテリジェントなルーティングが必要なマルチモデルアーキテクチャ
• 予算ガードレールが必要な本番システム