Claude API の高可用性設計 — Sonnet / Haiku / Opus マルチモデルフォールバックを本番で成立させる

// claude-fallback-client.ts
import Anthropic from "@anthropic-ai/sdk";
 
type FallbackChain = readonly string[];
 
interface FallbackConfig {
  readonly models: FallbackChain;
  readonly perCallTimeoutMs: number;
  readonly onFallback?: (fromModel: string, toModel: string, reason: string) => void;
}
 
// デフォルトの品質優先チェーン
const DEFAULT_CHAIN: FallbackChain = [
  "claude-sonnet-4-6",
  "claude-opus-4-6",
  "claude-haiku-4-5-20251001",
] as const;
 
export class ClaudeFallbackClient {
  private readonly client: Anthropic;
 
  constructor(apiKey: string) {
    this.client = new Anthropic({ apiKey });
  }
 
  async createMessage(
    params: Omit<Anthropic.MessageCreateParamsNonStreaming, "model">,
    config: Partial<FallbackConfig> = {},
  ): Promise<{ message: Anthropic.Message; modelUsed: string }> {
    const chain = config.models ?? DEFAULT_CHAIN;
    const timeoutMs = config.perCallTimeoutMs ?? 30_000;
    const errors: { model: string; error: unknown }[] = [];
 
    for (let i = 0; i < chain.length; i++) {
      const model = chain[i];
      try {
        const message = await this.callWithTimeout(
          () => this.client.messages.create({ ...params, model }),
          timeoutMs,
        );
        return { message, modelUsed: model };
      } catch (err) {
        errors.push({ model, error: err });
        if (!this.shouldFallback(err) || i === chain.length - 1) {
          // フォールバック対象外のエラー（400, 401 など）は即時スロー
          // 最後のモデルでも失敗した場合はスロー
          throw new AggregateError(
            errors.map((e) => e.error),
            `All models in chain failed: ${errors.map((e) => e.model).join(" → ")}`,
          );
        }
        const next = chain[i + 1];
        config.onFallback?.(model, next, this.describeError(err));
      }
    }
    throw new Error("unreachable");
  }
 
  private shouldFallback(err: unknown): boolean {
    if (err instanceof Anthropic.APIError) {
      // 429: レート制限 / 529: 過負荷 / 5xx: サーバーエラー
      if (err.status === 429 || err.status === 529) return true;
      if (err.status !== undefined && err.status >= 500) return true;
      return false;
    }
    // タイムアウトとネットワークエラーはフォールバック対象
    if (err instanceof Error) {
      if (err.name === "AbortError") return true;
      if (err.message.includes("ECONNRESET") || err.message.includes("ETIMEDOUT")) return true;
    }
    return false;
  }
 
  private describeError(err: unknown): string {
    if (err instanceof Anthropic.APIError) return `${err.status} ${err.name}`;
    if (err instanceof Error) return err.name;
    return "unknown";
  }
 
  private async callWithTimeout<T>(fn: () => Promise<T>, ms: number): Promise<T> {
    const controller = new AbortController();
    const timer = setTimeout(() => controller.abort(), ms);
    try {
      return await fn();
    } finally {
      clearTimeout(timer);
    }
  }
}
 
// 使用例
const client = new ClaudeFallbackClient(process.env.ANTHROPIC_API_KEY!);
const { message, modelUsed } = await client.createMessage(
  {
    max_tokens: 1024,
    messages: [{ role: "user", content: "Summarize quantum tunneling in 3 sentences." }],
  },
  {
    onFallback: (from, to, reason) => {
      console.warn(`[fallback] ${from} → ${to} (${reason})`);
    },
  },
);
console.log(`[ok] model=${modelUsed}`);
console.log(message.content[0].type === "text" ? message.content[0].text : "");

// circuit-breaker.ts
type CircuitState = "closed" | "open" | "half-open";
 
interface BreakerOptions {
  readonly failureThreshold: number;  // この回数連続で失敗したら open
  readonly openDurationMs: number;    // open 状態を保つ時間
  readonly halfOpenTrialLimit: number; // half-open で試す回数
}
 
const DEFAULTS: BreakerOptions = {
  failureThreshold: 5,
  openDurationMs: 30_000,
  halfOpenTrialLimit: 1,
};
 
export class CircuitBreaker {
  private state: CircuitState = "closed";
  private failureCount = 0;
  private openedAt = 0;
  private halfOpenTrials = 0;
 
  constructor(private readonly name: string, private readonly opts: BreakerOptions = DEFAULTS) {}
 
  canExecute(): boolean {
    if (this.state === "closed") return true;
    if (this.state === "open") {
      if (Date.now() - this.openedAt >= this.opts.openDurationMs) {
        this.state = "half-open";
        this.halfOpenTrials = 0;
        return true;
      }
      return false;
    }
    // half-open: 限定的に試行を許可
    return this.halfOpenTrials < this.opts.halfOpenTrialLimit;
  }
 
  onSuccess(): void {
    this.failureCount = 0;
    if (this.state !== "closed") {
      this.state = "closed";
    }
  }
 
  onFailure(): void {
    this.failureCount += 1;
    if (this.state === "half-open") {
      this.halfOpenTrials += 1;
      this.state = "open";
      this.openedAt = Date.now();
      return;
    }
    if (this.failureCount >= this.opts.failureThreshold) {
      this.state = "open";
      this.openedAt = Date.now();
    }
  }
 
  describe(): string {
    return `${this.name}[${this.state} failures=${this.failureCount}]`;
  }
}
 
// ClaudeFallbackClient と組み合わせる
const breakers = new Map<string, CircuitBreaker>();
function getBreaker(model: string): CircuitBreaker {
  let breaker = breakers.get(model);
  if (!breaker) {
    breaker = new CircuitBreaker(model);
    breakers.set(model, breaker);
  }
  return breaker;
}
 
// createMessage ループ内の改修例
// for (const model of chain) の中で:
//   const breaker = getBreaker(model);
//   if (!breaker.canExecute()) continue;  // open ならスキップして次モデルへ
//   try {
//     const message = await this.callWithTimeout(...);
//     breaker.onSuccess();
//     return { message, modelUsed: model };
//   } catch (err) {
//     if (this.shouldFallback(err)) breaker.onFailure();
//     // ...
//   }

// stream-fallback.ts
import Anthropic from "@anthropic-ai/sdk";
 
export async function streamWithFallback(
  client: Anthropic,
  params: Omit<Anthropic.MessageStreamParams, "model">,
  chain: readonly string[],
  onDelta: (text: string) => void,
): Promise<{ modelUsed: string; completedCleanly: boolean }> {
  for (let i = 0; i < chain.length; i++) {
    const model = chain[i];
    try {
      // stream() は async iterable を返す
      const stream = client.messages.stream({ ...params, model });
 
      // 初回イベントを待つ(接続確立前エラーはここで捕捉できる)
      let streamStarted = false;
 
      for await (const event of stream) {
        if (!streamStarted && event.type === "message_start") {
          streamStarted = true;
        }
        if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
          onDelta(event.delta.text);
        }
      }
      return { modelUsed: model, completedCleanly: true };
    } catch (err) {
      if (!isStreamStartError(err) || i === chain.length - 1) {
        // ストリーム開始後のエラーは、ユーザーに見える形でログに残し、
        // 再接続は上位のハンドラに任せる
        onDelta("\n\n*[通信が途中で切れました。再送します]*");
        return { modelUsed: model, completedCleanly: false };
      }
      // 次モデルへフォールバック
    }
  }
  throw new Error("unreachable");
}
 
function isStreamStartError(err: unknown): boolean {
  if (err instanceof Anthropic.APIError) {
    return err.status === 429 || err.status === 529 || (err.status ?? 0) >= 500;
  }
  return false;
}