集約グループ
マルチキープール統合とインテリジェント負荷分散ソリューション
概要
集約グループとは？
集約グループ（Aggregate Group）は、GPT-Loadが提供する高度なグループタイプで、複数の標準グループを1つの論理グループに組み合わせることができます。集約グループを通じて、複数のキープールを統一管理し、インテリジェント負荷分散と高可用性を実現できます。
複数キープールの統一管理
異なるキープールを1つのアクセスポイントに統合
インテリジェント負荷分散
重みに基づいて各サブグループにリクエストトラフィックを自動分散
可用性の向上
あるサブグループに利用可能なキーがない場合、他のサブグループに自動切り替え
柔軟なトラフィック制御
各サブグループのトラフィック割合を動的に調整
使用シーン
マルチキープール負荷分散
複数の標準グループのキープールを集約し、均等なトラフィック分散を実現
リソース分離と集約
部門ごとのキープールを独立管理しつつ、集約グループを通じて統一サービスを提供
弾性スケーリング
クライアント設定を変更せずに既存の集約グループに新しいキープールを迅速に追加
カナリアデプロイメント
重み調整により新しいキープールのトラフィック割合を制御し、段階的な切り替えを実現
高可用性アーキテクチャ
プライマリキープールが枯渇した場合、バックアップキープールに自動切り替え
コアコンセプト
集約グループ
特別なグループタイプで、キー自体は含まず、他の標準グループを参照し、インテリジェントアルゴリズムを通じて複数のキープールの統一管理と負荷分散を実装します。
サブグループ
集約グループによって参照される標準グループで、実際にAPIキーを保存・管理します。各サブグループは独立して設定・メンテナンス可能です。
重み
負荷分散におけるサブグループのトラフィック割合を決定し、0〜1000の範囲です。重みが高いほど多くのトラフィックが割り当てられ、重み0は一時的な無効化を意味します。
状態
サブグループの運用状態には、有効（重み > 0かつ利用可能なキーあり）、無効（重み = 0）、無効（重み > 0だが利用可能なキーなし）の3種類があります。
状態管理
| 重み | 利用可能キー | 状態 | 説明 |
|---|---|---|---|
| > 0 | あり | 有効 | 通常通り負荷分散に参加 |
| = 0 | - | 無効 | 負荷分散に参加しない（一時的に無効化） |
| > 0 | なし | 無効 | 選択時に自動的にスキップされる |
設計原理
負荷分散アルゴリズム
GPT-Loadはサブグループ選択にスムーズ重み付けラウンドロビン（Smooth Weighted Round-Robin）アルゴリズムを使用し、以下の特徴があります：
スムーズな分散：より均等なトラフィック分散、バーストトラフィックを回避
正確な重み付け：設定された重み比率に厳密に従ってトラフィックを分散
高性能：O(n)時間複雑度、高同時実行シナリオに適している
サブグループ選択ロジック
候補グループの計算
重み付けラウンドロビンアルゴリズムに基づいて次の候補サブグループを計算
可用性チェック
このサブグループに利用可能なキーがあるかチェック
選択またはスキップ
キーがあれば使用、なければ試行済みとマークして次の候補へ
失敗処理
すべてのサブグループに利用可能なキーがない場合、エラーを返す
主要機能
- •スマートスキップ：利用可能なキーがないサブグループを自動的にスキップ
- •高速フェイル：すべてのサブグループを確認後、すぐにエラーを返す
- •ステートレス：各リクエストは独立して決定、外部状態に依存しない
使用規則
サブグループ制限
ネスト不可
チャネルタイプの一貫性
検証エンドポイントの一貫性
重み設定規則
値の範囲
0-1000
特殊値0
サブグループを無効化（負荷分散に参加しない）
パーセンテージ計算
サブグループ割合 = サブグループ重み / すべてのサブグループ重みの合計 × 100%
推奨プラクティス
理解とメンテナンスが容易な100単位の値（例：100、200、500）を使用
ベストプラクティス
均等分散
容量が近い複数のキープール、均等なトラフィック分散を目指す
サブグループA: 100 サブグループB: 100 サブグループC: 100
利点
- ✓シンプルで直感的、バランスの取れたトラフィック
- ✓同等に重要な複数のキープールに適している
容量比例分散
容量差が大きいキープール、容量比率で分散
サブグループA（50キー）: 500 # 50% サブグループB（30キー）: 300 # 30% サブグループC（20キー）: 200 # 20%
利点
- ✓バランスの取れたキー利用率
- ✓小さなプールの過負荷を回避
プライマリ-バックアップモード
プライマリキープールを優先使用、バックアップキープールを保険として
サブグループA（プライマリ）: 900 # 90% サブグループB（バックアップ）: 100 # 10%
利点
- ✓プライマリプールを優先的に消費
- ✓バックアッププールがバッファとして機能
カナリアデプロイメント
新しいキープールの安定性をテスト、段階的にトラフィックを切り替え
ステージ1: 旧(980) / 新(20) ステージ2: 旧(800) / 新(200) ステージ3: 旧(200) / 新(800)
利点
- ✓制御可能なリスク
- ✓問題の影響範囲が限定的
モデルリダイレクトとの連携
集約グループが同じチャネルタイプだが異なるサービスプロバイダーに接続するサブグループを含む場合、各サブグループでモデルリダイレクトを設定し、クライアントから統一されたモデル名でアクセス可能にします。
ユースケース
集約グループに3つのOpenAI形式のサブグループが含まれ、異なるプロバイダーに接続し、クライアントが統一されたgpt-4モデル名を使用：
サブグループA (OpenAI公式): {"gpt-4": "gpt-4-turbo"}サブグループB (Azure OpenAI): {"gpt-4": "gpt-35-turbo"}サブグループC (OpenRouter): {"gpt-4": "openai/gpt-4-turbo"}クライアントはgpt-4を使用するだけで、集約グループが重みに基づいてトラフィックを分散し、各サブグループが実際にサポートされているモデルに自動的にマッピングします。
トラブルシューティング
リクエストが「No available sub-groups」を返す
原因
すべてのサブグループに利用可能なキーがない、すべてのサブグループが無効化されている（重み = 0）、または集約グループにサブグループが追加されていない
解決方法
- 1サブグループリストを確認し、状態を確認
- 2「無効」状態のサブグループに入り、キーを検証・補充
- 3無効化されたサブグループの重みを復元
- 4少なくとも1つのサブグループが「有効」状態であることを確認
トラフィック分散が重み設定と一致しない
原因
一部のサブグループに利用可能なキーがなく自動的にスキップされている、重み設定が最近変更されより長い観察時間が必要、またはリクエスト量が少なすぎて統計的に代表性がない
解決方法
- 1すべてのサブグループに利用可能なキーがあるか確認
- 2ログページでより長い期間（例：1時間）のトラフィック分散を分析
- 3重み設定が保存され有効であることを確認
標準グループのチャネルタイプを変更できない
原因
標準グループが1つ以上の集約グループによってサブグループとして参照されている
解決方法
- 1標準グループ詳細ページで「参照している集約グループ」リストを確認
- 2リスト内の各集約グループからサブグループを削除
- 3チャネルタイプを変更
- 4必要に応じて集約グループに再追加