退役モデルを枠切れと区別して検知する仕組み
今回やったこと
AI CLI のモデル名がサービス側の更新で使えなくなったとき、単なる枠切れと同じ扱いにすると、失敗が見えなくなることがある。判定用のスクリプトは、退役や未知のモデルIDを識別し、実行前の照合と日次の棚卸しで知らせる。控えのエンジンが処理を引き継ぐ運用でも、設定の誤りを別枠の消費として隠さないための仕組みを紹介する。
フェイルオーバーが成功しても、設定が正しいとは限らない
2026年10月9日、接地判定で使っていた既定モデル claude-opus-4-6-thinking が、Antigravity 側のモデル一覧更新後に拒否された。CLI は「known model として認識されない」というエラーを返したが、次の候補である別エンジンが回答したため、レーン全体は停止しなかった。
処理結果だけ見ればフォールバックは機能している。しかし、その状態が続くと、本命モデルが使えないことに気づかず、予定していた複数の枠のうち一つが実際には使われないままになる。記録では、10月4日以降の判定が別エンジンへ寄っていたことが確認され、気付くまで5日間、本命の枠が機能していなかった。この事例の問題は、控えがあることではない。退役を通常の一時的な失敗として見えなくしたことにある。
実行時のエラーを分類する
判定用のスクリプトは、エラー出力に not recognized as a known model または invalid model selection が含まれるかを調べる。該当した場合は未知モデルとして記録し、stderr に明示し、設定された通知経路へ知らせる。一方、枠切れやタイムアウトはこの判定に該当しない。日常的に発生しうる一時的なエラーを同じ重大通知に混ぜないためだ。
ここでの役割は、モデルの失敗を検知して知らせることに限られる。呼び出し側が控えへ進むか停止するかは、そのレーンの設計に委ねられる。これにより、検知機構を追加しただけで既存の復旧動作まで変えてしまうことを避けている。
実行前と日次の二つの点検
エラーが起きた後に検知するだけでなく、実行前にも設定値を現在の一覧と照合できる。preflight は指定したモデルIDが agy models の一覧にあるか確認し、一覧に含まれない（未知の）IDである場合に知らせる。モデル一覧が取得できない場合は、全モデルを未知と誤判定してレーンを止めない。
さらに audit は、設定ファイルに書かれたモデルIDをまとめて一覧と突き合わせる。退役モデルを、実際にそのモデルを呼び出すまで待たずに見つけられる。コマンドの用途は次のように分かれる。
| 操作 | 確認すること | 通知・終了の考え方 |
|---|---|---|
models | CLI が現在返すモデル一覧 | 一覧取得のみ |
preflight --model <ID> | 実行前に指定IDが一覧にあるか | 未知なら通知。照合不能なら継続 |
audit | 設定にあるID全体の棚卸し | 既定では点検自体の失敗と未知IDを分ける |
audit --notify | 棚卸し結果の通知 | 未知IDを通知 |
audit --strict-exit | CIなどで未知IDを終了コードに反映 | 必要な場面だけ厳格化 |
日次棚卸しの既定終了コードは、未知IDがあっても0である。点検ジョブ自体が恒常的に失敗扱いとなって運用から外されるのを避けるためだ。CIなど、未知IDを失敗として扱いたい場面では --strict-exit を使える。
回帰テストでは誤報も抑える
回帰テストは、未知モデルの拒否文言を通知対象にするだけでなく、枠切れやタイムアウトを誤って退役扱いしないことも確認する。検知を広げすぎると、日々の一時的な失敗が本物の設定不備を覆い隠す。対照ケースを並べることで、鳴るべきときと鳴らないべきときを一緒に守る。
実装上はモデル一覧をキャッシュし、照合不能と空の一覧を区別する。ネットワークやCLIの一時障害を「設定済みモデルがすべて未知」と読むと大量の誤通知になるためだ。モデル一覧取得の記録では、一覧取得は枠を消費せず約2秒だったとされるが、これは2026年10月9日時点の実測であり、将来のCLIや環境での所要時間を保証する値ではない。
導入時に確認すること
モデルIDはコードだけでなく、環境変数、設定ファイル、起動定義にも置かれる。棚卸し対象が一部の設定だけに限られていれば、見つからない退役IDが残る。点検範囲を実際の呼び出し元と一致させ、通知先が動くこと、フォールバックした場合にも元のモデル失敗が記録されることを確認する必要がある。
対象は判定用のスクリプトと、その回帰テストである。この仕組みは未知モデルを検知するものであり、サービス側のモデル一覧変更そのものを防ぐものではない。モデル名の入れ替わりがあっても運用が静かに別経路へ流れないよう、異常を区別して観測できる状態を作る。
更新履歴
- 2026-10-18: 初稿作成。