# 複数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ファイルだけ触る） ```js // llm-ask.mjs — PROVIDERS に1行足すだけ newprovider: { base: 'https://api.example.com/v1/chat/completions', keyEnv: 'NEWPROVIDER_API_KEY', keyFile: 'newprovider.env', model: '<モデルID>' }, ``` ```js // llm-fallback.mjs — 実測で決めた位置へ差し込む export const FALLBACK_CHAIN = Object.freeze([ { provider: 'fastest_cheap', model: '...' }, { provider: 'newprovider', model: '...' }, // ← ここ { provider: 'last_resort', model: '...' }, ]); ``` `--provider` の usage 文字列にも新しい名前を足す（忘れると「対応していない」と誤解される）。 ## 3. 回帰テストは「配列全体」を pin する ← ここが本題 ```js 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段階すべて通してから完了とする。 ```bash # ① ユニット 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 / 応答本文 ``` ```bash # ④ 配布している場合: 利用者が実際に取得するURLを叩いて新版が配信されているか確認 curl -s "https://<配布元>//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で直した ---