AI Gateway Architecture2026年7月29日Flatkey Team

AI API Gateway アーキテクチャ: 1つのキー、モデルルーティング、フェイルオーバー

1つのキーでのモデルアクセス、明示的なルーティングポリシー、ヘルスチェック、リトライ、契約を壊さないフェイルオーバー、ストリーミング、テレメトリ、移行までを解説する本番向けアーキテクチャガイド。

AI API ゲートウェイは、アプリケーションに 1 つの安定したエンドポイントを提供し、その背後のインフラストラクチャでは複数のモデル、プロバイダー、アカウント、またはリージョンを使用できます。重要なのは、単に複数の API キーを 1 つのキーの背後に隠すことではありません。重要なのは、すべてのリクエストに対して制御された意思決定ポイントを作ることです。

その意思決定ポイントは、トラフィックがモデルプロバイダーに到達する前に、運用上の疑問に答えることができます。

このクライアントは要求されたモデルを呼び出すことが許可されているか？
どの upstream が、現在このリクエストの能力、レイテンシー、コスト要件を満たしているか？
その upstream は、さらにトラフィックを受け取れるほど健全か？
このリクエストは安全に再試行できるか？
どのフェイルバックがレスポンス契約を維持するか？
チームは後から、ルート、コスト、失敗についてどのように説明するか？

このガイドでは、そうした責務を本番アーキテクチャに落とし込みます。また、1 つの API キーがどこで役立ち、どこでは役立たないのか、そして OpenAI 互換クライアントを、ゲートウェイが見えない経路選択の驚きの原因にならないように移行する方法も示します。

The reference architecture in one request path

実用的な AI ゲートウェイのリクエストは、5 つのレイヤーを通過します。

クライアント契約: アプリケーションは、認証済みのリクエストを 1 つの安定したベース URL に送信します。
受け入れ制御: ゲートウェイは、ID、クォータ、モデル権限、ペイロード上限、およびリクエストメタデータを検証します。
ルーティングポリシー: ポリシーエンジンは、要求されたモデルまたは機能を、対象候補となる upstream に変換します。
実行制御: 健全性、同時実行数、タイムアウト、再試行、フェイルバック、およびストリーミングのルールが、選択されたターゲットの呼び出し方法を決定します。
テレメトリと会計: ゲートウェイは、選択されたルート、レスポンスステータス、レイテンシー、トークンまたはメディア使用量、ならびにコスト配賦を記録します。

Application / agent
        |
        |  one API key + stable request schema
        v
AI API gateway
  ├─ authentication and tenant policy
  ├─ model alias and capability registry
  ├─ routing policy and budget rules
  ├─ health, timeout, retry, and fallback controls
  └─ logs, traces, usage, and cost attribution
        |
        ├────────> Provider or deployment A
        ├────────> Provider or deployment B
        └────────> Provider or deployment C

したがって、ゲートウェイは コントロールプレーン であり、同時に データプレーン でもあります。コントロールプレーンは、ポリシー、認証情報、エイリアス、クォータ、ルーティング設定を保存します。データプレーンは、ライブリクエスト、ストリーミングレスポンス、再試行、およびテレメトリを処理します。これらの責務を概念的に分離しておくと変更が安全になります。運用担当者は、すべてのアプリケーションチームに新しいクライアントコードの配布を求めることなく、ルーティングポリシーを更新できます。

What “one key” should mean

「1 つのキー」とは、すべての人、サービス、環境で共有する 1 つの認証情報ではなく、アプリケーション向けの 1 つの認証情報契約を意味すべきです。

適切な設計では、本番、ステージング、ローカル開発、CI、および独立したワークロードごとに、別々のゲートウェイ認証情報を発行します。各キーは、狭いスコープ、所有者、クォータ、そして失効経路を持つべきです。ゲートウェイはプロバイダーの認証情報をサーバー側に保持し、受信した ID を、使用が許可された upstream の認証情報にマッピングします。

これにより、実用的なセキュリティ境界が作られます。

境界	クライアントが見えるもの	ゲートウェイが見えるもの	プロバイダーが見えるもの
アプリケーション認証情報	自分のゲートウェイキー	クライアントの識別情報とポリシー	不要
プロバイダー認証情報	何も	暗号化された上流シークレットまたはマネージドID	プロバイダーアカウントの識別情報
ルーティングポリシー	要求された公開モデルまたはエイリアス	対象候補と選択理由	選択されたリクエストのみ
課金コンテキスト	公開される場合はアプリレベルの使用状況	テナント、プロジェクト、ルート、使用量、価格のマッピング	プロバイダー側の使用状況

ゲートウェイキーは、キー管理の衛生を弱める理由として決して扱うべきではありません。シークレットマネージャーに格納し、ブラウザコードや公開リポジトリには決して置かず、ローテーションし、環境ごとに分離してください。より深い運用チェックリストについては、AI製品向けの安全なAPIキー管理を参照してください。

モデルエイリアスはクライアント契約をプロバイダーから切り離す

最初のルーティング抽象化はモデルエイリアスです。アプリケーション全体でプロバイダー固有のモデル識別子をハードコーディングする代わりに、クライアントは次のような安定した名前を要求します。

support-fast
reasoning-high
code-review-default
image-generation-standard

各エイリアスの背後にあるレジストリは、機能契約を定義します。テキストのエイリアスでは、ツール呼び出し、構造化出力、最小コンテキストサイズ、ストリーミングサポート、承認済みのフォールバックファミリーを指定できます。画像または動画のエイリアスでは、受け入れ可能な入力タイプ、出力サイズ、非同期ジョブの挙動、安全性制約など、異なるフィールドが必要です。

エイリアスは、候補モデルがすべて同一の動作をすることを約束すべきではありません。アプリケーションが依存できる最小限の挙動を定義するべきです。

alias: support-fast
contract:
  modality: text
  streaming: true
  tools: optional
  structured_output: required
  maximum_latency_ms: 3500
routes:
  - target: provider-a/model-fast
    priority: 1
  - target: provider-b/model-balanced
    priority: 2

この間接化こそが、安定したベースURLに価値を持たせるものです。アプリケーションはエイリアス契約に統合し、プラットフォーム運営者は評価の後、プロバイダー障害、価格変更、または地域要件に応じてターゲットセットを変更できます。

ルーティングの決定は明示的であるべき

本番環境のルーティングは通常、厳格なフィルターとソフトな順位付けを組み合わせます。

1. 厳格な適格性フィルターを適用する

リクエストを満たせないターゲットはすべて除外します。一般的なフィルターには次のものがあります。

必須のモダリティと入力タイプ
コンテキストウィンドウまたは出力サイズの要件
ツール呼び出しまたは構造化出力のサポート
データ所在地またはリージョンでの利用可否
テナントまたはプロジェクトの許可リスト
安全性またはコンプライアンスポリシー
現在のクォータ、レート制限、または同時実行状態
ストリーミング互換性

厳格な要件を満たせないターゲットは、たとえ安価であっても勝つべきではありません。

2. 適格なターゲットを順位付けする

フィルタリング後、残ったルートをスコアリングします。シンプルなポリシーは、不透明な最適化器よりも運用しやすいことがあります。

route score =
  quality_weight × evaluation_score
  - latency_weight × predicted_latency
  - cost_weight × estimated_cost
  - risk_weight × recent_error_rate

重みはワークロードごとに異なるべきです。インタラクティブなチャットでは、最初のトークンまでの時間が重視されるかもしれません。夜間の抽出ジョブでは、成功した構造化レコード1件あたりのコストが重視されるかもしれません。コーディングエージェントでは、小さな価格差よりも、ツールの信頼性や長いコンテキストでの挙動のほうが価値が高い場合があります。

3. 理由を記録する

すべてのルーティング निर्णयは、次のような機械可読メタデータを生成する必要があります。

{
  "requested_alias": "support-fast",
  "selected_target": "provider-a/model-fast",
  "policy_version": "support-fast-2026-07-29.3",
  "selection_reason": "healthy_primary_within_latency_budget",
  "fallback_count": 0
}

チームが、なぜそのルートが選択されたのかを再構築できないなら、コストのずれ、品質の劣化、またはプロバイダー障害をデバッグできません。

ヘルスチェックには HTTP 200 以上が必要

上流は、実際のモデルトラフィックには失敗しているのに、ヘルスプローブには成功を返すことがあります。そのため、AI ゲートウェイのヘルスには複数のシグナルが必要です。

トランスポートの健全性: 接続失敗、TLS エラー、DNS エラー、上流タイムアウト
API の健全性: レート制限レスポンス、認証失敗、プロバイダーエラー、形式不正のレスポンス
モデルの健全性: 空の出力、無効な構造化出力、壊れたツール呼び出し、互換性のないストリーミングチャンク
パフォーマンスの健全性: 最初のトークンまでの時間、総レイテンシ、キュー時間、スループット
キャパシティの健全性: 同時リクエスト数、1分あたりのトークン圧力、アカウント残高、またはデプロイメントのクォータ

1 回の失敗ではなく、ローリングウィンドウを使用します。サーキットブレーカーは、失敗閾値またはレイテンシ閾値を超えた後に一時的にターゲットを除外し、その後、完全なトラフィックを復帰させる前に限定的なプローブを許可できます。アウトライア検出は、同じプロバイダーの正常なデプロイメントを利用可能なまま、1 つの異常なデプロイメントだけを除外することもできます。

この原則は、ゲートウェイおよびサービスメッシュのインフラで十分に確立されています。リトライ、サーキットブレーカー、アウトライア検出は別個の制御であり、それぞれに境界付きのポリシーが必要です。Envoy は、これらのメカニズムを HTTP retry、circuit breaking、および outlier detection のガイダンスで個別に説明しています。

リクエストが安全な場合にのみリトライする

リトライは、作業を増幅したり重複する副作用を生んだりしない場合にのみ、信頼性を向上させます。

応答バイトがまだ届く前に失敗した非ストリーミングのテキスト補完では、同じターゲットに対する 1 回のリトライは妥当かもしれません。ツールを起動する、画像や動画のジョブを開始する、外部アカウントに課金する、またはすでに部分的な出力をストリーミングしているリクエストでは、無条件のリトライは重複を生んだり、ユーザー体験を損なったりする可能性があります。

次の 3 つの प्रश्नを使ってリトライの可否を定義します。

リクエストは上流で受け付けられましたか? 受け付け前の接続失敗は、プロバイダーが処理を開始した後のタイムアウトとは異なります。
クライアントに何らかの出力は届いていますか? ストリーミングが始まると、プロバイダーを切り替えることで応答が不連続になる可能性があります。
冪等キーまたは重複排除レコードはありますか? 長時間実行されるメディアやエージェントのワークフローには、安定した操作IDが必要です。

保守的なリトライマトリクスは次のようになります:

障害	同一ターゲットへのリトライ	クロスターゲットのフォールバック	注記
応答前の接続失敗	通常は安全、回数制限あり	通常は安全	ジッターとデッドライン予算を適用する
プロバイダーのレート制限	場合による	多くの場合	リトライヒントと容量状態を尊重する
出力前のプロバイダー5xx	回数制限あり	多くの場合	不健全なターゲットを一時的に除外する
無効な構造化出力	修復ポリシーがある場合のみ	契約互換のターゲットに限る	品質SLOに対してカウントする
部分的なストリーミング応答	通常は不可	通常は不可	明確なストリームエラーを返すか、明示的なプロトコルがある場合のみ再開する
非同期メディアジョブが受理された	盲目的なリトライなし	盲目的なフォールバックなし	操作IDでポーリングする; 送信は重複排除する

1つのエンドツーエンドのデッドラインを維持してください。クライアントが8秒を許容する場合、ゲートウェイはプライマリに7秒使った後で、フォールバックにさらに8秒を与えることはできません。各試行は同じリクエスト予算を消費します。

フォールバックは契約を維持しなければならない

フォールバックは単に「別のモデルを試す」ことではありません。プライマリ経路が失敗したときに何が変更され得るかについての合意です。

フォールバックは3つのレベルで定義します:

同じモデル、異なるデプロイまたはアカウント: 振る舞い上のリスクが最も低く、クォータやリージョン障害に有効です。
同等のモデルファミリー: 中程度のリスク; スキーマ、ツール、安全性、出力スタイルについて回帰テストが必要です。
機能を劣化させた能力: リスクが最も高い; ツールを無効化し、コンテキストを削減し、ライブ応答の代わりにキュー済み応答を返すことがあります。

各エイリアスについて、次を文書化します:

どの障害クラスがフォールバックをトリガーするか
どのターゲットが契約互換であるか
フォールバックが発生したことをクライアントに通知するか
最大試行回数と総デッドライン
品質とコストの変化をどのように測定するか
応答をキャッシュまたは再生できるか

リージョン別のプロバイダーアクセスは、別の次元を追加します。プロバイダーやモデルは、ある地理的地域、アカウント種別、または商取引条件では利用可能でも、別の条件では利用できない場合があります。Regional LLM provider routingでは、これらのルートに必要な個別のアクセス、ポリシー、フォールオーバーのチェックを説明しています。

ストリーミングはゲートウェイ契約の一部である

OpenAI互換のリクエスト形状はクライアント移行を簡素化できますが、ストリーミング互換性には意図的な変換が必要です。ゲートウェイは、イベント順序、終了理由、使用状況メタデータ、ツール呼び出しフラグメント、エラー通知、接続キャンセルを保持しなければなりません。

1つのストリーミングエイリアスの背後で2つのモデルをルーティングする前に、次をテストしてください:

最初のイベントまでの時間とハートビートの動作
増分テキストの差分形式
ツール呼び出し引数の組み立て
最終イベントでの使用量レポート
クライアントのキャンセル伝播
最初のイベントの前後におけるタイムアウト動作
ヘッダー送信後のエラー形式

プロトコルが明示的に再開をサポートしていない限り、1つのレスポンスの中にストリームの再開を隠してはいけません。ほとんどのクライアントでは、1つのモデルの部分的な回答と別のモデルの回答を混在させるよりも、明確なエラーを返す方がましです。

オブザーバビリティはルーティングと成果をつなぐ

ゲートウェイのダッシュボードは有用ですが、本番環境の診断には、モデルリクエストを周辺のアプリケーショントレースに結び付けられる構造化テレメトリが必要です。

少なくとも、以下を記録してください:

Dimension	Example fields
Identity	tenant, project, environment, key ID, workload
Request	request ID, operation ID, alias, modality, input size
Routing	policy version, eligible targets, selected target, fallback count
Reliability	status class, provider error code, retries, timeout stage
Performance	queue time, time to first token, total latency, output throughput
Usage	input, output, cache, image, audio, or video units
Economics	estimated cost, billed cost, budget rule, price version
Quality	evaluation label, schema validity, tool success, user outcome

デフォルトでは生のプロンプトや出力をログに記録しないようにしてください。コンテンツの記録は、ユースケース、保持ポリシー、ユーザーの期待がそれを許可する場合にのみ行ってください。OpenTelemetry プロジェクトは、進化中の生成AIシステム向けのセマンティック規約を維持しており、各プロバイダーごとに別々のスキーマを作るのではなく、チームが一貫した span と metric 名を使うのに役立ちます。

コスト制御は上流呼び出しの前に置く

事後の支出レポートではインシデントを防げません。アドミッションとルーティングのポリシーは、トラフィックを送る前にコストを評価すべきです。

有用な制御には次のものがあります:

キーごとおよびプロジェクトごとのハードクォータ
ソフトな予算アラート
入力または出力ユニットの上限
環境別のモデル許可リスト
柔軟なワークロード向けのコスト認識ルーティング
再現可能なリクエスト向けのキャッシュポリシー
高コストなメディアジョブ向けの同時実行制限
モデル、プロバイダー、テナント、またはルートのキルスイッチ

ルーティングエンジンには、バージョン管理された価格表と一貫した使用量正規化レイヤーが必要です。そうでないと、「最安モデル」ポリシーが互換性のない単位や古い価格を比較してしまう可能性があります。プロバイダー料金、プラットフォーム費用、運用制御を分離するフレームワークについては、AI gateway pricing を参照してください。

最小限の OpenAI 互換移行

最小限のクライアント変更は通常、新しい API キー、ベース URL、モデル名だけです。OpenAI 互換のゲートウェイを使えば、アプリケーションコードは同じクライアントライブラリを維持できます:

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url="https://router.flatkey.ai/v1",
)

response = client.chat.completions.create(
    model="your-model-or-alias",
    messages=[
        {"role": "user", "content": "このインシデントレポートを要約してください。"}
    ],
)

そのコード変更は簡単な部分です。安全な移行には4つの段階があります。

現在の契約を棚卸しする。 モデル、パラメータ、ストリーミング動作、ツール、スキーマ、タイムアウト、エラー処理を記録します。
シャドー評価またはオフライン評価を実行する。 代表的なリクエストで、出力品質、スキーマの妥当性、レイテンシ、コストを比較します。
1つのワークロードをカナリアリリースする。 制限されたトラフィック割合から始め、即時ロールバックできる経路を用意します。
ルーティング機能を別々に有効化する。 まずエンドポイントを変更し、次にエイリアスを追加し、その後にヘルスベースのフェイルオーバー、最後にコストまたは品質の最適化を行います。

これらの変更を分けることで、障害の原因を診断しやすくなります。エンドポイント移行、モデル置換、リトライポリシー、コスト最適化がすべて同時に開始されると、どの変数が回帰を引き起こしたのかチームは分かりません。Flatkey integration starterでは、base URL移行パターンについてさらに詳しく説明しています。

本番対応チェックリスト

ゲートウェイを共有インフラとして扱う前に、このチェックリストを使用してください。

クライアント契約

安定したbase URLとバージョン管理されたリクエストスキーマ
最低限の対応機能が文書化された名前付きエイリアス
一貫したエラーエンベロープとリクエストID
ストリーミング、ツール呼び出し、構造化出力のテスト済み対応

アイデンティティとセキュリティ

サービス別・環境別のキー分離
サーバー側のプロバイダ認証情報
キーのスコープ、クォータ、ローテーション、失効
プロンプトとレスポンスのログ記録は無効化するか、明示的に管理する

ルーティングと信頼性

コストランキングの前に厳格な適格性フィルタを適用
バージョン管理されたルーティングポリシーと価格データ
実際のリクエスト動作に基づくヘルス判定
1つのエンドツーエンドの期限を持つ制限付きリトライ
契約互換のフォールバック先
サーキットブレーカーとリカバリープローブ

運用

ルート理由、プロバイダエラー、レイテンシ、使用状況のテレメトリ
フォールバック率、エラー率、コストの乖離、クォータ逼迫に対するアラート
モデル別・ルート別のキルスイッチ
プロバイダ障害とゲートウェイ障害のためのランブック
重要なワークロード向けの直接経路または代替の緊急経路

Flatkeyがこのアーキテクチャにどう適合するか

Flatkeyは、対応モデルへのアクセス、使用状況、請求のための1つのAPIキー、1つのOpenAI互換base URL、1つのダッシュボードを提供します。ルーターは、上流の切り替えと負荷分散をサポートしながら、個別のプロバイダアカウントと断片化した統合経路を減らすよう設計されています。

アプリケーションチームにとってのアーキテクチャ上の利点は、安定したクライアント境界です。OpenAI互換のクライアントを https://router.flatkey.ai/v1 に向け、対応しているモデルを選択し、モデルアクセスは同じゲートウェイエンドポイントの背後に維持します。チームはそれでも、自分たちのアプリケーションレベルの契約、評価しきい値、キーのスコープ、障害予算、フェイルバックの期待値を定義する必要があります。

最適なゲートウェイアーキテクチャは、ルーティングを見えなくするものではありません。ルーティングを変更可能で、境界が明確で、説明可能なものにします。