OpenAI 互換 API ゲートウェイへの移行: ベース URL を反転する前に互換性コントラクトを構築する

base_url、api_key、model を変更するだけで、単純なチャット デモが OpenAI 互換の API に対して機能するようになります。本番移行が安全であることを証明するだけでは十分ではありません。

障害は通常、後になって現れます。ストリーム化されたツール呼び出しが異なる形式で到着する、JSON スキーマ モードが無視される、埋め込みモデルが異なるベクトル サイズを返す、使用法フィールドが欠落している、副作用を再試行して二重送信する、またはプロバイダー固有の推論オプションが何も行われないなどです。実際的な目標は、抽象的にエンドポイントが「OpenAI と互換性がある」かどうかを尋ねることではありません。目標は、アプリケーションが依存する OpenAI 型のコントラクトのどの部分を定義し、それらの部分をテストし、コントラクトが明示的になった場合にのみゲートウェイを経由するルーティングを行うことです。

このガイドでは、信頼性、使用状況の帰属、ロールバック オプションを維持しながら、プロバイダー固有の SDK または散在する互換性のあるエンドポイントから OpenAI 互換性のある 1 つのゲートウェイにチームを移行する方法を説明します。

この移行における事実、推奨事項、予測は何ですか?

事実: いくつかのプロバイダは、API の一部について OpenAI 互換のパスまたは SDK の使用法を文書化しています。 Google は、API キー、ベース URL、モデルを変更することで、OpenAI Python および TypeScript ライブラリと REST を介した Gemini アクセスを文書化します。また、まだ OpenAI ライブラリを使用していないアプリケーションには Gemini API を直接使用することも推奨します。 Gemini の互換性ドキュメントでは、チャットの完了、ストリーミング、関数呼び出し、イメージの理解、埋め込み、推論労力のマッピング、追加のリクエスト本文によるプロバイダー固有のオプションについて説明しています。 AI は、複数のモダリティに対する OpenAI REST と SDK の互換性をまとめて文書化しますが、そのマトリックスには、アシスタント、スレッド、ランなど、サポートされていない OpenAI 形状のサーフェスもリストされています。 Mistral は、ベース URL とモデル名を変更することで、OpenAI 互換クライアントの移行パスを文書化します。 Groq は OpenAI パスのチャット完了エンドポイントを公開します。 vLLM は、パラメータの違いを文書化しながら、補完とチャット用の OpenAI 互換サーバーを提供します。 OpenAI エージェント SDK のドキュメントでは、OpenAI 以外のプロバイダの多くが新しい応答 API をまだサポートしておらず、多くの場合、チャット完了モードがより安全な互換性のターゲットであると警告しています。

推奨事項: 互換性をテスト済みのアプリケーション契約として扱います。アプリが使用する正確なエンドポイントと機能のインベントリを作成し、プロバイダーとモデル機能マトリックスを作成し、トラフィック移行前に適合性テストを作成し、ゲートウェイ境界での既知のリクエストとレスポンスの違いを正規化し、アプリケーションごとのキーとロールバック プロファイルをロールアウトします。

予測: OpenAI 互換のサーフェスは、摩擦の最も低い統合レイヤーとして今後も有用ですが、プロバイダー ネイティブの機能は分岐し続けるでしょう。互換性契約を維持しているチームは、非公式の「ドロップイン交換」の前提に依存しているチームよりも早く新しいモデルを採用できます。

ステップ 1: 現在の AI 呼び出しごとにインベントリを作成する

コードの変更ではなく、インベントリから始めます。チームがすべての AI 呼び出しがチャットの完了のように見えると想定し、リリース後にのみ隠れた依存関係を発見すると、移行は失敗します。

呼び出しサイトごとに 1 行を作成します。スケジュールされたジョブ、内部ツール、ノートブック、バックグラウンド ワーカー、評価ハーネス、顧客対応サービスが含まれます。

app: support-assistant
owner: customer-platform
current_provider: provider_a
current_sdk: provider_a_python_sdk
endpoint_shape: chat.completions
model: provider-a-large-2026
features:
  - streaming
  - tool_calls
  - json_schema_output
  - usage_accounting
latency_budget_ms: 8000
retry_policy: retry_429_5xx_no_tool_side_effects
monthly_volume_estimate: 2.4M requests
rollback_contact: oncall-customer-platform

モデルごとだけでなく、エンドポイントと機能ごとに各呼び出しを分類します。単一のモデル名は、その使用方法に応じて、非常に異なる互換性要件を隠すことができます。

在庫チェックリスト

• チャット: メッセージ、システム命令、温度、トップ-P、最大トークン、停止シーケンス。
• ストリーミング: サーバー送信イベント パーサー、最終チャンク、ストリーム内での使用状況、キャンセル動作。
• ツール: 関数スキーマ、並列呼び出し、引数 JSON、ツール結果メッセージ、副作用安全性。
• 構造化出力: JSON モード、JSON スキーマ、厳密な検証、フォールバック修復ロジック。
• ビジョンまたはマルチモーダル入力: 画像 URL、base64、MIME 処理、詳細パラメーター。
• エンベディング: モデル ID、ベクトル次元、正規化の期待値、インデックスの互換性。
• ファイルとバッチ: API、ジョブのポーリング、キャンセル、出力形式をアップロードします。
• 推論制御: 推論作業、思考予算、非表示トークン、プロバイダー固有の設定。
• エラー: レート制限形状、タイムアウト形状、コンテンツ ポリシー エラー、再試行可能なステータス コード。
• 使用量と請求: プロンプト トークン、完了トークン、キャッシュされたトークン、推論トークン、コスト割り当てタグ。

このステップの出力は依存関係マップです。シンプルな OpenAI 互換 API プロファイルを使用して移行できるアプリと、アダプターの作業が必要なアプリを示します。

ステップ 2: 互換性契約テーブルを作成する

互換性契約は、アプリケーションの機能ごとに、ゲートウェイが何を保証しなければならないか、そしてそれをどのようにテストするかを記載した表です。エンジニアリング チームと製品チームが展開の決定を下すのに十分な具体性を持たせる必要があります。

この表は、過度の約束も防ぎます。プロバイダーがチャットと埋め込みをサポートしているが、ファイルやアシスタントのようなワークフローはサポートしていない場合は、契約にその旨を記載する必要があります。 「未サポート」は、本番環境での予期せぬ問題を回避する場合、有効な移行結果です。

ステップ 3: モデル ID を分散させる代わりにモデル プロファイルを作成する

すべてのアプリで、1 つのハードコードされたモデル ID を別のハードコードされたモデル ID に置き換えないでください。モデル プロファイルを使用します。

profile: support-chat-fast
openai_model_alias: support-chat-fast
provider: provider_b
provider_model: provider-b/chat-large-fast
endpoint: chat.completions
features:
  streaming: true
  tools: true
  structured_outputs: schema_validated
  vision: false
  embeddings: false
request_policy:
  drop_unsupported_params: false
  reject_unknown_params: true
  pass_through_extra_body: ["reasoning_effort"]
fallback_profile: support-chat-safe
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 つあると、使用状況の特定と緊急ロールバックが困難になります。

安全なロールアウト シーケンスは次のようになります:

1. 開発プロファイル: ローカル トラフィックとステージング トラフィックのみをゲートウェイ経由でルーティングします。リクエストの形状とパーサーの問題を修正しました。
2. シャドウ テスト: ユーザーに表示される出力に影響を与えることなく、新しいプロファイルに対する代表的なリクエストを再生します。スキーマの有効性、ツールの動作、レイテンシ クラス、および使用フィールドを比較します。
3. 小規模な運用スライス: 低い割合のトラフィックまたは 1 つの内部テナントを移動します。エラー、再試行、ユーザー向けの品質シグナル、コストを監視します。
4. アプリごとの拡張: 一度に 1 つのアプリを移行します。同じリスク プロファイルを共有しない限り、チャット、埋め込み、バッチ、ファイルを一緒に移行しないでください。
5. ロールバック プロファイル: 既知の適切なプロバイダー/モデル プロファイルを、アプリ側の同じエイリアスまたは高速構成切り替えの背後で使用できるようにしておきます。
6. 移行後のロック: 安定したら、トラフィックがゲートウェイ制御をバイパスできないように、アプリケーション環境から直接プロバイダー キーを削除します。

ロールバックは他のパスと同様にテストする必要があります。ゲートウェイでモデル プロファイルを切り替えることができる場合は、休止期間中にその切り替えをテストし、アプリケーション ログ、使用状況分析、および請求の帰属が一貫性を保っていることを確認します。

例: 分散したエンドポイントを 1 つのゲートウェイ コントラクトに置き換える

チームに 3 つのアプリがあると仮定します。

• ストリーミング チャットとツールを使用するカスタマー サポート アシスタント。
• 厳密な JSON 出力を必要とするコンテンツ分類子。
• ベクトル データベースに保存された埋め込みを使用する検索サービス。

危険な移行では、3 つのアプリすべてが同じベース URL に変更され、3 つの新しいモデル ID が選択されます。より安全な移行により、契約が分離されます:

• サポート チャット プロファイル: ストリーミング、ツール呼び出し、バッファリングされたツール呼び出しデルタ、再試行分類、使用状況ログが必要です。
• classifier-json プロファイル: スキーマの検証、拒否処理が必要で、サイレント パラメーターの削除は必要ありません。
• search-embedding profile: 固定ベクトル次元と、次元が変更された場合のインデックス移行計画が必要です。

各プロファイルは独自の適合性テストとロールアウトを受けます。サポート アシスタントにはストリーミング アダプターの作業が必要な場合があります。スキーマ検証がモデルの外部にある場合、分類子はすぐに合格する可能性があります。埋め込みサービスでは、インプレース モデル スワップではなく、新しいインデックスが必要になる場合があります。ゲートウェイはチームに OpenAI 互換のベース URL を 1 つ提供しますが、互換性契約により移行が誠実に行われます。

移行チェックリスト

• バックグラウンド ジョブや内部スクリプトを含む、すべての AI 呼び出しサイトをリストします。
• エンドポイント、機能、モデル、所有者、ロールバック パスごとに呼び出しを分類します。
• プロバイダー モデル ID をハードコーディングする代わりに、アプリ側モデル プロファイルを定義します。
• 各プロバイダーとモデル プロファイルの機能マトリックスを作成します。
• プロファイルがパススルーを明示的に許可しない限り、サポートされていないパラメータは拒否します。
• ストリーミング、ツール、構造化出力、埋め込み、エラー、再試行、および使用フィールドをテストします。
• 帰属と制御には、アプリごとおよび環境ごとに API キーを使用します。
• ユーザーに表示される運用トラフィックの前にシャドウ テストを実行します。
• 一度に 1 つのアプリケーションまたは機能クラスをロールアウトします。
• コードを再デプロイせずに、テスト済みのロールバック プロファイルを利用可能な状態に保ちます。

実用的な結論

OpenAI 互換の API ゲートウェイは、単なる別の URL ではなく、制御された移行レイヤーになるときに最も価値があります。ベース URL スイッチにより、機械的なコードの変更が軽減されます。互換性契約により、運用リスクが軽減されます。

実稼働トラフィックを切り替える前に、アプリケーションが実際に必要とするもの、つまりストリーミング動作、ツール セマンティクス、スキーマ保証、埋め込みディメンション、再試行ルール、使用フィールド、エラーの意味を書き留めてください。これらの要件をモデル プロファイル、アダプター ルール、適合性テストに変換します。次に、アプリごとのキー、分析、ロールバック プロファイルをロールアウトします。

単純なチャット パスが機能する場合は、良いスタートとして扱います。移行の残りの部分は、データベース、キュー、または決済プロバイダーの変更と同じ規律に値するエンジニアリング作業として扱ってください。

関連資料

• 複数のモデル プロバイダーにわたる構造化出力の検証
• モデルの置換とロールバックのランブック
• 使用状況分析とトークンゲートウェイでの調整