AI API ゲートウェイのモデル非推奨 Runbook: サポート終了前のインベントリ、テスト、移行、ロールバック

ハードコードされたモデル ID は、本番環境の依存関係ではありません。これらは、プロバイダーがエンドポイントの名前を変更するか、日付付きスナップショットを廃止するか、エイリアスを変更するか、プレビュー モデルを削除するか、API レベルの非互換性を導入するまで機能します。この障害が 1 回の完全な停止として現れることはほとんどありません。これは、スキーマの障害、遅延の増加、予期しない拒否、ツール呼び出しの引数の違い、コストの変更、または急いで移行した後にワークロードの動作が異なるテナントからの顧客チケットとして現れます。

実際的な修正は、モデル ID をアプリケーション コード内の静的な文字列ではなく、管理された依存関係のように扱うことです。 AI API ゲートウェイでは、これは反復可能なモデルの非推奨ランブックを構築することを意味します。つまり、インベントリ、検出、影響の評価、置換のテスト、シャドウ トラフィック、段階的なロールアウト、互換性が壊れた場合の迅速なロールバックです。

事実、推奨事項、予測

事実: 主要なモデル プロバイダーは、モデル カタログ、バージョン管理ガイダンス、非推奨通知、移行ガイダンスを公開しています。これらのリソースは、モデルの可用性が静的ではないことを示しています。プロバイダによっては、便宜的なエイリアスを特定のモデル ID と区別しており、一部の移行には既存の統合を壊す API レベルの違いが含まれる場合があります。

推奨事項: モデルのライフサイクル制御をゲートウェイ内に置きます。論理モデル名をアプリケーション チームに公開し、プロバイダー モデルの使用状況を一元的に追跡し、非推奨ソースを監視し、運用トラフィックを切り替える前に互換性テストを実行します。

予測: モデルのライフサイクル操作は、AI プラットフォーム エンジニアリングの通常の部分になるでしょう。マルチプロバイダー システムを実行しているチームでは、バージョン インベントリ、変更ウィンドウ、回帰チェック、ロールバック プラン、顧客通知など、モデルに対する依存関係スタイルの制御がますます必要になります。

障害モード: アプリケーション コード中に散在するプロバイダー モデル ID

一般的な実装は単純に始まります:

{
  "model": "provider-model-preview-2025-06",
  "messages": [
    {"role": "user", "content": "Extract the invoice fields as JSON."}
  ]
}

これはプロトタイプでは簡単ですが、運用環境では危険です。モデル文字列は、バックエンド サービス、スクリプト、ローコード ワークフロー、内部ツール、顧客統合、パートナー製品間で重複する可能性があります。モデルがサポート終了に近づくと、基本的な質問に答えられる所有者は一人もいません:

• まだトラフィックを送信している API キーはどれですか?
• どのテナントが JSON スキーマ、ツール呼び出し、ストリーミング、ビジョン、オーディオ、または長いコンテキストに依存していますか?
• 1 日あたりの支出と収益はどれくらいですか?
• どのワークロードがより安価なモデルに耐えることができ、どのワークロードに品質レビューが必要ですか?
• チームはすべてのアプリケーションを再デプロイせずにロールバックできますか?

ゲートウェイはリクエスト、キー、テナント、プロバイダ、コスト、レイテンシ、障害をすでに認識しているため、この問題を解決するのは自然な場所です。

ステップ 1: モデル在庫テーブルを作成する

耐久性のある在庫から始めます。独自のテナント、キー、請求、ワークフロー コンテキストが必要であるため、プロバイダーのダッシュボードだけに依存しないでください。

実用的な model_inventory テーブルには次のものを含めることができます:

logical_model_name       support-fast
provider                 provider_a
provider_model_id         model-x-preview-2025-06
endpoint_type             chat_completions
alias_status              pinned_snapshot | provider_alias | internal_alias
status                    active | deprecated | blocked | retired
replacement_candidates    ["support-fast-v2", "support-balanced"]
first_seen_at             timestamp
last_seen_at              timestamp
deprecation_announced_at  timestamp
shutdown_at               timestamp
admin_override            text
owner_team                support-platform

次に、これを使用状況データと結合します。各プロバイダー モデルと論理モデルについて、次を追跡します:

• 有効なテナントと API キー
• 1 日あたりのリクエストと 1 日あたりのトークン
• 支出、マージン、または内部コストの割り当て
• 平均だけではないレイテンシのパーセンタイル
• 5xx 率、プロバイダー エラー率、タイムアウト率、および再試行率
• 構造化出力の使用法とスキーマの失敗率
• ツール呼び出しの使用法とツール実行の副作用
• ストリーミングの使用法
• テキスト、画像、音声、ファイル入力などのモダリティ
• コンテキストの長さの分布

このインベントリは、非推奨のアナウンスをパニックからクエリに変えます。

ステップ 2: 論理モデル名によるルーティング

アプリケーション チームは、すべてのプロバイダーのモデル ライフサイクル ルールを知る必要はありません。ワークロードの意図を表す安定した論理名を付けます:

• support-fast
• support-quality
• coding-premium
• invoice-extractor-v2
• content-moderation-default

ゲートウェイはこれらの名前をプロバイダー モデル ID にマッピングします:

{
  "logical_model": "invoice-extractor-v2",
  "routing_policy": {
    "primary": {
      "provider": "provider_a",
      "model": "model-x-stable-2025-09"
    },
    "constraints": {
      "requires_json_schema": true,
      "max_input_tokens": 64000,
      "region": "eu"
    }
  }
}

これは、プロバイダーの詳細をすべて非表示にすることを意味するものではありません。これは、プロバイダー固有の機能を製品コードに分散させるのではなく、ゲートウェイのメタデータに組み込むことを意味します。適切な抽象化では、アプリケーションが望むことと プロバイダが実際にできることの両方を示します。

ステップ 3: スケジュールされた操作として非推奨を監視する

非推奨モニターはスケジュールに従って実行し、手動オーバーライドをサポートする必要があります。プロバイダー モデルのカタログ、非推奨ページ、変更ログ、リリース ノート、および内部管理エントリをチェックする必要があります。すべてのライフサイクル信号がクリーンな機械可読 API を通じて利用できるわけではないため、オペレーターが日付を追加または修正できるようにしてください。

モニターがライフサイクル イベントを検出すると、内部レコードを作成します:

provider_model_id: model-x-preview-2025-06
status: deprecated
shutdown_at: 2026-02-15
recommended_replacements:
  - model-x-stable-2025-09
  - model-y-mini-2025-10
source_type: provider_deprecation_page
confidence: confirmed

その後、影響分析を自動的にトリガーします。非推奨の通知は、誰かが調査することを思い出すまでチャット チャネルに残すべきではありません。

ステップ 4: 影響レポートを生成する

影響レポートは、エンジニアリング、財務、サポート、パートナー チームにとって十分具体的なものである必要があります。インクルード:

• 非推奨のプロバイダー モデルと影響を受ける論理名
• シャットダウン日と推奨される決定期限
• 影響を受けるテナント、チーム、および API キー
• 毎日のリクエスト量とトークン量
• 1 日のコスト、顧客への請求エクスポージャー、および該当する場合はマージンへの影響
• モデルを使用する上位のエンドポイントまたは製品
• プロンプト カテゴリまたは保存されたプロンプト テンプレート
• JSON スキーマ、関数またはツール呼び出し、ストリーミング、画像、音声、ファイル、または長いコンテキストの使用
• 現在のレイテンシのパーセンタイルとエラー率
• 既知の契約上の制約またはデータ所在地の制約

パートナー API ユーザーの場合は、このメタデータのフィルタリングされたバージョンを公開して、代理店、再販業者、組み込み AI 製品ビルダーがプロバイダーのシャットダウンがダウンストリーム サービスに影響を与える前に自社の顧客に警告できるようにします。

ステップ 5: 機能別に代替候補リストを作成する

ブランド名だけで代替品を選択しないでください。ワークロードに対して候補者を採点します。

最新の主力モデルが必ずしも最良の代替品であるとは限りません。より小型の新しいモデルでは、大容量ワークロードのレイテンシとコストが維持される可能性があります。複雑なコーディング、抽出、推論のワークフローには、より高性能なモデルが必要になる場合があります。ランブックでは、デフォルトですべての非推奨をアップグレードに変えるのではなく、これを明示する必要があります。

ステップ 6: 互換性評価パックを実行する

実稼働ルーティングを変更する前に、実際のワークロードのリスクを反映する評価パックを実行してください。

最小評価セット

• ゴールデン プロンプト: 期待される特性を備えた安定した例。必ずしも 1 つの正確な答えが得られるわけではありません。
• スキーマの有効性テスト: JSON 解析の成功、必須フィールド、列挙値、長さ制限、およびネストされたオブジェクトのチェック。
• ツール呼び出しテスト: 正しいツールの選択、有効な引数、安全でない重複した副作用はありません。
• 安全性と拒否のチェック: 正当なビジネス リクエストがまだ完了していることを確認します。
• コストの比較: 入力トークン、出力トークン、再試行、および重複した呼び出し。
• レイテンシの比較: p50、p95、p99、タイムアウト レート、および関連する場合はストリーミングの最初のトークンのレイテンシ。
• 人によるレビュー: 自動チェックが不十分な、価値の高いワークフローや曖昧なワークフローには必要です。

構造化されたワークフローの場合、単一の自然言語品質スコアだけでは十分ではありません。置換では、ダウンストリーム コードが解析して信頼できる出力を生成する必要があります。

ステップ 7: 実稼働トラフィックを安全にシャドウイングする

シャドウ テストとは、実稼働リクエストのサンプルを候補モデルに複製し、現在のモデルの回答のみをユーザーに返すことを意味します。比較のために候補の応答を個別に保存します。

if route.shadow_enabled and request.is_safe_to_shadow:
    primary_response = call(current_model, request)
    enqueue_shadow_call(candidate_model, request, trace_id)
    return primary_response

すべてをシャドウしないでください。ツール実行レイヤーが無効になっているかモック化されている場合を除き、副作用のあるツール呼び出しを含むリクエストの重複を避けてください。機密データ、保持ルール、テナント契約には注意してください。シャドウ テストでは、一時的なトークンの使用量が増加しますが、厳選されたテスト ケースだけではなく、実際のプロンプトから証拠が得られます。

次のシャドウ結果を比較します:

• スキーマの有効性
• ツール呼び出しの互換性
• 出力の長さ
• 成功したリクエストごとのコスト
• レイテンシの分布
• 拒否とエラーのパターン
• タスク固有のレビュー結果

ステップ 8: パーセンテージベースのルーティングを使用してロールアウトする

候補者が評価に合格したら、段階的に展開します。すべてのアプリケーションを再デプロイするのではなく、テナント、キー、または論理モデルによるゲートウェイでのルーティング制御を優先します。

保守的なシーケンス:

1. 内部テナントのみ
2. 対象となる本番トラフィックの 1%
3. 5%
4. 25%
5. 50%
6. 100%

ロールアウトを開始する前にロールバックしきい値を定義します:

rollback_if:
  schema_failure_rate_increase: "> 1.0 percentage point"
  provider_5xx_rate: "> 2x baseline"
  p95_latency_increase: "> 30%"
  cost_per_successful_request: "> 25% over approved budget"
  tool_argument_validation_failures: "> 0.5%"
  tenant_blocklist_hit: "any critical tenant"

しきい値はワークロードによって調整する必要があります。チャットボットは、多くの場合、請求書抽出パイプラインよりも多くの文言のバリエーションを許容できます。バックグラウンド要約ジョブは、対話型サポート アシスタントよりも長い待ち時間を許容する場合があります。

ステップ 9: 移行中に請求の帰属を保持する

ゲートウェイがプロバイダー モデル ID のみを記録する場合、モデルの移行により使用状況分析が歪められる可能性があります。論理モデルと物理モデルの両方のディメンションを保持します:

tenant_id
api_key_id
logical_model_name
provider
provider_model_id
migration_id
input_tokens
output_tokens
provider_cost
customer_charge
latency_ms
status
schema_valid

migration_id が重要です。これにより、財務とサポートはロールアウト期間中に古い動作と新しい動作を比較できます。代替モデルの方が高価な場合、企業は差額を吸収するか、価格を更新するか、一部のテナントをより小規模なモデルに移行するか、顧客の承認を必要とするかを決定できます。

ステップ 10: 監査ログとロールバック計画を保存する

すべての移行は記録を残す必要があります:

• 非推奨モデルと代替モデル
• 影響を受ける論理モデル名
• 意思決定の所有者と承認者
• 影響レポートのリンク
• 評価結果
• シャドウ トラフィックの概要
• ロールアウトのタイムスタンプ
• ロールバックしきい値
• 顧客またはパートナーへの通知
• 最終ステータスと学んだ教訓

ロールバック計画は、願望的なものではなく、実行可能なものでなければなりません。古いプロバイダー モデルが間もなくシャットダウンされる場合、ロールバックとは、2 番目の代替候補へのルーティング、機能の無効化、より厳格なプロンプトの使用、または影響を受けるテナントの一時的な制限を意味する場合があります。カットオーバーの前に利用可能なオプションを文書化します。

管理すべきトレードオフ

• モデル ID を固定すると再現性が向上しますが、スナップショットが廃止されるとサポート終了のリスクが高まります。
• プロバイダ エイリアスはメンテナンスを軽減しますが、アプリケーションの下で動作が変わる可能性があるため、回帰監視が必要です。
• ゲートウェイ レベルの抽象化により移行が簡素化されますが、機能メタデータが明示的でない限り、プロバイダ固有の機能が隠蔽される可能性があります。
• シャドウ テストにより信頼性は向上しますが、リクエストが重複するため、一時的なトークンの使用量が増加します。
• 自動移行により停止リスクが軽減されますが、価格または一般的なベンチマーク スコアのみによって置き換えが選択される場合、セマンティックな回帰が発生する可能性があります。
• テナントごとのオーバーライドは重要な顧客を保護しますが、運用の複雑さとサポートの負担が増加します。
• 厳格な互換性ゲートにより構造化されたワークフローが保護されますが、迅速な変更やスキーマの変更が必要なより優れたモデルの導入が遅れる可能性があります。

実装チェックリスト

• プロバイダー モデルと論理モデル名の中央インベントリを作成します。
• 可能な限り、アプリケーション チームからの直接プロバイダー モデル ID をブロックします。
• プロバイダーのライフサイクル監視と手動管理オーバーライドを追加します。
• すべての非推奨イベントの影響レポートを生成します。
• 機能、コスト、レイテンシ、コンプライアンス、互換性による代替品のスコア。
• ゴールデン プロンプト、スキーマ チェック、ツール呼び出しチェック、安全性チェック、コスト比較を実行します。
• 置換を公開する前に、本番トラフィックをシャドウセーフにします。
• 事前定義されたロールバックしきい値を使用して、テナント、キー、またはパーセンテージごとにロールアウトします。
• 使用状況分析で論理モデル、プロバイダー モデル、移行 ID を追跡します。
• 下流の顧客が影響を受ける場合は、パートナー向け API を通じて非推奨メタデータを公開します。

実用的な結論

モデルの非推奨プロセスを設計する最も安全な時期は、次のシャットダウン通知の前です。まずは 1 つのルールから始めます。アプリケーションは論理モデル名を要求し、ゲートウェイはプロバイダー マッピングを所有します。次に、そのルールの周りに運用レイヤー (インベントリ、モニタリング、影響レポート、評価、シャドウ トラフィック、段階的ロールアウト、ロールバック、監査ログ) を追加します。

これにより、モデルの移行が直前の文字列置換から管理された依存関係ワークフローに変わります。目標は、モデルの動作を永久にフリーズさせることではありません。目標は、品質、コスト、レイテンシ、構造化出力の動作、および請求の帰属を維持しながらモデルを意図的に変更することです。

関連資料

• 構造化出力とツール呼び出しの互換性チェック
• LLM のルーティング制御とロールバック動作API
• パートナー向けテナントと使用状況メタデータ