Skip to main content

APIM モデル負荷分散ポリシー

概要​

本ドキュメントでは、Azure API Management (APIM) 向けに開発されたOpenAI互換モデルの負荷分散ポリシーについて説明します。本ポリシーは最新バージョンのTerraformデプロイスクリプトに統合されており、複数のOpenAI互換バックエンドサービス間でリクエストをインテリジェントに分散し、高可用性、自動フェイルオーバー、インテリジェントなレートリミット処理機能を提供します。

アーキテクチャ設計​

全体アーキテクチャ図​

コア機能特性​

1. 複数プロトコル対応​

  • Azure OpenAI: api-key ヘッダー認証を使用
  • OpenAI互換サービス: Authorization: Bearer 認証を使用
  • パス形式自動適応:
    • Azure OpenAI: /openai/deployments/{model}/chat/completions
    • 汎用形式: /openai/{provider}/{model}/chat/completions

2. インテリジェント負荷分散アルゴリズム​

Providerグループ化メカニズム​

負荷分散ポリシーはまずリクエスト内のProviderでグループ化を行います：

  • 同一Providerのバックエンドサービスのみが同じ負荷分散グループに参加
  • 異なるProvider間では負荷分散しない、それぞれ独立して動作
  • 各Providerグループ内で独立して優先度・重みアルゴリズムを実行

多層負荷分散ポリシー​

コアアルゴリズム特性：

  • 優先度スケジューリング: 高優先度バックエンドを優先利用、障害時は自動で低優先度に切替
  • 重み付き負荷分散: 同一優先度内で重みに応じてトラフィックを分配
  • インテリジェント障害検知: レートリミットやエラー状態を自動検知
  • 動的復旧: バックエンド復旧時は自動で負荷分散に再組み込み

3. インテリジェント障害処理​

障害検知と自動復旧​

コア耐障害メカニズム​

  • 多重障害検知: HTTPステータスコード、タイムアウト、接続エラー等に対応
  • インテリジェントリトライ戦略: 最大5回リトライ、利用不可バックエンドは自動スキップ
  • 状態自動復旧: 時間ウィンドウベースの自動復旧メカニズム
  • リアルタイム状態同期: バックエンド状態変化をキャッシュに即時反映

ワークフロー詳細​

リクエスト処理フロー​

コア処理フェーズ​

  1. リクエスト解析: URLからProviderとModel情報を抽出、複数APIパス形式に対応
  2. バックエンドフィルタ: Provider+Model組み合わせでマッチするバックエンドをフィルタ、キャッシュ機構でパフォーマンス向上
  3. 負荷分散: 優先度順にソートし、同一優先度内で重みに応じてトラフィック分配
  4. リクエスト転送: バックエンド種別に応じて認証方式を設定し、リクエストパス形式を調整

構成管理​

構成方法​

1. APIM Named Valueによる構成​

  • 構成項目名: ModelEndpoints
  • 構成タイプ: JSON形式の文字列
  • 更新方法: 即時反映、サービス再起動不要

操作手順：

  1. Azure Portalにログイン → API Managementインスタンス
  2. 「Named values」メニューを選択
  3. ModelEndpoints構成項目を探す
  4. JSON構成内容を編集し保存

2. Terraformによる構成​

自動化デプロイやバージョン管理シナリオに適用。

バックエンド構成構造​

{
  "provider": "provider-type",
  "priority": 1,
  "weight": 50,
  "endpoint": "https://api-endpoint.example.com/path/{model}",
  "api_key": "********",
  "models": ["model-a", "model-b", "model-c"]
}

構成パラメータ説明​

パラメータ型説明
providerstringプロバイダー種別識別子
prioritynumber優先度（数字が小さいほど高優先度）
weightnumber重み値（同一優先度内の分配比率）
endpointstringバックエンドエンドポイントURL（{model}プレースホルダーは実際のモデル名に置換）
api_keystringAPI認証キー
modelsarray当該バックエンドが対応するモデルリスト

構成例​

APIM Named Value構成例​

[
  {
    "provider": "azure-openai",
    "priority": 1,
    "weight": 50,
    "endpoint": "https://xxxxxxx.openai.azure.com/openai/deployments/{model}",
    "api_key": "********",
    "models": ["gpt-4.1", "gpt-4.1-mini"]
  },
  {
    "provider": "azure-openai",
    "priority": 2, 
    "weight": 30,
    "endpoint": "https://yyyyyyy.openai.azure.com/openai/deployments/{model}",
    "api_key": "********",
    "models": ["gpt-4.1", "gpt-4.1-mini"]
  },
  {
    "provider": "openai-compatible",
    "priority": 1,
    "weight": 100,
    "endpoint": "https://api.example.com/v1/",
    "api_key": "********",
    "models": ["custom-model"]
  }
]

構成説明:

  • 最初の2つの構成はazure-openaiプロバイダーで、同じ負荷分散グループに属します
  • 3つ目の構成はopenai-compatibleプロバイダーで、独立したグループとなります
  • 異なるProviderグループ間で負荷分散は行われません

キャッシュポリシー​

キャッシュメカニズム​

  • キャッシュ時間: 30秒（パフォーマンスと構成更新の即時性を両立）
  • キャッシュ範囲: Provider+Model組み合わせごとにキャッシュ
  • 失効条件: 構成変更時に自動失効
  • 更新戦略: ラジー（遅延）ロード方式、必要時にキャッシュ生成

構成更新フロー​

  1. 構成変更検知 → キャッシュ失効 → 動的再構築 → ゼロダウンタイム更新

エラー処理とリトライ​

リトライメカニズム​

  • 自動リトライ条件：HTTP 429、HTTP 5xx
  • 最大リトライ回数：5回
  • リトライ間隔：1秒

エラータイプ処理​

エラーコード処理ポリシー説明
429レートリミットマーク＋他バックエンドへリトライRetry-Afterヘッダーに従い復旧時間を設定
5xx他バックエンドへリトライサーバ内部エラー、他バックエンドを試行
503利用可能なバックエンドなしエラー返却全バックエンド利用不可時に返却

デバッグ機能​

デバッグヘッダー​

デバッグモード有効時、レスポンスに以下のヘッダーが追加されます：

X-Debug-Provider: provider-a
X-Debug-Model: model-x
X-Debug-Path: /api/model-x/chat/completions -> /chat/completions
X-Debug-Backend: 0
X-Debug-Endpoint: https://api-a.example.com/path/model-x

デバッグモード有効化​

variable "enable_debug_headers" {
  description = "Enable debug headers for load balancer policy"
  type        = bool
  default     = true
}

ベストプラクティス​

1. 優先度設計の推奨​

優先度1: メインサービスプロバイダー（低レイテンシ・高信頼性）
優先度2: バックアップサービスプロバイダー（異なるリージョンまたはプロバイダー）
優先度3: コスト最適化サービス（価格優位または特殊モデル）

2. 重み分配戦略​

  • 同等性能バックエンド: 均等な重みを設定
  • 異なる性能バックエンド: 性能差に応じて重み比率を調整
  • コスト考慮: コストが低いバックエンドに高い重みを割り当て

3. Providerグループ化戦略​

  • 同種サービスグループ化: 同一タイプのAPIサービスを同じProviderにまとめる
  • リージョングループ化: リージョンごとに異なるProviderグループを設定
  • コストグループ化: コスト特性でProviderを分類
  • 機能グループ化: モデル機能特性でグループ化

4. 監視と運用​

  • デバッグヘッダー有効化: 開発・テスト環境で有効化
  • ログ監視: 503エラーやリトライ回数を監視
  • パフォーマンス監視: キャッシュヒット率や応答時間を注視
  • 構成監視: Named Value構成の変更と反映状況を監視

トラブルシューティング​

よくある問題​

1. 503 Service Unavailable​

原因: リクエストされたprovider+model組み合わせに対応する利用可能なバックエンドが存在しない 解決策:

  • 構成に該当バックエンドがあるか確認
  • モデル名が正しいか検証
  • バックエンドが全てレートリミット状態になっていないか確認

2. 認証失敗​

原因: APIキーの設定ミスまたは期限切れ 解決策:

  • バックエンドサービスのAPIキーが正しいか検証
  • 認証方式がバックエンド要件と一致しているか確認

3. パス解析エラー​

原因: リクエストパス形式が想定と異なる 解決策:

  • 正しいパス形式を使用しているか確認
  • providerおよびmodelパラメータが正しく渡されているか確認

デバッグ手順​

  1. デバッグヘッダー有効化: EnableDebugHeaders Named Valueをtrueに設定
  2. デバッグ情報確認: レスポンスのX-Debug-*ヘッダー情報を確認
  3. 構成ロード検証: ModelEndpoints Named Value構成が正しいか確認
  4. キャッシュ状態確認: キャッシュ生成・失効状況を監視
  5. バックエンド状態監視: バックエンド応答状態やリトライ動作を観察