OpenAI 互換 API ゲートウェイへの移行: ベース URL を反転する前に互換性コントラクトを構築する
実稼働アプリをプロバイダー SDK または点在する OpenAI 互換エンドポイントから 1 つのゲートウェイに移行するための実践的な移行ガイド: インベントリー呼び出し、機能マトリックスの定義、適合テストの作成、癖の正規化、安全なロールバックによるロールアウト。
base_url、api_key、および model を変更するだけで、OpenAI 互換 API に対して単純なチャット デモを動作させることができる場合がよくあります。本番環境への移行が安全であることを証明するだけでは十分ではありません。
障害は通常、後から発生します。ストリーミングされたツール呼び出しが異なる形式で到着する、JSON スキーマ モードが無視される、埋め込みモデルが異なるベクトル サイズを返す、使用法フィールドが欠落している、副作用を再試行して二重送信する、またはプロバイダー固有の推論オプションが何も行われないなどです。実際的な目標は、エンドポイントが抽象的に「OpenAI 互換」かどうかを尋ねることではありません。目標は、アプリケーションが OpenAI 形式のコントラクトのどの部分に依存するかを定義し、それらの部分をテストし、コントラクトが明示的になった後でのみゲートウェイを経由するようにルーティングすることです。
このガイドでは、信頼性、使用状況の帰属、ロールバック オプションを維持しながら、プロバイダー固有の SDK または散在する互換性のあるエンドポイントから 1 つの OpenAI 互換ゲートウェイにチームを移行する方法を説明します。
この移行における事実、推奨事項、予測とは何ですか?
事実: いくつかのプロバイダは、API の一部について OpenAI 互換パスまたは SDK の使用法を文書化しています。 Google は、API キー、ベース URL、モデルを変更することで、OpenAI Python および TypeScript ライブラリと REST を介して Gemini にアクセスすることを文書化していますが、OpenAI ライブラリをまだ使用していないアプリケーションに対しては、Gemini API を直接使用することも推奨しています。 Gemini の互換性ドキュメントでは、チャットの完了、ストリーミング、関数呼び出し、イメージの理解、埋め込み、推論労力のマッピング、追加のリクエスト本文によるプロバイダー固有のオプションについて説明しています。 Together AI は、複数のモダリティに対する OpenAI REST と SDK の互換性を文書化していますが、そのマトリックスには、アシスタント、スレッド、ランなど、サポートされていない OpenAI 形状のサーフェスもリストされています。 Mistral では、ベース URL とモデル名を変更することで、OpenAI 互換クライアントの移行パスを文書化しています。 Groq は、OpenAI パスのチャット完了エンドポイントを公開します。 vLLM は、パラメーターの違いを文書化しながら、補完とチャット用の OpenAI 互換サーバーを提供します。 OpenAI Agents SDK のドキュメントでは、多くの非 OpenAI プロバイダーがまだ新しい Responses API をサポートしておらず、多くの場合、Chat Completions モードがより安全な互換性ターゲットであると警告しています。
推奨事項: 互換性をテスト済みのアプリケーション契約として扱います。アプリが使用する正確なエンドポイントと機能のインベントリを作成し、プロバイダーとモデルの機能マトリックスを作成し、トラフィック移行前に適合性テストを作成し、ゲートウェイ境界での既知のリクエストとレスポンスの違いを正規化し、アプリケーションごとのキーとロールバック プロファイルをロールアウトします。
予測: OpenAI 互換のサーフェスは、摩擦の最も少ない統合レイヤーとして今後も有用ですが、プロバイダー ネイティブの機能は分岐し続けるでしょう。互換性契約を維持しているチームは、非公式な「ドロップイン交換」の前提に依存しているチームよりも早く新しいモデルを採用できます。
ステップ 1: 現在の AI 呼び出しごとにインベントリを作成する
コード変更ではなく、インベントリから始めます。チームがすべての AI 呼び出しがチャット完了のように見えると想定し、リリース後にのみ隠れた依存関係を発見すると、移行は失敗します。
呼び出しサイトごとに 1 行を作成します。スケジュールされたジョブ、内部ツール、ノートブック、バックグラウンド ワーカー、評価ハーネス、顧客対応サービスが含まれます。
app: サポートアシスタント
所有者: 顧客プラットフォーム
現在のプロバイダー: プロバイダー_a
current_sdk: プロバイダー_a_python_sdk
endpoint_shape: chat.completions
モデル: プロバイダー-a-large-2026
特徴:
- ストリーミング
- ツールコール
- json_schema_output
- 使用状況_会計
latency_budget_ms: 8000
retry_policy: retry_429_5xx_no_tool_side_Effects
month_volume_estimate: 240 万リクエスト
rollback_contact: オンコール顧客プラットフォームモデルごとだけでなく、エンドポイントと機能ごとに各通話を分類します。単一のモデル名は、その使用方法に応じて、非常に異なる互換性要件を隠すことができます。
在庫チェックリスト
- チャット: メッセージ、システム指示、温度、トップポイント、最大トークン、停止シーケンス。
- ストリーミング: サーバー送信イベント パーサー、最終チャンク、ストリーム内での使用状況、キャンセル動作。
- ツール: 関数スキーマ、並列呼び出し、引数 JSON、ツール結果メッセージ、副作用安全性。
- 構造化出力: JSON モード、JSON スキーマ、厳密な検証、フォールバック修復ロジック。
- ビジョンまたはマルチモーダル入力: 画像 URL、base64、MIME 処理、詳細パラメータ。
- エンベディング: モデル ID、ベクトル次元、正規化の期待値、インデックスの互換性。
- ファイルとバッチ: API、ジョブのポーリング、キャンセル、出力形式をアップロードします。
- 推論コントロール: 推論の労力、思考の予算、非表示のトークン、プロバイダー固有の設定。
- エラー: レート制限の形状、タイムアウトの形状、コンテンツ ポリシー エラー、再試行可能なステータス コード。
- 使用量と請求: プロンプト トークン、完了トークン、キャッシュされたトークン、推論トークン、コスト割り当てタグ。
このステップの出力は依存関係マップです。これにより、どのアプリがシンプルな OpenAI 互換 API プロファイルを使用して移行できるか、どのアプリがアダプターの作業を必要とするかがわかります。
ステップ 2: 互換性契約テーブルを作成する
互換性契約は、アプリケーションの機能ごとに、ゲートウェイが何を保証する必要があるか、およびそれをどのようにテストするかを示す表です。エンジニアリング チームと製品チームが展開の決定を下すのに十分な具体性を持たせる必要があります。
<テーブル> <頭>この表は、過度の約束も防ぎます。プロバイダーがチャットと埋め込みをサポートしているが、ファイルやアシスタントのようなワークフローはサポートしていない場合は、契約にその旨を記載する必要があります。 「未サポート」は、本番環境での予期せぬ事態を回避する場合、有効な移行結果です。
ステップ 3: モデル ID を分散させる代わりにモデル プロファイルを作成する
すべてのアプリで、あるハードコードされたモデル ID を別のハードコードされたモデル ID に置き換えないでください。モデル プロファイルを使用します。
プロファイル: support-chat-fast
openai_model_alias: サポートチャットファースト
プロバイダー: プロバイダー_b
プロバイダーモデル: プロバイダー-b/チャット-ラージ-ファースト
エンドポイント: chat.completions
特徴:
ストリーミング: true
ツール: true
構造化出力: スキーマ検証済み
ビジョン: 偽
埋め込み: false
リクエストポリシー:
ドロップ_unsupported_params: false
拒否_不明_パラメータ: true
pass_through_extra_body: ["reasoning_effort"]
fallback_profile: チャットセーフをサポート
cost_center_required: trueこのプロファイルはアプリケーションに安定した名前を与えますが、ゲートウェイはプロバイダー マッピングを所有します。また、フラット モデル名前空間ではなく名前空間モデル ID を使用するプロバイダーも処理します。アプリは support-chat-fast を要求します。ゲートウェイは、現在それが Together スタイルの名前空間モデル、Gemini 互換モデル、Mistral 互換モデル、Groq チャット モデル、セルフホスト vLLM エンドポイント、または別の承認されたターゲットにマッピングされているかどうかを決定します。
トレードオフはガバナンスのオーバーヘッドです。プロファイルは文書化し、レビューし、バージョン管理する必要があります。利点は、移行、ロールバック、モデルの置換ですべてのアプリケーションを再デプロイする必要がないことです。
ステップ 4: 移行前に適合テストを作成する
適合テストは、各ターゲット プロファイルに対して契約を検証する小規模な反復可能なチェックです。これらは、最初のロールアウトの前、およびプロバイダー、モデル、SDK、またはゲートウェイ アダプターが変更されるたびに実行する必要があります。
最小のテスト スイート
- ゴールデン プロンプト テスト: 決定論的なプロンプトを送信し、応答の形状、終了理由、安全動作、および基本的なセマンティック要件を検証します。アプリケーションが実際に依存している場合を除き、正確な表現を必要としません。
- ストリーミング パーサー テスト: クライアントがすべてのチャンクを解析し、最終テキストを再構築し、キャンセルを処理し、ストリームの完了を検出できることを確認します。
- ツール呼び出しのラウンド トリップ: ツール呼び出しを強制し、引数を解析し、偽のツールを実行し、ツールの結果を返し、モデルが正しく続行することを確認します。
- ツール呼び出しストリーミング テスト: ツールの実行前に部分的な引数デルタをバッファリングして再構築できることを確認します。そうでない場合は、そのプロファイルの増分ツールの実行を無効にします。
- JSON スキーマの検証: 有効な出力、無効な出力、欠落フィールド、余分なフィールド、拒否またはエラーのケースをテストします。
- 埋め込み次元チェック: 既存のインデックスを再利用する前に、ベクトルの長さ、数値型、ターゲット ベクトル インデックスとの互換性を確認します。
- 再試行および冪等性テスト: 429、500、タイムアウト、および部分的なストリームの障害をシミュレートします。ツールの副作用が誤って繰り返されないように注意してください。
- 使用状況の調整: ゲートウェイの使用状況記録を、プロバイダーから報告された使用状況フィールドおよび請求元帳の予想と比較します。
テストは運用トラフィック パターンに近づけてください。単一の「詩を書いてください」というプロンプトは、ツール、JSON、埋め込み、使用状況のアカウンティングに依存するワークフローについてはほとんど何も証明しません。
ステップ 5: ゲートウェイ境界での動作異常を正規化する
OpenAI 互換のゲートウェイはアプリケーション コードの変更を減らす必要がありますが、すべてのプロバイダーが同じように動作するように見せるべきではありません。既知の違いにはアダプターを使用し、動作を可視化します。
リクエストの正規化
- モデル エイリアス: 安定したアプリ向けプロファイル名をプロバイダー固有のモデル ID にマッピングします。
- サポートされていないパラメータ: デフォルトでは、サポートされていないパラメータを明確なエラーで拒否します。サイレントドロップはデモ中は便利ですが、本番環境では危険です。
- プロバイダ固有のオプション: 文書化されたモデル プロファイルでのみ、推論や思考の制御などの制御されたパススルー フィールドを許可します。
- メッセージ変換: ターゲット プロバイダーが異なる形式を想定しているシステム、開発者、ユーザー、アシスタント、ツールのメッセージを正規化します。
- タイムアウト バジェット: SDK のデフォルトを累積させるのではなく、アプリケーション レベルの期限を 1 つ適用します。
応答の正規化
- テキストとツールの選択: アシスタント テキスト、ツール呼び出し、終了理由の一貫した形状を返します。
- ストリーミング チャンク: 共通デルタを正規化し、バッファリングが必要な場所を文書化します。
- 使用状況フィールド: プロバイダー ネイティブの使用状況と、正規化されたプロンプト、完了、および合計トークン数（利用可能な場合）を保存します。
- エラーの形状: ステータス コード、再試行可能性、プロバイダー エラー コード、リクエスト ID を 1 つのエラー スキーマにマッピングします。
- コスト メタデータ: 後で分析できるように、アプリ、チーム、プロファイル、プロバイダー、モデル、環境のラベルを添付します。
主なトレードオフは、移植性とプロバイダーの能力です。最小の共通曲面に正規化すると、互換性が向上します。プロバイダー固有のフィールドを許可すると、高度な機能が維持されますが、すべてのパススルー オプションはプロファイルのドキュメントとテスト マトリックスの一部になります。
ステップ 6: アプリごとのキーとロールバック プロファイルを使用してロールアウトする
移行は、コードを再デプロイしなくても元に戻せる必要があります。アプリケーション、環境、チームごとに個別の API キーを使用します。単一の共有キーにより、使用量の特定と緊急ロールバックが困難になります。
安全なロールアウト シーケンスは次のようになります。
<オル>ロールバックは、他のパスと同様にテストする必要があります。ゲートウェイでモデル プロファイルを切り替えることができる場合は、休止期間中にその切り替えをテストし、アプリケーション ログ、使用状況分析、および請求の帰属が一貫性を保っていることを確認します。
例: 分散したエンドポイントを 1 つのゲートウェイ コントラクトに置き換える
チームに 3 つのアプリがあると仮定します。
- ストリーミング チャットとツールを使用するカスタマー サポート アシスタント
- 厳密な JSON 出力を必要とするコンテンツ分類子。
- ベクター データベースに保存されたエンベディングを使用した検索サービス。
危険な移行では、3 つのアプリすべてが同じベース URL に変更され、3 つの新しいモデル ID が選択されます。より安全な移行により、契約が分離されます。
- サポート チャット プロファイル: ストリーミング、ツール呼び出し、バッファリングされたツール呼び出しデルタ、再試行分類、使用状況ログが必要です。
- classifier-json プロファイル: スキーマ検証、拒否処理が必要であり、サイレント パラメーターの削除は必要ありません。
- 検索埋め込みプロファイル: 固定ベクトル次元と、次元が変更された場合のインデックス移行計画が必要です。
各プロファイルは独自の適合性テストとロールアウトを受けます。サポート アシスタントにはストリーミング アダプターの作業が必要な場合があります。スキーマ検証がモデルの外部にある場合、分類子はすぐに合格する可能性があります。埋め込みサービスでは、インプレース モデル スワップではなく、新しいインデックスが必要になる場合があります。ゲートウェイはチームに 1 つの OpenAI 互換ベース URL を提供しますが、互換性契約により移行が誠実に行われます。
移行チェックリスト
- バックグラウンド ジョブや内部スクリプトを含む、すべての AI 呼び出しサイトをリストする
- エンドポイント、機能、モデル、所有者、ロールバック パスごとに通話を分類する
- プロバイダー モデル ID をハードコーディングする代わりに、アプリ側のモデル プロファイルを定義します。
- プロバイダーとモデル プロファイルごとに機能マトリックスを作成する
- プロファイルで明示的にパススルーが許可されていない限り、サポートされていないパラメータは拒否します。
- ストリーミング、ツール、構造化出力、埋め込み、エラー、再試行、使用フィールドをテストする
- 帰属と制御のためにアプリごとおよび環境ごとの API キーを使用する
- ユーザーが目に見える本番トラフィックの前にシャドウ テストを実行します。
- 一度に 1 つのアプリケーションまたは機能クラスをロールアウトします。
- コードを再デプロイせずに、テスト済みのロールバック プロファイルを利用可能な状態に保ちます。
実行可能な結論
OpenAI 互換の API ゲートウェイは、単なる別の URL ではなく、制御された移行レイヤーになるときに最も価値があります。ベース URL スイッチにより、機械的なコードの変更が軽減されます。互換性契約により、運用リスクが軽減されます。
実稼働トラフィックを切り替える前に、ストリーミング動作、ツール セマンティクス、スキーマ保証、埋め込みディメンション、再試行ルール、使用フィールド、エラーの意味など、アプリケーションが実際に必要とするものを書き留めてください。これらの要件をモデル プロファイル、アダプター ルール、適合性テストに変換します。次に、アプリごとのキー、分析、ロールバック プロファイルをロールアウトします。
単純なチャット パスが機能する場合は、それを良いスタートとして扱います。移行の残りの部分は、データベース、キュー、または決済プロバイダーの変更と同じ規律に値するエンジニアリング作業として扱います。