# 複数LLMプロバイダの無料枠切れを検知して自動で次候補へ差し替える 安いLLM（無料枠・激安API）に処理を逃がしてコストを下げる構成は広く使われるが、**無料枠が切れた瞬間に黙って落ちる**という落とし穴がある。しかも落ちたことが記録されないため、誰も気づかない。結果その作業は一番高いモデルへ逆流する。 この指示書は、その検知とフォールバックを実装する手順と、**連鎖の順番を実測で決める方法**をまとめたもの。 ## この問題が実在することの確認（実測例） 同一時刻に4プロバイダを叩いたときの失敗率。1プロバイダの問題ではなく、無料枠は構造的に当てにならない。 | プロバイダ | 失敗 | HTTPステータス | 種類 | |---|---|---|---| | A（無料枠・高速LPU系） | 14/36 (39%) | 429 | 1日あたりトークン上限 | | B（無料枠・大文脈系） | 31/36 (86%) | 503 → 429 | 容量逼迫。15秒間隔で6回試して0/6 | | C（クレジット制ルーター） | 高額モデル全滅 | 402 | 残高不足 | | D（従量・中堅） | 15/36 (42%) | 429 | レート制限 | 一方、**前払い残高型の2社は36/36で無傷**だった。「安い」と「当てになる」は別の軸だと分かる。 ## 実装 ### 1. 失敗の分類を先に決める（ここが設計の核心） 一律リトライは間違い。**待って回復するものと、待っても回復しないもの**を分ける。 ``` retry にする: 429 / 5xx / ネットワーク例外・タイムアウト next にする : 401 / 402 / 403（認証切れ・残高不足・権限なし）とその他4xx ``` `402`（残高不足）を指数バックオフでリトライすると、**回復しないものを待ち続けて時間だけ捨てる**。ここを間違えると「フォールバックを入れたのに遅くなった」という結果になる。 ```js export function classifyFailure(status) { // status が null = ネットワーク例外 if (status == null || status === 429 || (status >= 500 && status <= 599)) return 'retry'; return 'next'; } ``` ### 2. 候補列は「課金プールを跨ぐ」ように並べる 同一ベンダー内で並べても、1つの壁で全滅する。**課金の出所が違うものを混ぜる**のが要点。 ```js export const FALLBACK_CHAIN = Object.freeze([ { provider: '<無料枠A>', model: '<安くて賢いモデル>' }, // 無料枠 { provider: '<クレジット制>', model: '<同じモデルの別経路>' }, // 前払いクレジット { provider: '<別ベンダー無料>', model: '<...>' }, // 別会社の無料枠 { provider: '<従量課金>', model: '<...>' }, // 従量 { provider: '<前払い残高>', model: '<...>' }, // 前払い（最後の砦） ]); ``` 2番手に「1番手と同じモデルの別経路」を置くと、差し替わっても出力の性質が変わらないので下流が壊れにくい。 **候補列は長くしてよい**。失敗は速い（429は実測130ms程度で返る）ので、通らない候補を挟むコストはほぼゼロ。だから「品質順に並べて、落ちたら次」で十分機能する。 ### 3. 実装は1箇所に集約する 即時実行のCLIと夜間バッチの2箇所に同じロジックを書くと必ず乖離する。共有モジュールにして両方から呼ぶ。 ```js export async function callWithFallback({ start, chain, payloadFor, fetchImpl, sleepImpl, onAttempt, onFailover }) { // start（呼び出し側が指定したもの）を先頭に、chain を順に。 // 既に試した provider は飛ばす。キーが無い候補はエラーにせず飛ばす。 // retry は同一候補で最大2回、指数バックオフ。 // Retry-After があれば尊重するが、60秒を超えるなら待たずに次候補へ。 // 全滅したときだけ throw し、候補ごとの理由を全部含めた要約を持たせる。 } ``` `fetchImpl` / `sleepImpl` を差し替え可能にしておく。これが無いとテストが実ネットワークを叩くことになり、レート制限の検証自体ができない。 ### 4. 失敗も台帳に記録する（これを忘れると全部無意味） 多くの実装は成功時だけ使用量ログを書く。すると**壁にぶつかっている事実が可視化されず**、「そのプロバイダを使っていない」ようにしか見えない。 試行ごとに1行、成功も失敗も記録する。プロンプト本文と応答本文は記録しない。 ```jsonl {"t":"...","provider":"A","model":"...","in":0,"out":0,"secs":0.13,"status":"http_429","attempt":0,"failover":false} {"t":"...","provider":"B","model":"...","in":81,"out":50,"secs":1.2,"status":"ok","attempt":0,"failover":true} ``` `status` / `attempt` / `failover` の3つがあれば、「どの無料枠が何回枯れたか」を後から集計できる。 ### 5. ログは1ホップ1行、ラベルと理由を必ず一致させる ここで実際にやった失敗を共有する。当初こう書いていた。 ```js // 誤り: from に常に最初の候補、reason に最後の失敗理由が入る onFailover({ from: start, to: candidate, reason: failures.at(-1)?.reason }); ``` 3段落ちたのに1行しか出ず、しかも**1番目の候補名に3番目のエラー本文がぶら下がる**。「Aが429」と書いてあるのに中身はBのエラーメッセージ、という状態で、原因追跡が不可能になった。 正しくは、**候補が失敗して次へ移る時点ごとに**呼び、`from` にはその失敗した候補自身、`reason` にはその候補自身の理由を渡す。エラー本文はそのまま出すと巨大なJSONで読めないので、改行を除いて140文字程度に切り詰める（詳細ログや例外サマリには全文を残す）。 ## 連鎖の順番を実測で決める カタログ単価だけで並べると失敗する。実際に踏んだ罠を3つ挙げる。 ### 罠1: 単価最安が実効最安ではない 思考トークンを出すモデルは、入出力単価が最安でも**出力量が10〜20倍**になる。実測では単価最安のモデルが `finish_reason: length` で15問中10問が切断され、実用不可だった。**実効単価は「1タスクあたりいくらか」で測る**。 ### 罠2: ベンチが飽和していると差が見えない 最初に易しいタスクで測ったとき、上位2モデルは同点で**失敗した問題まで同一**だった。難易度を上げたら30ポイント差がついた。**「差が出ない」は「差がない」ではなく「タスクが易しすぎる」を先に疑う**。 判別力のあるタスクの例（いずれも機械採点できる形にする）: - 多段の計算（値引き→原価率→利益率を小数第1位まで） - 複数制約の充足（除外条件を5個与えて「条件を満たす最も早い日」を1つ求めさせる） - 税込・税抜が混在した複数レコードの抽出と正規化 - 相対日付の解決（基準日を与えて「来月の第2月曜」等） - 否定制約の遵守（「この語を使わずに」「N文字以内で」） - 母語のニュアンス（時刻・敬語・婉曲表現の取り違え） ### 罠3: 正規表現採点は上位モデルを不当に落とす 最上位モデルが2問落ちたので原因を見たら、**両方とも採点側のバグ**だった。 - コード修正課題で `slice(-n)` しか正解と認めない正規表現を書いていたが、モデルは `slice(Math.max(len - n, 0))`（境界がより堅牢な正解）を返していた - 文章課題で「元の値に触れてはいけない」と機械的に禁止したが、モデルは正しい新値を明示した上で丁寧に確認を促していた **コードは実行して採点し、文章は判定モデルに採点させる**。これを直したら最上位モデルの正答率は86%→100%になった。採点を直す前の順位表を信じてはいけない。 **採点ロジック自体を検証する**。手書きの「正解のはずの回答」と「誤答のはずの回答」を各問に用意し、前者がpass・後者がfailになることを確認してから本番の計測に入る。 ### 計測の型 ``` 各モデル × 各タスク × 3回反復 記録: 正答/切断/エラーを区別 + 入出力トークン + 実測ms 集計: 到達性（成功コール数/総コール数）を正答率と別の列で持つ ``` **到達性を正答率に混ぜない**。無料枠が枯れているモデルは「正答率が低い」のではなく「そもそも返ってこない」。混ぜると品質の判断を誤る。実測では、成功したコールだけ見れば最高品質のモデルが、到達性5/36で実用不可だった。 ## 検証（ここまでやって初めて完了） 1. **スタブfetchのユニットテスト**（実ネットワークを叩かない） - 429 → 同一候補でリトライした後に次候補へ移る - 402 → **リトライも待機もせず**即座に次候補へ（待ち時間ゼロを確認） - 1番目が失敗し2番目が成功 → `failover: true` が記録される - 3候補連続失敗して4番目で成功 → ホップが3回記録され、各回の `from` と `reason` の組が正しい - キー未設定の候補は例外にせず飛ばされる - 全滅 → throw し、要約に候補ごとの理由が全部含まれる 2. **実キーでの実地確認**。無料枠が実際に枯れているタイミングは絶好の試験環境なので逃さない。枯れた候補を起点に指定して、差し替わって正答が返ることを確認する。 3. **フォールバック無効化フラグでの確認**。`--no-fallback` 相当を用意し、それを付けたときに差し替わらず非ゼロ終了することを確認する。**これが無いと「そのプロバイダが復活したか」を永久に確認できない**（付けずに叩くと他へ差し替わって成功してしまう）。 ## 運用上の注意 - クレジット制ルーターの `402` は `max_tokens × 単価` の**事前**チェックであることが多い。実使用量が小さくても残高が薄いと高いモデルを呼べない。「使った分だけ足す」では足りず、多少の余裕が必要。 - ローカル実行（GPU推論）を連鎖に入れる前に、そのマシンで実際に動くか確認する。実測では `llama-server process has terminated` で36/36全滅した環境があった。**動かないものを連鎖に入れると、失敗が1段増えるだけ**。 - 「導入済み」と「その瞬間に到達できる」は別。ツールの有無ではなく**到達性を継続監視する**。 ---