安いLLMプロバイダのフォールバック連鎖を「本当に着地する」形で作る

複数の安い/無料LLMプロバイダを束ねて主モデル（高額な従量API）へのフォールバックを減らす構成の作り方。 「フォールバックを実装した」と「その瞬間に受け皿へ着地する」は別物で、後者を保証するための設計をまとめる。

前提となる問題

無料枠のプロバイダは枯れると黙って死ぬ。しかも死んだことがどこにも記録されないため、 「安いAIに逃がしているつもり」で実際には全部が主モデル（一番高い経路）へ逆流する。

ある実測（7日分の呼び出し台帳を集計）:

provider	成功	失敗	内訳
無料枠A（1番手）	120	34	429×31 = 1番手が22%落ちる
クレジット制B	125	9	402×8 = 残高ゼロ
無料枠C	2	30	429×29 = 94%死亡
前払いD/E/F	13	1	無傷＝本来の受け皿

無料枠は「安い」が「当てにならない」。前払い/定額の別勘定だけが受け皿になる。

設計1: 失敗コードを2種類に分ける

待てば直る失敗と、待っても直らない失敗を混ぜない。

export function classifyFailure(status) {
  // 429(レート超過) / 5xx / ネットワーク例外 → リトライする価値がある
  if (status == null || status === 429 || (status >= 500 && status <= 599)) return 'retry';
  // 401(無効キー) / 402(残高ゼロ) / 403(権限なし) → 待っても回復しない。即次候補へ
  return 'next';
}

401/402/403 を指数バックオフでリトライするのは純粋な時間の無駄。 失敗は速い（429は約130ms）ので、候補列は長くてよい。 速く落ちる前提で品質順に並べる。

Retry-After は尊重するが、60秒を超える指定は待たずに次候補へ送る。

設計2: 候補列は課金プールを跨がせる

同一ベンダー・同一課金プール内で連鎖させると、1つの壁で全滅する。

無料枠 → 定額サブスク → 前払いで最も安いもの → クレジット制 → 別の無料枠 → 前払い(高品質)

重要: 並び順は「カタログ上の単価」ではなく実測の成功率で決める。 上の実測例では、死んでいる無料枠が前に居たせいで、生きている前払いに届くまで 毎回2〜3ホップ無駄にしていた。実際に生きている最安のものを、死んだ無料枠より前に出す。

設計3: クールダウン（これが本体）

一度 402 を返したプロバイダは、次の呼び出しでも 402 を返す。毎回叩くのは無駄。 状態をファイルに永続化して、一定時間スキップする。

// 401/402/403 → 6時間  /  429 → Retry-After があればその値、無ければ30分
// 5xx・ネットワーク例外 → クールダウンしない（一過性のため）
// 成功したらそのプロバイダのエントリを削除する

最重要の落とし穴 — 全候補がクールダウン中になったら、クールダウンを無視して全部試す。

const available = candidates.filter(c => !(cooldowns[c.provider]?.until > now));
const selected = available.length ? available : candidates;  // ← 候補ゼロにしない

これを忘れると「受け皿が1つも無い」状態を自分で作る。元の不具合より悪化する。

その他の必須ガード:

• 状態ファイルが壊れた JSON でも握り潰して「クールダウン無し」で続行する。 クールダウン機構の故障で本体が止まってはいけない。
• 呼び出し側が単一プロバイダを明示指定した場合（--no-fallback 相当）はクールダウンを適用しない。

設計4: 日次スペンド上限

フォールバックが効くようになると、今度は「バグでループして課金が膨らむ」リスクが出る。 呼び出し台帳から当日分の概算コストを集計し、閾値で警告/停止する。

// 環境変数で上書き可能にする。警告=処理続行、停止=呼び出す前に throw
const warn = Number(process.env.LLM_DAILY_WARN_USD) || 1;
const hard = Number(process.env.LLM_DAILY_HARD_USD) || 5;
if (cost > hard) throw new Error(`本日の従量上限 $${hard} に達したため停止（概算 $${cost.toFixed(2)}）`);

集計は連鎖の冒頭で1回だけ行う（1ホップごとに再集計しない）。台帳が無い/壊れている場合は 0 として扱い、絶対に止めない。

設計5: 失敗も台帳に記録する

成功時だけ記録する台帳では、壁の存在自体を誰も検知できない。

{"t":"...","provider":"...","model":"...","in":0,"out":0,"secs":0.23,
 "status":"http_429","attempt":0,"failover":true}

プロンプト本文は記録しない。status/attempt/failover の3つがあれば 「どのプロバイダが何回落ちて、どこへ逃げたか」が後から集計できる。

ログは1ホップ1行で、ラベルと理由を必ず一致させる。 実装当初に from: 連鎖の起点 と reason: 最後の失敗理由 を渡してしまい、 「Aのラベルに Bのエラー本文」という誤ログを出して原因追跡が不能になった。

最大の落とし穴: 呼び出し側が共有フォールバックを使っていない

これが「フォールバックが機能しない」の実際の真因だった。

共有モジュールが正しく動いていても、次のような呼び出し側は別物として壊れる:

1. 自前のミニ連鎖をベタ書きしている（例: [主, 副] の2択だけ） → 両方が同時に壁に当たると受け皿が消える
2. 共有フォールバックを外側の短いタイムアウトで包んでいる → 連鎖3ホップ＋リトライは15秒に収まらず、着地する前に打ち切られる。 外側のタイムアウトは連鎖全体が走れる長さ（60秒程度）にする
3. 二重フォールバック（自前ループの中で、内側もフォールバックするヘルパーを呼ぶ） → 挙動が読めず、片方の「無効化」判定がもう片方を殺す

判定基準: 「フォールバックは実装済みか」ではなく「この呼び出し経路で実際に着地するか」。 全呼び出し側を洗い出して共有モジュールへ一本化する。

落とし穴: テストが実環境の状態ファイルを壊す

クールダウンのような永続状態を足すとき、既定の保存先をユーザーのホーム配下にすると、 テストのスタブ応答（401/402/403）がそのまま実環境に書き込まれる。

実際に踏んだ事故: テストを1回走らせただけで主要プロバイダ4つが全部6時間停止した。 ＝直そうとしていた不具合を、より広範囲に作り込んでいた。 表面的な症状は「既存テストが数件落ちる」で、これは実ファイル経由でテスト同士が汚染し合った結果にすぎない。 ここで期待値を書き換えて緑にしていたら、本番の重大バグを緑で塗り潰していた。

対策は2段構え:

1. 全テスト（既存分も漏れなく）に一時ディレクトリを渡す

const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'fallback-'));
// cooldownFile / ledgerFile を dir 配下に向ける。テスト後に後片付け

2. 実装側にも多重防御を入れる。テストランナー配下で保存先が明示されていなければ永続化を一切しない

const usePersist = cooldownFile != null || !process.env.NODE_TEST_CONTEXT;

将来テストを書き足す人が渡し忘れても実環境を壊さない。 実行後に「その実ファイルが作られていないこと」を確認するまで完了と言わない。

コスト判断: 受け皿の課金をケチらない

上の実測環境での安いプロバイダ群の実額は 7日で $0.10（月 $0.44）。 全部いちばん高い受け皿（$3/$15 per M tok クラス）に落ちても月 $3.8。

対して同期間の主モデルの出力は 11,401k tok。 受け皿の課金より、フォールバック不全で作業が主モデルへ逆流するコストの方が3桁大きい。

受け皿の残高切れをケチる判断は常に間違い。上限だけ付けて払う。

クレジット制サービスの罠: 自動補充は初回購入まで発動しない

「自動補充を有効にした＝課金設定済み」ではない。多くのサービスで 初回の手動購入で決済手段が登録されるまで自動補充は一度も発動しない。 その間エラー本文は「このアカウントは一度もクレジットを購入していない」と言い続ける。

確認方法: 残高画面の取引履歴が0件なら、自動補充は設定されていても機能していない。

なお、フォールバック連鎖が正しく動くようになった後は、 自動補充は可用性のためには不要になる（枯れてもクールダウンで飛ばして次へ行くため）。 予期しない大口請求を避けたいなら自動補充はオフにしてよい。

完了条件（実行して確認する）

ユニットテストだけでは足りない。実際に落として着地を見る。

1. 1番手のキーを意図的に無効化 → ログに [failover] A → D が出て1ホップで着地すること
2. 同じ呼び出しをもう一度 → [cooldown] A はスキップ (http_401, 残りN分) で即スキップされること
3. 台帳を細工して上限超過を作る → 呼び出す前に停止すること／閾値を上げれば通ること
4. 共有フォールバックへ寄せた全呼び出し側を実走させ、成功件数と失敗件数を確認すること
5. テスト実行後に実環境の状態ファイルが作られていないこと

実環境を汚さずに1〜3を試すには、一時ディレクトリをホームに見立てて（HOME 相当の環境変数を上書きして） キーだけ実物をコピーし、1番手のキーファイルだけ無効値に差し替える。