複数LLMプロバイダのフォールバック連鎖に新しい実行者を安全に追加する

コスト削減のために「安いLLMから順に試し、落ちたら次へ」というフォールバック連鎖を持っている環境で、 新しいプロバイダを実測にもとづいて正しい位置に差し込み、静かに壊れないことを保証するための手順書。

対象: OpenAI互換（/chat/completions）のエンドポイントを持つプロバイダ全般。

---

0. 前提となる設計（まだ無ければ先にこれを作る）

• llm-fallback.mjs: FALLBACK_CHAIN（順序付き配列）と callWithFallback() を持つ。
  • classifyFailure(status): 429 と 5xx と ネットワーク断 は retry、それ以外（401/402/403）は即 next。 無料枠切れ(402)や鍵ミス(401)でリトライするのは待ち時間の無駄。
  • キーが無い候補は payloadFor() が null を返してエラーにせず素通りする。
• llm-ask.mjs: PROVIDERS 表（base / keyEnv / keyFile / model）を持ち、--provider で1本化。

1. 「入れるかどうか」を実測で決める（憶測で足さない）

同じ難易度のタスクを N問 × 3回 全プロバイダに投げ、次の4指標を取る。

指標	意味	落とし穴
成功率	期待どおりの出力を返した割合	正規表現による自動採点は上位モデルを不当に落とす（冗長な前置きを付けるため）。採点条件を緩めるか目視する
$/task	実測単価	公称単価ではなく実際の usage から出す
中央値レイテンシ	体感速度	平均は外れ値に引っ張られる
到達性 (n/N)	そもそも応答が返った回数	これが最重要。無料枠のプロバイダは 429 や 402 で沈黙する

判断ルール:

• 既存の後段候補より「成功率」と「$/task」の両方で上回るなら、その候補の前に入れる。
• 到達性が満点でないプロバイダを後段に置いてはいけない（後段は最後の砦なので必ず繋がる必要がある）。
• 到達性が低くても安ければ前段に置く価値はある（落ちても後段が拾う）。

2. 実装（3ファイルだけ触る）

// llm-ask.mjs — PROVIDERS に1行足すだけ
newprovider: {
  base: 'https://api.example.com/v1/chat/completions',
  keyEnv: 'NEWPROVIDER_API_KEY',
  keyFile: 'newprovider.env',
  model: '<モデルID>'
},

// llm-fallback.mjs — 実測で決めた位置へ差し込む
export const FALLBACK_CHAIN = Object.freeze([
  { provider: 'fastest_cheap', model: '...' },
  { provider: 'newprovider',   model: '...' },   // ← ここ
  { provider: 'last_resort',   model: '...' },
]);

--provider の usage 文字列にも新しい名前を足す（忘れると「対応していない」と誤解される）。

3. 回帰テストは「配列全体」を pin する ← ここが本題

test('フォールバック候補は指定された順序である', () => {
  const providers = FALLBACK_CHAIN.map(({ provider }) => provider);
  assert.deepEqual(providers, ['a', 'b', 'newprovider', 'c']);   // 全体を固定
  assert.ok(providers.indexOf('newprovider') < providers.indexOf('c'));
});

slice(0, 2) や includes() による部分検査は禁止。 複数人・複数エージェントが同じリポジトリを触る環境では、 別ブランチが古い基点から同じ配列を編集し、あなたのエントリを消したまま緑で通ることが実際に起きる。 配列全体を deepEqual で固定していれば、その時に merge conflict か CI 赤として必ず可視化される。

同じ理由で、順序が意味を持つ共有定数（優先度リスト・ルーティング表・権限順）はすべて全体 pin にする。

4. 検証（ユニットテストだけで「動く」と言わない）

4段階すべて通してから完了とする。

# ① ユニット
node --test tools/llm-fallback.test.mjs

# ② 実キーで単体疎通（フォールバックを切って、その1社だけを叩く）
node tools/llm-ask.mjs --provider newprovider --no-fallback "1+1は? 数字だけ"

# ③ 多段フォールバックの実走 ← いちばん重要
#    先行候補の鍵を「無効な値」で上書きして起動する。未設定にすると素通りされて
#    フォールバック経路そのものを検証できないので、必ず "無効値" にすること。
A_API_KEY=bogus B_API_KEY=bogus node tools/llm-ask.mjs --provider a "日本の首都は?"
#    期待: [failover] a HTTP401 → b / [failover] b HTTP401 → newprovider / 応答本文

# ④ 配布している場合: 利用者が実際に取得するURLを叩いて新版が配信されているか確認
curl -s "https://<配布元>/<path>/llm-fallback.mjs?cb=$RANDOM" | grep newprovider

--no-fallback を付け忘れると②が別プロバイダの成功を拾ってしまい、 鍵が壊れていても「動いた」と誤判定する。

5. ドキュメントの矛盾を必ず消す

実測で方針が変わったなら、過去に「この実行者は使わない」と書いた運用ドキュメントを同じPRで直す。 チェーンだけ変えてドキュメントを残すと、次に読んだAI/人が古い記述に従って元に戻す。

6. レビュー観点（実装をコード生成AIに委譲した場合は特に）

• diff の削除行を読む。指示していない既存挙動（リトライ回数・失敗分類・待機ロジック）が変わっていないか
• 鍵未設定のマシンでエラーにならず素通りするか
• 台帳/ログに新プロバイダ名が正しく記録されるか（コスト集計が壊れない）

---

チェックリスト

• 実測4指標（成功率 / $per task / レイテンシ / 到達性）を取った
• 後段に置く候補の到達性が満点である
• PROVIDERS / FALLBACK_CHAIN / usage文字列 の3箇所を更新した
• 順序テストが配列全体を deepEqual で固定している
• --no-fallback 付きの単体疎通が通った
• 先行候補を無効値で潰した多段フォールバックが新候補に到達した
• 矛盾する運用ドキュメントを同じPRで直した