Antigravity × マルチプロバイダー LLM フェイルオーバー — Gemini / Claude / ローカル Gemma を止めない本番構成

// src/llm/provider.ts
// 目的: 各 LLM プロバイダーを同一インターフェースで扱い、ルーター層で切り替え可能にする
 
export interface LLMRequest {
  messages: Array<{ role: "system" | "user" | "assistant"; content: string }>;
  maxTokens?: number;
  temperature?: number;
  jsonSchema?: Record<string, unknown>;  // 能力軸: structured output 必要かの判定に使う
  minContextTokens?: number;              // 能力軸: 必要な入力トークン数
}
 
export interface LLMResponse {
  content: string;
  inputTokens: number;
  outputTokens: number;
  provider: string;       // "gemini" | "claude" | "gemma-local"
  latencyMs: number;
  attemptCount: number;   // フォールバック何回目で成功したか
}
 
export interface LLMProvider {
  readonly name: string;
  readonly capabilities: {
    maxContext: number;           // コンテキストウィンドウ上限
    supportsJsonSchema: boolean;  // Structured Output 対応
    requiresNetwork: boolean;     // ローカル実行可能かどうか
  };
  readonly cost: {
    inputPer1M: number;   // USD
    outputPer1M: number;  // USD
  };
  invoke(req: LLMRequest, signal: AbortSignal): Promise<LLMResponse>;
  healthCheck(): Promise<boolean>;  // ping 相当
}

// src/llm/gemini-provider.ts
import { GoogleGenerativeAI } from "@google/generative-ai";
import type { LLMProvider, LLMRequest, LLMResponse } from "./provider";
 
export class GeminiProvider implements LLMProvider {
  readonly name = "gemini";
  readonly capabilities = {
    maxContext: 1_048_576,
    supportsJsonSchema: true,
    requiresNetwork: true,
  };
  readonly cost = { inputPer1M: 0.15, outputPer1M: 0.6 };
 
  private client: GoogleGenerativeAI;
  private modelName = "gemini-2.5-flash";
 
  constructor(apiKey: string) {
    this.client = new GoogleGenerativeAI(apiKey);
  }
 
  async invoke(req: LLMRequest, signal: AbortSignal): Promise<LLMResponse> {
    const start = Date.now();
    const model = this.client.getGenerativeModel({
      model: this.modelName,
      generationConfig: {
        maxOutputTokens: req.maxTokens ?? 4096,
        temperature: req.temperature ?? 0.7,
        ...(req.jsonSchema ? { responseMimeType: "application/json", responseSchema: req.jsonSchema } : {}),
      },
    });
 
    // AbortSignal を SDK に渡す: タイムアウト時に確実にソケットを閉じるため
    const result = await model.generateContent({
      contents: req.messages.map((m) => ({ role: m.role === "assistant" ? "model" : m.role, parts: [{ text: m.content }] })),
    }, { signal });
 
    const text = result.response.text();
    const usage = result.response.usageMetadata;
 
    return {
      content: text,
      inputTokens: usage?.promptTokenCount ?? 0,
      outputTokens: usage?.candidatesTokenCount ?? 0,
      provider: this.name,
      latencyMs: Date.now() - start,
      attemptCount: 1,
    };
  }
 
  async healthCheck(): Promise<boolean> {
    try {
      const controller = new AbortController();
      const timer = setTimeout(() => controller.abort(), 3000);
      await this.invoke(
        { messages: [{ role: "user", content: "ok" }], maxTokens: 5 },
        controller.signal
      );
      clearTimeout(timer);
      return true;
    } catch {
      return false;
    }
  }
}

// src/llm/circuit-breaker.ts
// 目的: 連続失敗回数を監視し、閾値超過で指定期間は呼び出しをスキップする
 
export type CircuitState = "closed" | "open" | "half-open";
 
export interface CircuitBreakerConfig {
  failureThreshold: number;   // 連続失敗何回で open にするか
  openDurationMs: number;     // open 状態を維持する時間
  halfOpenSuccessCount: number; // half-open で何回成功したら closed に戻すか
}
 
export class CircuitBreaker {
  private state: CircuitState = "closed";
  private consecutiveFailures = 0;
  private consecutiveHalfOpenSuccess = 0;
  private openedAt = 0;
 
  constructor(
    private readonly name: string,
    private readonly config: CircuitBreakerConfig,
  ) {}
 
  canExecute(): boolean {
    if (this.state === "closed") return true;
    if (this.state === "open") {
      const elapsed = Date.now() - this.openedAt;
      if (elapsed >= this.config.openDurationMs) {
        this.state = "half-open";
        this.consecutiveHalfOpenSuccess = 0;
        return true;
      }
      return false;
    }
    // half-open: 限定的に試行を許可
    return true;
  }
 
  recordSuccess(): void {
    if (this.state === "half-open") {
      this.consecutiveHalfOpenSuccess++;
      if (this.consecutiveHalfOpenSuccess >= this.config.halfOpenSuccessCount) {
        this.reset();
      }
      return;
    }
    this.consecutiveFailures = 0;
  }
 
  recordFailure(): void {
    if (this.state === "half-open") {
      // half-open で 1 回でも失敗したら即 open に戻す
      this.state = "open";
      this.openedAt = Date.now();
      return;
    }
    this.consecutiveFailures++;
    if (this.consecutiveFailures >= this.config.failureThreshold) {
      this.state = "open";
      this.openedAt = Date.now();
    }
  }
 
  private reset(): void {
    this.state = "closed";
    this.consecutiveFailures = 0;
    this.consecutiveHalfOpenSuccess = 0;
  }
 
  getState(): CircuitState {
    return this.state;
  }
}

// src/llm/router.ts
// 目的: リクエストを能力・遅延・コストの順で評価し、最適なプロバイダーへ振り分ける
 
import type { LLMProvider, LLMRequest, LLMResponse } from "./provider";
import { CircuitBreaker } from "./circuit-breaker";
 
interface ProviderSlot {
  provider: LLMProvider;
  breaker: CircuitBreaker;
  recentLatencyMs: number[];  // 直近 N 回のレイテンシ
}
 
export class LLMRouter {
  private slots: ProviderSlot[] = [];
  private readonly latencyWindow = 20;
 
  constructor(providers: LLMProvider[]) {
    this.slots = providers.map((p) => ({
      provider: p,
      breaker: new CircuitBreaker(p.name, {
        failureThreshold: 3,
        openDurationMs: 30000,
        halfOpenSuccessCount: 2,
      }),
      recentLatencyMs: [],
    }));
  }
 
  async execute(req: LLMRequest, timeoutMs = 20000): Promise<LLMResponse> {
    const candidates = this.rankProviders(req);
    if (candidates.length === 0) {
      throw new Error("No capable provider available for this request");
    }
 
    const errors: Array<{ provider: string; error: unknown }> = [];
    let attemptCount = 0;
 
    for (const slot of candidates) {
      if (!slot.breaker.canExecute()) {
        continue;  // open 状態のプロバイダーはスキップ
      }
      attemptCount++;
      const controller = new AbortController();
      const timer = setTimeout(() => controller.abort(), timeoutMs);
      try {
        const res = await slot.provider.invoke(req, controller.signal);
        clearTimeout(timer);
        slot.breaker.recordSuccess();
        this.recordLatency(slot, res.latencyMs);
        return { ...res, attemptCount };
      } catch (err) {
        clearTimeout(timer);
        slot.breaker.recordFailure();
        errors.push({ provider: slot.provider.name, error: err });
        // 次の候補に進む
      }
    }
 
    const errMsg = errors.map((e) => `${e.provider}: ${String(e.error)}`).join(" / ");
    throw new Error(`All providers failed after ${attemptCount} attempts — ${errMsg}`);
  }
 
  private rankProviders(req: LLMRequest): ProviderSlot[] {
    // 第 1 層: 能力軸でフィルタ
    const capable = this.slots.filter((s) => {
      if (req.jsonSchema && !s.provider.capabilities.supportsJsonSchema) return false;
      if (req.minContextTokens && req.minContextTokens > s.provider.capabilities.maxContext) return false;
      return true;
    });
 
    // 第 2 層: 遅延軸でソート（直近 20 回の中央値）
    // 第 3 層: 同遅延帯ならコスト順
    return capable.sort((a, b) => {
      const latA = this.medianLatency(a);
      const latB = this.medianLatency(b);
      const latDiff = latA - latB;
      if (Math.abs(latDiff) > 500) return latDiff;  // 500ms 以上の差は遅延で判断
      return a.provider.cost.outputPer1M - b.provider.cost.outputPer1M;
    });
  }
 
  private medianLatency(slot: ProviderSlot): number {
    if (slot.recentLatencyMs.length === 0) return 1500;  // 初期値
    const sorted = [...slot.recentLatencyMs].sort((a, b) => a - b);
    return sorted[Math.floor(sorted.length / 2)];
  }
 
  private recordLatency(slot: ProviderSlot, latencyMs: number): void {
    slot.recentLatencyMs.push(latencyMs);
    if (slot.recentLatencyMs.length > this.latencyWindow) {
      slot.recentLatencyMs.shift();
    }
  }
}

// src/main.ts
import { GeminiProvider } from "./llm/gemini-provider";
import { ClaudeProvider } from "./llm/claude-provider";
import { GemmaLocalProvider } from "./llm/gemma-local-provider";
import { LLMRouter } from "./llm/router";
 
const router = new LLMRouter([
  new GeminiProvider(process.env.GEMINI_API_KEY!),
  new ClaudeProvider(process.env.ANTHROPIC_API_KEY!),
  new GemmaLocalProvider("http://localhost:1234/v1"),  // LM Studio
]);
 
const res = await router.execute({
  messages: [{ role: "user", content: "製品説明を JSON で生成してください" }],
  jsonSchema: { type: "object", properties: { name: { type: "string" }, description: { type: "string" } } },
  maxTokens: 500,
});
 
console.log(`Provider: ${res.provider}, Attempts: ${res.attemptCount}, Latency: ${res.latencyMs}ms`);
// 例: "Provider: claude, Attempts: 2, Latency: 1843ms"
// Gemini が失敗し Claude にフォールバックしたことが 1 行で分かる

## 障害メモ YYYY-MM-DD
 
### 何が起きたか（事実だけ）
- 発生時刻 / 復旧時刻:
- 影響を受けたプロバイダー:
- フォールバック発生率のピーク:
- ユーザーに露出したエラー件数:
 
### 検知はどう働いたか
- 最初に気づいたきっかけ（アラート / 問い合わせ / 自分の目視）:
- アラートは想定どおり鳴ったか:
 
### ルーターはどう振る舞ったか
- サーキットは open になったか / 何秒で:
- フォールバック先は適切だったか:
- 想定外の挙動:
 
### 次への一手（1 つだけ）
- 設定値の変更 / コードの修正 / 監視の追加 のどれか 1 つ: