AI API ゲートウェイのモデル非推奨 Runbook: サポート終了前のインベントリ、テスト、移行、ロールバック
モデル ID を管理された依存関係として扱うための実践的なランブック: インベントリの使用状況、非推奨の検出、スコアの置換、互換性テストの実行、トラフィックのシャドウイング、段階的なロールアウト、請求帰属の保持。
ハードコードされたモデル ID は、静かな運用依存関係です。これらは、プロバイダーがエンドポイントの名前を変更するか、日付付きスナップショットを廃止するか、エイリアスを変更するか、プレビュー モデルを削除するか、API レベルの非互換性を導入するまで機能します。この障害が 1 回の完全な停止として現れることはほとんどありません。これは、スキーマの障害、レイテンシーの増加、予期せぬ拒否、ツール呼び出しの引数の違い、コストの変更、または急いで移行した後にワークロードの動作が異なるテナントからの顧客チケットとして現れます。
実際的な修正は、モデル ID をアプリケーション コード内の静的な文字列ではなく、管理された依存関係のように扱うことです。 AI API ゲートウェイでは、これは反復可能なモデルの非推奨ランブックを構築することを意味します。つまり、インベントリ、検出、影響の評価、置換のテスト、シャドウ トラフィック、段階的なロールアウト、互換性が壊れた場合の迅速なロールバックなどです。
事実、推奨事項、予測
事実: 主要なモデル プロバイダーは、モデル カタログ、バージョン管理ガイダンス、非推奨通知、移行ガイダンスを公開しています。これらのリソースは、モデルの可用性が静的ではないことを示しています。プロバイダによっては、便利なエイリアスを特定のモデル ID と区別しており、一部の移行には、既存の統合を壊す API レベルの違いが含まれる場合があります。
推奨事項: モデルのライフサイクル制御をゲートウェイ内に置きます。論理モデル名をアプリケーション チームに公開し、プロバイダー モデルの使用状況を一元的に追跡し、非推奨ソースを監視し、本番トラフィックを切り替える前に互換性テストを実行します。
予測: モデルのライフサイクル操作は、AI プラットフォーム エンジニアリングの通常の部分になるでしょう。マルチプロバイダー システムを実行しているチームでは、バージョン インベントリ、変更ウィンドウ、回帰チェック、ロールバック プラン、顧客通知など、モデルに対する依存関係スタイルの制御がますます必要になります。
障害モード: アプリケーション コード中に散在するプロバイダー モデル ID
一般的な実装は単純に始まります。
{
"モデル": "プロバイダーモデル-プレビュー-2025-06",
「メッセージ」: [
{"role": "user", "content": "請求書のフィールドを JSON として抽出します。"}
】
}これはプロトタイプでは簡単ですが、実稼働環境では危険です。モデル文字列は、バックエンド サービス、スクリプト、ローコード ワークフロー、内部ツール、顧客統合、パートナー製品間で重複する可能性があります。モデルがサポート終了に近づくと、基本的な質問に答えられる所有者は一人もいません。
- まだトラフィックを送信している API キーはどれですか?
- JSON スキーマ、ツール呼び出し、ストリーミング、ビジョン、オーディオ、または長いコンテキストに依存するテナントはどれですか?
- 1 日あたりの支出と収益はどれくらいですか?
- 安価なモデルに耐えられるワークロードと品質レビューが必要なワークロードはどれですか?
- チームはすべてのアプリケーションを再デプロイせずにロールバックできますか?
ゲートウェイは、リクエスト、キー、テナント、プロバイダー、コスト、レイテンシ、障害をすでに認識しているため、この問題を解決するのに自然な場所です。
ステップ 1: モデル在庫テーブルを作成する
耐久性のある在庫から始めます。独自のテナント、キー、請求、ワークフロー コンテキストが必要であるため、プロバイダーのダッシュボードだけに依存しないでください。
実際の model_inventory テーブルには以下を含めることができます。
logical_model_name support-fast
プロバイダプロバイダ_a
Provider_model_id モデル-x-プレビュー-2025-06
endpoint_type チャット完了
alias_status ピン留めされたスナップショット |プロバイダー_エイリアス |内部エイリアス
ステータスがアクティブ |廃止されました |ブロックされました |退職した
replace_candidates ["support-fast-v2"、"support-balance"]
first_seen_at タイムスタンプ
last_seen_at タイムスタンプ
deprecation_announced_at タイムスタンプ
shutdown_at タイムスタンプ
admin_override テキスト
owner_team サポート プラットフォーム次に、これを使用状況データと結合します。プロバイダー モデルと論理モデルごとに、以下を追跡します。
- 有効なテナントと API キー
- 1 日あたりのリクエストと 1 日あたりのトークン
- 支出、マージン、または内部コストの配分
- 単なる平均ではなく、レイテンシのパーセンタイルを表示
- 5xx 率、プロバイダー エラー率、タイムアウト率、再試行率
- 構造化された出力の使用法とスキーマの失敗率
- ツール呼び出しの使用法とツール実行の副作用
- ストリーミングの使用量
- テキスト、画像、音声、ファイル入力などのモダリティ
- コンテキストの長さの分布
このインベントリは、非推奨のアナウンスをパニックからクエリに変えます。
ステップ 2: 論理モデル名によるルーティング
アプリケーション チームは、すべてのプロバイダーのモデル ライフサイクル ルールを知っている必要はありません。ワークロードの意図を表す安定した論理名を付けます。
高速サポートサポート品質コーディングプレミアムinvoice-extractor-v2コンテンツモデレーションデフォルト
ゲートウェイは、これらの名前をプロバイダー モデル ID にマッピングします。
{
"logical_model": "invoice-extractor-v2",
"ルーティング_ポリシー": {
"プライマリ": {
"プロバイダー": "プロバイダー_a",
"モデル": "モデル-x-stable-2025-09"
}、
「制約」: {
"requires_json_schema": true、
"max_input_tokens": 64000、
「地域」: 「EU」
}
}
}これは、プロバイダーの詳細をすべて非表示にするという意味ではありません。これは、プロバイダー固有の機能を製品コードに分散させるのではなく、ゲートウェイのメタデータに組み込むことを意味します。優れた抽象化は、アプリケーションが何を望んでいるのかとプロバイダが実際に何ができるのかの両方を示します。
ステップ 3: スケジュールされた操作として非推奨を監視する
非推奨モニターはスケジュールに従って実行し、手動によるオーバーライドをサポートする必要があります。プロバイダー モデルのカタログ、非推奨ページ、変更ログ、リリース ノート、および内部管理エントリをチェックする必要があります。すべてのライフサイクル信号がクリーンな機械可読 API を通じて利用できるわけではないため、オペレーターが日付を追加または修正できるようにします。
モニターがライフサイクル イベントを検出すると、内部レコードを作成します。
provider_model_id:model-x-preview-2025-06
ステータス: 非推奨
シャットダウン時刻: 2026-02-15
推奨交換品:
- モデル-x-安定版-2025-09
- モデル-y-mini-2025-10
ソースタイプ: Provider_deprecation_page
信頼性: 確認済み次に、影響分析を自動的にトリガーします。非推奨の通知は、誰かが調査することを忘れない限り、チャット チャネルに残すべきではありません。
ステップ 4: 影響レポートを生成する
影響レポートは、エンジニアリング、財務、サポート、パートナー チームにとって十分に具体的なものである必要があります。含める:
- 非推奨のプロバイダー モデルと影響を受ける論理名
- シャットダウン日と推奨される決定期限
- 影響を受けるテナント、チーム、API キー
- 毎日のリクエスト量とトークン量
- 1 日あたりのコスト、顧客への請求エクスポージャ、および該当する場合はマージンへの影響
- モデルを使用する上位のエンドポイントまたは製品
- プロンプト カテゴリまたは保存されたプロンプト テンプレート
- JSON スキーマ、関数またはツールの呼び出し、ストリーミング、画像、音声、ファイル、または長いコンテキストの使用
- 現在のレイテンシのパーセンタイルとエラー率
- 既知の契約上の制約またはデータ所在地の制約
パートナー API ユーザーの場合は、このメタデータのフィルタリングされたバージョンを公開して、代理店、再販業者、組み込み AI 製品ビルダーがプロバイダーのシャットダウンがダウンストリーム サービスに影響を与える前に自社の顧客に警告できるようにします。
ステップ 5: 機能別に代替候補リストを作成する
ブランド名だけで代替品を選択しないでください。ワークロードに対して候補者を採点します。
<テーブル> <頭>最新のフラッグシップ モデルが必ずしも最良の代替品であるとは限りません。より小型の新しいモデルでは、大容量ワークロードのレイテンシとコストが維持される可能性があります。複雑なコーディング、抽出、推論のワークフローには、より高性能なモデルが必要になる場合があります。ランブックでは、デフォルトですべての非推奨をアップグレードに変えるのではなく、これを明示する必要があります。
ステップ 6: 互換性評価パックを実行する
本番ルーティングを変更する前に、実際のワークロードのリスクを反映する評価パックを実行してください。
最小評価セット
- ゴールデン プロンプト: 期待される特性を備えた安定した例。必ずしも 1 つの正確な答えが得られるわけではありません。
- スキーマの有効性テスト: JSON 解析の成功、必須フィールド、列挙値、長さ制限、ネストされたオブジェクトのチェック。
- ツール呼び出しテスト: 正しいツールの選択、有効な引数、安全でない重複した副作用がないこと。
- 安全性と拒否のチェック: 正当なビジネス リクエストがまだ完了していることを確認します。
- コストの比較: 入力トークン、出力トークン、再試行、および重複した呼び出し。
- レイテンシの比較: p50、p95、p99、タイムアウト率、および関連する場合、ストリーミングの最初のトークンのレイテンシ
- 人間によるレビュー: 自動チェックでは不十分な、価値の高いワークフローや曖昧なワークフローに必要です。
構造化されたワークフローの場合、単一の自然言語品質スコアだけでは十分ではありません。置換では、ダウンストリーム コードが解析して信頼できる出力を生成する必要があります。
ステップ 7: 実稼働トラフィックを安全にシャドウイングする
シャドウ テストとは、実稼働リクエストのサンプルを候補モデルに複製し、現在のモデルの回答のみをユーザーに返すことを意味します。比較のために候補の回答を個別に保存します。
route.shadow_enabled および request.is_safe_to_shadow の場合:
Primary_response = call(current_model, request)
enqueue_shadow_call(candidate_model、リクエスト、trace_id)
プライマリ応答を返すすべてをシャドウしないでください。ツール実行レイヤーが無効になっているかモック化されている場合を除き、副作用のあるツール呼び出しを含むリクエストの重複を避けてください。機密データ、保持ルール、テナント契約には注意してください。シャドウ テストでは、一時的なトークンの使用量が増加しますが、厳選されたテスト ケースだけではなく、実際のプロンプトから証拠が得られます。
シャドウの結果を比較します:
- スキーマの有効性
- ツール呼び出しの互換性
- 出力の長さ
- 成功したリクエストあたりのコスト
- レイテンシの分布
- 拒否とエラーのパターン
- タスク固有のレビュー結果
ステップ 8: パーセンテージベースのルーティングをロールアウトする
候補者が評価に合格したら、段階的にロールアウトします。すべてのアプリケーションを再デプロイするのではなく、テナント、キー、または論理モデルによるゲートウェイでのルーティング制御を優先します。
保守的なシーケンス:
<オル>ロールアウトを開始する前にロールバックしきい値を定義します:
rollback_if:
schema_failure_rate_increase: "> 1.0 パーセント ポイント"
Provider_5xx_rate: "> 2x ベースライン"
p95_latency_increase: "> 30%"
成功したリクエストあたりのコスト: > 承認された予算を 25% 上回りました"
ツール引数検証失敗: "> 0.5%"
tenant_blocklist_hit: "重要なテナント"しきい値はワークロードに応じて調整する必要があります。チャットボットは、多くの場合、請求書抽出パイプラインよりも多くの文言のバリエーションを許容できます。バックグラウンド要約ジョブは、対話型サポート アシスタントよりも長い待ち時間を許容する場合があります。
ステップ 9: 移行中に請求の帰属を保持する
ゲートウェイがプロバイダー モデル ID のみを記録する場合、モデルの移行により使用状況分析が歪められる可能性があります。論理モデルと物理モデルの両方のディメンションを保持します:
テナント ID
api_key_id
論理モデル名
プロバイダー
プロバイダーモデルID
移行ID
入力トークン
出力トークン
プロバイダーコスト
customer_charge
latency_ms
ステータス
スキーマ_有効migration_id が重要です。これにより、財務とサポートはロールアウト期間中に古い動作と新しい動作を比較できます。代替モデルの方が高価な場合、企業は差額を吸収するか、価格を更新するか、一部のテナントをより小規模なモデルに移行するか、顧客の承認を必要とするかを決定できます。
ステップ 10: 監査ログとロールバック計画を保存する
すべての移行は記録を残す必要があります:
- 非推奨モデルと代替モデル
- 影響を受ける論理モデル名
- 意思決定の所有者と承認者
- 影響レポートへのリンク
- 評価結果
- シャドウ トラフィックの概要
- ロールアウトのタイムスタンプ
- ロールバックしきい値
- 顧客またはパートナーへの通知
- 最終ステータスと学んだ教訓
ロールバック計画は、願望的なものではなく、実行可能なものである必要があります。古いプロバイダー モデルが間もなくシャットダウンされる場合、ロールバックとは、2 番目の代替候補へのルーティング、機能の無効化、より厳格なプロンプトの使用、または影響を受けるテナントの一時的な制限を意味する場合があります。カットオーバーの前に、利用可能なオプションを文書化します。
管理すべきトレードオフ
- モデル ID を固定すると再現性が向上しますが、スナップショットが廃止されるとサポート終了のリスクが高まります。
- プロバイダ エイリアスはメンテナンスを軽減しますが、アプリケーションの下での動作が変わる可能性があるため、回帰監視が必要です。
- ゲートウェイ レベルの抽象化により移行が簡素化されますが、機能メタデータが明示的でない限り、プロバイダー固有の機能が隠蔽される可能性があります。
- シャドウ テストにより信頼性は向上しますが、リクエストが重複するため、一時的なトークンの使用量が増加します。
- 自動移行により停止のリスクが軽減されますが、価格や一般的なベンチマーク スコアのみによって置き換えが選択された場合、セマンティックな退行が発生する可能性があります。
- テナントごとのオーバーライドは重要な顧客を保護しますが、運用の複雑さとサポートの負担が増加します。
- 厳格な互換性ゲートにより、構造化されたワークフローが保護されますが、迅速な変更やスキーマの変更が必要な、より優れたモデルの導入が遅れる可能性があります。
実装チェックリスト
- プロバイダ モデルと論理モデル名の集中インベントリを作成する
- 可能な限り、アプリケーション チームから直接プロバイダー モデル ID をブロックする
- プロバイダーのライフサイクル監視と手動による管理者オーバーライドを追加します。
- すべての非推奨イベントの影響レポートを生成する
- 機能、コスト、レイテンシ、コンプライアンス、互換性によって代替品のスコアを評価する
- ゴールデン プロンプト、スキーマ チェック、ツール呼び出しチェック、安全性チェック、コスト比較を実行する
- 代替を公開する前に本番トラフィックをシャドウセーフにする
- 事前定義されたロールバックしきい値を使用して、テナント、キー、またはパーセンテージごとにロールアウトします。
- 使用状況分析で論理モデル、プロバイダー モデル、移行 ID を追跡します。
- 下流の顧客が影響を受ける場合、パートナー向け API を通じて非推奨メタデータを公開する
実行可能な結論
モデルの非推奨プロセスを設計する最も安全な時期は、次のシャットダウン通知の前です。まずは 1 つのルールから始めます。アプリケーションは論理モデル名を要求し、ゲートウェイはプロバイダー マッピングを所有します。次に、そのルールの周りに運用レイヤー（インベントリ、モニタリング、影響レポート、評価、シャドウ トラフィック、段階的ロールアウト、ロールバック、監査ログ）を追加します。
これにより、モデルの移行が直前の文字列置換から管理された依存関係ワークフローに変わります。目標は、モデルの動作を永久にフリーズさせることではありません。目標は、品質、コスト、レイテンシー、構造化出力の動作、および請求の帰属を維持しながらモデルを意図的に変更することです。