Claude API コスト最適化プロダクションガイド — Batch API・Prompt Caching・Adaptive Thinking を組み合わせて最大90%削減する実装パターン

// batch-processor.ts — 本番用バッチ処理クライアント
import Anthropic from "@anthropic-ai/sdk";
 
interface BatchJob {
  id: string;
  prompt: string;
  systemPrompt?: string;
  metadata?: Record<string, string>;
}
 
interface BatchConfig {
  model: string;
  maxTokens: number;
  concurrencyLimit: number; // 同時処理バッチ数の上限
  retryAttempts: number;
}
 
class ProductionBatchProcessor {
  private client: Anthropic;
  private config: BatchConfig;
 
  constructor(config: BatchConfig) {
    this.client = new Anthropic();
    this.config = config;
  }
 
  // バッチリクエストをJSONL形式で構築
  private buildBatchRequests(jobs: BatchJob[]) {
    return jobs.map((job) => ({
      custom_id: job.id,
      params: {
        model: this.config.model,
        max_tokens: this.config.maxTokens,
        system: job.systemPrompt || "You are a helpful assistant.",
        messages: [{ role: "user" as const, content: job.prompt }],
      },
    }));
  }
 
  // バッチを送信し、完了まで待機
  async processBatch(jobs: BatchJob[]): Promise<Map<string, string>> {
    const requests = this.buildBatchRequests(jobs);
 
    // バッチ作成
    const batch = await this.client.messages.batches.create({
      requests,
    });
 
    console.log(`Batch created: ${batch.id} (${jobs.length} jobs)`);
 
    // ポーリングで完了待ち（本番では Webhook 推奨）
    const results = new Map<string, string>();
    let status = batch.processing_status;
 
    while (status !== "ended") {
      await new Promise((r) => setTimeout(r, 30_000)); // 30秒間隔
      const updated = await this.client.messages.batches.retrieve(batch.id);
      status = updated.processing_status;
 
      console.log(
        `Batch ${batch.id}: ${status}`,
        `(succeeded: ${updated.request_counts.succeeded}`,
        `/ errored: ${updated.request_counts.errored})`
      );
    }
 
    // 結果を取得
    for await (const result of this.client.messages.batches.results(
      batch.id
    )) {
      if (result.result.type === "succeeded") {
        const text = result.result.message.content
          .filter((b) => b.type === "text")
          .map((b) => b.text)
          .join("");
        results.set(result.custom_id, text);
      }
    }
 
    return results;
  }
}
 
// 使用例：1000件のドキュメント要約を50%コストで実行
const processor = new ProductionBatchProcessor({
  model: "claude-sonnet-4-6-20260320",
  maxTokens: 2048,
  concurrencyLimit: 5,
  retryAttempts: 3,
});
 
const jobs: BatchJob[] = documents.map((doc, i) => ({
  id: `summary-${i}`,
  prompt: `以下のドキュメントを300文字以内で要約してください:\n\n${doc.content}`,
  systemPrompt: "あなたは正確で簡潔な要約を生成する専門家です。",
}));
 
const summaries = await processor.processBatch(jobs);
// コスト: Sonnet 4.6 通常 $3/$15 → Batch $1.5/$7.5（50%削減）

// chunk-strategy.ts — ワークロード別チャンク戦略
function getOptimalChunkSize(totalJobs: number, avgTokensPerJob: number): number {
  const totalTokenEstimate = totalJobs * avgTokensPerJob;
 
  if (totalTokenEstimate < 1_000_000) {
    // 小規模: 全件を1バッチに
    return totalJobs;
  } else if (totalTokenEstimate < 50_000_000) {
    // 中規模: 500件ずつ（エラー時の再送範囲を限定）
    return 500;
  } else {
    // 大規模: 200件ずつ（メモリ消費とリトライコストのバランス）
    return 200;
  }
}

// prompt-cache-optimizer.ts — キャッシュ効率を最大化する設計パターン
import Anthropic from "@anthropic-ai/sdk";
 
class CacheOptimizedClient {
  private client: Anthropic;
 
  constructor() {
    this.client = new Anthropic();
  }
 
  // パターン1: 大規模システムプロンプトのキャッシュ
  // → 同じシステムプロンプトを使う連続リクエストで効果大
  async withCachedSystemPrompt(
    systemPrompt: string,
    userMessages: Array<{ role: "user" | "assistant"; content: string }>
  ) {
    return this.client.messages.create({
      model: "claude-sonnet-4-6-20260320",
      max_tokens: 4096,
      system: [
        {
          type: "text",
          text: systemPrompt,
          cache_control: { type: "ephemeral" }, // 5分間キャッシュ
        },
      ],
      messages: userMessages,
    });
  }
 
  // パターン2: ドキュメント分析 — 同一文書への複数質問
  // → 文書部分をキャッシュし、質問だけ変えて繰り返し呼び出す
  async analyzeDocumentWithQuestions(
    document: string,
    questions: string[]
  ) {
    const results: string[] = [];
 
    for (const question of questions) {
      const response = await this.client.messages.create({
        model: "claude-sonnet-4-6-20260320",
        max_tokens: 2048,
        messages: [
          {
            role: "user",
            content: [
              {
                type: "text",
                text: `以下のドキュメントを分析してください:\n\n${document}`,
                cache_control: { type: "ephemeral" },
              },
              {
                type: "text",
                text: `\n\n質問: ${question}`,
              },
            ],
          },
        ],
      });
 
      results.push(
        response.content
          .filter((b) => b.type === "text")
          .map((b) => b.text)
          .join("")
      );
 
      // キャッシュ使用状況をログ
      console.log(
        `Cache: write=${response.usage.cache_creation_input_tokens ?? 0}`,
        `read=${response.usage.cache_read_input_tokens ?? 0}`,
        `uncached=${response.usage.input_tokens}`
      );
    }
 
    return results;
  }
}
 
// 実行例: 50ページのPDFに10個の質問 → 2回目以降は入力コスト90%削減
const client = new CacheOptimizedClient();
const answers = await client.analyzeDocumentWithQuestions(
  longPdfText,          // ~30,000トークン
  [
    "契約期間は？",
    "違約金の条件は？",
    "自動更新の有無は？",
    // ... 7つの追加質問
  ]
);
// 1回目: 30,000トークン書き込み（1.25倍コスト）
// 2〜10回目: 30,000トークン読み取り × 0.1倍 = 3,000トークン相当
// トータル: 通常300,000 → 最適化後 67,500トークン相当（約78%削減）

// cache-friendly-prompt-design.ts
// ❌ 悪い例: 毎回変わる部分がプロンプト先頭にある
const badPrompt = `
現在時刻: ${new Date().toISOString()}  // ← 毎回変わる → キャッシュ無効化
ユーザーID: ${userId}
以下の長いシステム指示に従ってください...（5000トークン）
`;
 
// ✅ 良い例: 変わらない部分を先頭に、変わる部分を末尾に
const goodPrompt = [
  {
    type: "text" as const,
    text: longSystemInstructions,    // 5000トークン（不変）
    cache_control: { type: "ephemeral" as const },
  },
  {
    type: "text" as const,
    text: `ユーザーID: ${userId}\n現在時刻: ${new Date().toISOString()}`,
    // ← 変動部分はキャッシュ対象外
  },
];

// adaptive-thinking-router.ts — 複雑度に応じた思考レベルの自動選択
import Anthropic from "@anthropic-ai/sdk";
 
type ThinkingEffort = "low" | "medium" | "high" | "max";
 
interface TaskClassification {
  complexity: "simple" | "moderate" | "complex" | "critical";
  estimatedTokens: number;
}
 
class AdaptiveThinkingRouter {
  private client: Anthropic;
 
  constructor() {
    this.client = new Anthropic();
  }
 
  // タスクの複雑度を事前判定（軽量モデルで分類）
  private async classifyTask(prompt: string): Promise<TaskClassification> {
    const response = await this.client.messages.create({
      model: "claude-haiku-4-5-20251001", // 分類は Haiku で十分
      max_tokens: 100,
      messages: [
        {
          role: "user",
          content: `Classify this task complexity as simple/moderate/complex/critical. Reply with JSON only: {"complexity": "...", "estimatedTokens": N}\n\nTask: ${prompt.slice(0, 500)}`,
        },
      ],
    });
 
    try {
      const text = response.content[0].type === "text" ? response.content[0].text : "";
      return JSON.parse(text);
    } catch {
      return { complexity: "moderate", estimatedTokens: 1000 };
    }
  }
 
  // 複雑度 → thinking effort のマッピング
  private getThinkingConfig(
    classification: TaskClassification
  ): { model: string; effort: ThinkingEffort } {
    switch (classification.complexity) {
      case "simple":
        // 単純な質問 → Haiku（thinking不要、最安）
        return { model: "claude-haiku-4-5-20251001", effort: "low" };
      case "moderate":
        // 中程度 → Sonnet + 低〜中の思考
        return { model: "claude-sonnet-4-6-20260320", effort: "medium" };
      case "complex":
        // 複雑 → Sonnet + 高い思考
        return { model: "claude-sonnet-4-6-20260320", effort: "high" };
      case "critical":
        // 重要タスク → Opus + 最大思考
        return { model: "claude-opus-4-6-20260320", effort: "max" };
      default:
        return { model: "claude-sonnet-4-6-20260320", effort: "medium" };
    }
  }
 
  async processWithOptimalThinking(prompt: string, systemPrompt?: string) {
    const classification = await this.classifyTask(prompt);
    const { model, effort } = this.getThinkingConfig(classification);
 
    console.log(
      `Task classified as ${classification.complexity}`,
      `→ ${model} with effort=${effort}`
    );
 
    const response = await this.client.messages.create({
      model,
      max_tokens: 16000,
      thinking: {
        type: "enabled",
        budget_tokens: this.getThinkingBudget(effort),
      },
      system: systemPrompt || "You are a helpful assistant.",
      messages: [{ role: "user", content: prompt }],
    });
 
    return response;
  }
 
  private getThinkingBudget(effort: ThinkingEffort): number {
    const budgets: Record<ThinkingEffort, number> = {
      low: 1024,
      medium: 4096,
      high: 10000,
      max: 32000,
    };
    return budgets[effort];
  }
}

// unified-cost-optimizer.ts — 三重最適化を統合した本番クライアント
import Anthropic from "@anthropic-ai/sdk";
 
interface OptimizationReport {
  originalCostEstimate: number;
  optimizedCostEstimate: number;
  savingsPercent: number;
  breakdown: {
    batchDiscount: number;
    cacheDiscount: number;
    modelDowngrade: number;
  };
}
 
class UnifiedCostOptimizer {
  private client: Anthropic;
  private readonly PRICING = {
    "claude-opus-4-6": { input: 15, output: 75, cacheWrite: 18.75, cacheRead: 1.5 },
    "claude-sonnet-4-6": { input: 3, output: 15, cacheWrite: 3.75, cacheRead: 0.3 },
    "claude-haiku-4-5": { input: 0.8, output: 4, cacheWrite: 1, cacheRead: 0.08 },
  }; // per 1M tokens
 
  constructor() {
    this.client = new Anthropic();
  }
 
  // ワークロード分析 → 最適戦略を自動選択
  async optimizeWorkload(
    jobs: Array<{ prompt: string; priority: "realtime" | "async" | "background" }>,
    sharedContext?: string
  ): Promise<OptimizationReport> {
    // 1. ジョブをプライオリティ別に分類
    const realtime = jobs.filter((j) => j.priority === "realtime");
    const async_ = jobs.filter((j) => j.priority === "async");
    const background = jobs.filter((j) => j.priority === "background");
 
    let totalOriginal = 0;
    let totalOptimized = 0;
 
    // 2. リアルタイム: キャッシュ + Adaptive Thinking（Batch不可）
    if (realtime.length > 0) {
      for (const job of realtime) {
        const { cost } = await this.processRealtime(job.prompt, sharedContext);
        totalOptimized += cost;
        totalOriginal += cost * 2.5; // キャッシュなし・フル思考の想定コスト
      }
    }
 
    // 3. 非同期: Batch API + キャッシュ（最大の削減効果）
    if (async_.length > 0 || background.length > 0) {
      const batchJobs = [...async_, ...background];
      const { cost } = await this.processBatchWithCache(
        batchJobs.map((j) => j.prompt),
        sharedContext
      );
      totalOptimized += cost;
      totalOriginal += cost * 4; // Batch割引なし・キャッシュなしの想定コスト
    }
 
    const savingsPercent =
      ((totalOriginal - totalOptimized) / totalOriginal) * 100;
 
    return {
      originalCostEstimate: totalOriginal,
      optimizedCostEstimate: totalOptimized,
      savingsPercent,
      breakdown: {
        batchDiscount: (async_.length + background.length) > 0 ? 50 : 0,
        cacheDiscount: sharedContext ? 90 : 0,
        modelDowngrade: background.length > 0 ? 30 : 0,
      },
    };
  }
 
  private async processRealtime(prompt: string, sharedContext?: string) {
    const messages: Anthropic.MessageCreateParams["messages"] = [
      {
        role: "user",
        content: sharedContext
          ? [
              { type: "text", text: sharedContext, cache_control: { type: "ephemeral" } },
              { type: "text", text: `\n\n${prompt}` },
            ]
          : prompt,
      },
    ];
 
    const response = await this.client.messages.create({
      model: "claude-sonnet-4-6-20260320",
      max_tokens: 4096,
      thinking: { type: "enabled", budget_tokens: 4096 },
      messages,
    });
 
    const cost = this.calculateCost(response.usage, "claude-sonnet-4-6");
    return { response, cost };
  }
 
  private async processBatchWithCache(prompts: string[], sharedContext?: string) {
    const requests = prompts.map((prompt, i) => ({
      custom_id: `job-${i}`,
      params: {
        model: "claude-sonnet-4-6-20260320",
        max_tokens: 2048,
        messages: [
          {
            role: "user" as const,
            content: sharedContext
              ? [
                  { type: "text" as const, text: sharedContext, cache_control: { type: "ephemeral" as const } },
                  { type: "text" as const, text: `\n\n${prompt}` },
                ]
              : prompt,
          },
        ],
      },
    }));
 
    const batch = await this.client.messages.batches.create({ requests });
    // Batch API: 50%割引 + キャッシュ: 入力90%割引 = 合計約95%削減
    const estimatedCost = prompts.length * 0.002; // rough estimate
    return { batch, cost: estimatedCost };
  }
 
  private calculateCost(
    usage: Anthropic.Usage,
    model: "claude-opus-4-6" | "claude-sonnet-4-6" | "claude-haiku-4-5"
  ): number {
    const pricing = this.PRICING[model];
    const inputCost = (usage.input_tokens / 1_000_000) * pricing.input;
    const outputCost = (usage.output_tokens / 1_000_000) * pricing.output;
    return inputCost + outputCost;
  }
}

// cost-monitor.ts — リアルタイムコスト監視 & アラートシステム
interface CostAlert {
  threshold: number;   // USD
  period: "hourly" | "daily" | "monthly";
  action: "warn" | "throttle" | "block";
}
 
class CostMonitor {
  private usageLog: Array<{ timestamp: Date; cost: number; model: string }> = [];
  private alerts: CostAlert[];
 
  constructor(alerts: CostAlert[]) {
    this.alerts = alerts;
  }
 
  // 毎リクエスト後に呼び出し
  recordUsage(usage: Anthropic.Usage, model: string) {
    const cost = this.estimateCost(usage, model);
    this.usageLog.push({ timestamp: new Date(), cost, model });
    this.checkAlerts();
    return cost;
  }
 
  private checkAlerts() {
    for (const alert of this.alerts) {
      const periodCost = this.getCostForPeriod(alert.period);
 
      if (periodCost > alert.threshold) {
        switch (alert.action) {
          case "warn":
            console.warn(
              `⚠️ Cost alert: ${alert.period} spend $${periodCost.toFixed(2)}`,
              `exceeds threshold $${alert.threshold}`
            );
            break;
          case "throttle":
            // リクエスト間隔を延長してコストを抑制
            console.warn(`🔶 Throttling: adding 5s delay between requests`);
            break;
          case "block":
            // 予算超過で新規リクエストをブロック
            throw new Error(
              `🛑 Budget exceeded: ${alert.period} cost $${periodCost.toFixed(2)}`
            );
        }
      }
    }
  }
 
  private getCostForPeriod(period: "hourly" | "daily" | "monthly"): number {
    const now = new Date();
    const cutoff = new Date(now);
 
    switch (period) {
      case "hourly": cutoff.setHours(cutoff.getHours() - 1); break;
      case "daily": cutoff.setDate(cutoff.getDate() - 1); break;
      case "monthly": cutoff.setMonth(cutoff.getMonth() - 1); break;
    }
 
    return this.usageLog
      .filter((entry) => entry.timestamp > cutoff)
      .reduce((sum, entry) => sum + entry.cost, 0);
  }
 
  private estimateCost(usage: Anthropic.Usage, model: string): number {
    // 簡易コスト計算（実際はモデル別の料金テーブルを参照）
    const rates: Record<string, { input: number; output: number }> = {
      "claude-opus-4-6-20260320": { input: 15, output: 75 },
      "claude-sonnet-4-6-20260320": { input: 3, output: 15 },
      "claude-haiku-4-5-20251001": { input: 0.8, output: 4 },
    };
    const rate = rates[model] || rates["claude-sonnet-4-6-20260320"];
    return (
      (usage.input_tokens / 1_000_000) * rate.input +
      (usage.output_tokens / 1_000_000) * rate.output
    );
  }
 
  // 日次レポート生成
  generateDailyReport(): string {
    const today = this.usageLog.filter(
      (e) => e.timestamp > new Date(Date.now() - 86400_000)
    );
    const totalCost = today.reduce((s, e) => s + e.cost, 0);
    const byModel = today.reduce((acc, e) => {
      acc[e.model] = (acc[e.model] || 0) + e.cost;
      return acc;
    }, {} as Record<string, number>);
 
    return [
      `=== Daily API Cost Report ===`,
      `Total: $${totalCost.toFixed(4)}`,
      `Requests: ${today.length}`,
      ...Object.entries(byModel).map(
        ([m, c]) => `  ${m}: $${(c as number).toFixed(4)}`
      ),
    ].join("\n");
  }
}
 
// 使用例: 3段階のアラート設定
const monitor = new CostMonitor([
  { threshold: 5, period: "hourly", action: "warn" },
  { threshold: 50, period: "daily", action: "throttle" },
  { threshold: 500, period: "monthly", action: "block" },
]);