AIゲートウェイでのチャネル管理

「チャネル（Channel）」はAIゲートウェイにおけるプロバイダー接続ポイントの設定です。あるプロバイダーのアドレス、実際のAPIキー、利用可能なモデル、および料金とクォータなどの情報を保持します。ゲートウェイはこれらのチャネルに基づいて、アプリから送信されたリクエストを対応するプロバイダーにルーティングします。本記事では、チャネルの追加、設定、テスト、管理方法について説明します。

前提条件

• ServBayがインストールされ実行中で、ServBayアカウントにログイン済みであること（チャネル追加前にログインが必要です）。
• 対象プロバイダーの実際のAPIキーを準備済みであること（Ollama / LM Studioなどローカルプロバイダーは入力不要）。
• AIゲートウェイ全体のアーキテクチャを理解していない場合は、先にAIゲートウェイの紹介を読むことをおすすめします。

チャネルの追加

**AIゲートウェイ → チャネル（Channels）**ページに移動し、**追加（Add）**をクリックしてウィザードを開きます。ウィザードは3つのステップに分かれています。

ステップ1：プロバイダーの選択

プロバイダーはカテゴリ別にグループ表示され、カードをクリックして選択できます：

• メインストリーム（Mainstream）：OpenAI、Anthropic、Google Gemini、Azure OpenAI、AWS Bedrock、OpenRouter。
• 中国（China）：DeepSeek、通义千问、智谱 GLM、Kimi、豆包·火山、文心一言、混元、MiniMax、零一万物、阶跃星辰。
• ローカル（Local）：Ollama、LM Studio。
• カスタム（Custom）：OpenAI Compatible、Custom。

プロバイダーを選択すると、ゲートウェイはそのプロバイダーのデフォルトBase URLを自動入力します。

デュアルリージョン切り替え

通义千问、智谱 GLM、Kimi、豆包·火山、混元、MiniMax、阶跃星辰などの中国系プロバイダーは、中国国内とグローバルの2つのエンドポイントを提供しています。この種のプロバイダーを選択すると、ウィザードに「リージョン」セレクター（🇨🇳 国内 / 🌐 グローバル）が表示され、切り替えるとBase URLが対応するリージョンのアドレスに自動更新されます。

ステップ2：設定の入力

• チャネル名（必須） — リスト内でチャネルを識別するための名前で、自由に設定できます。
• Base URL（必須） — プロバイダーのAPIアドレス。ほとんどのプロバイダーは自動入力されます。Azure OpenAIとCustomは手動で入力する必要があります。
• API Key（任意） — プロバイダーの実際のキー。空欄にした場合、エンドポイントに到達可能かどうかのテストのみ可能で、キーの有効性は検証できません。ローカルプロバイダー（Ollama / LM Studio）は通常入力不要です。
• モデル — 2つの方法があり、いずれかを選択します：
  • 自動検出：検出をクリックすると、ゲートウェイがプロバイダーのモデルリストAPIを呼び出して利用可能なモデルを取得し、チップ（chip）形式で複数選択できます。
  • 手動入力：モデル名を直接入力します。Azureチャネルにはモデル名ではなく**デプロイ名（Deployment name）**を入力する必要があります。
• 優先度 / 重み — 複数のチャネルが同じモデルを処理できる場合、ゲートウェイはこれに基づいてルーティングと負荷分散を決定します。

Azure OpenAIの注意点

Azureチャネルの「モデル」フィールドには、Azureポータルで作成した**デプロイ名（Deployment name）**を入力してください。基盤となるモデル名ではありません。Base URLもAzureリソースのエンドポイントを入力する必要があります。

ステップ3：確認と送信

設定の概要を確認して送信します。送信が成功すると、新しいチャネルがチャネルリストに表示され、リアルタイムのヘルス状態が表示されます。

ケイパビリティ検出とルーティング戦略

チャネルを追加すると、ゲートウェイはそのチャネルに対して**ケイパビリティ検出（capability probing）**を実行します。これはAIゲートウェイの最も核心的なインテリジェントルーティングメカニズムです。検出結果によって、Claude Codeなどのツールがそのまま使用できるか、モデルマッピングを作成する必要があるか、そしてターゲットモデルをどのように選択するかが決まります。

検出の2つの重要な指標

ゲートウェイは各チャネルについて2つの核心的な事実を検出します（いずれも三状態：true / false / 未検出）：

検出項目	意味	true	false	未検出
Claudeモデル名を認識（accepts_claude_names）	チャネルがclaude-opus-* / claude-sonnet-* / claude-haiku-*といったモデル名をネイティブに認識するか	直接接続可能で、マッピング不要	認識しないため、claude-*名を上流の実際のモデル名に変換するマッピングの作成が必須	検出が実行されていないか失敗しており、結論を下せない
ティア別に区別（tier_aware）	上流が自らopus / sonnet / haikuのティア別に異なるモデルを返すか	上流が既にティア分けしているので、上流に任せればよい	ティア分けしない（すべてのティアに同じモデルを返す）ため、ゲートウェイがマッピングを作成する必要がある	検出できないか、検出していない

なぜ推測ではなく検出するのか

プロバイダーによって動作が大きく異なります。OpenAIはclaude-*モデル名をネイティブには認識しません。一部の中継プロバイダーは転送を通じて認識します。また、コーディングプラン系プロバイダー（Claude Pro/Maxサブスクリプションなど）はサブスクリプションに紐づく特定のモデル名のみを認識する場合があります。ゲートウェイはチャネルタイプによる推測ではなく、実際に検出した上でルーティング戦略を決定します。

ルーティング判定：5つの状態

AI Gateway → 接続管理 → クライアントページでClaude Codeに対して「ワンクリック引き継ぎ」を行うと、ゲートウェイはすべての候補チャネルの検出結果を集約し、ルーティング判定を導き出します：

候補チャネルの状態	判定	意味
利用可能な候補チャネルがない（チャネルなし / すべて異常 / 仮想キーのスコープ内にチャネルなし）	候補チャネルなし	先にチャネルを追加または修復する必要があります
いずれかの候補チャネルの検出値が未検出	未検出	先に一度検出を実行する必要があり、未検証の前提でマッピングを作成することはできません
すべての候補チャネルがclaudeモデル名を認識	直接接続	マッピングを作成せず、リクエストをそのまま転送
すべての候補チャネルがclaudeモデル名を認識しない	マッピング必須	ゲートウェイが3ティアのマッピングを作成し、claude-*を上流の実際のモデル名に変換
候補の中に認識するものと認識しないものが混在	混合	手動での判断が必要（認識するものは直接、認識しないものはマッピング経由）

モデルマッピング：claude-*を上流の実際のモデルに変換

「マッピング必須」と判定された場合、ゲートウェイはClaude Code用に3つのモデルマッピングルールを作成し、それぞれ3つのティアをカバーします：

Claude Codeが送信するモデル名	マッピングルール（ワイルドカード）	マッピング先
claude-opus-*	すべてのopusティアのリクエストにマッチ	候補チャネル内のフラッグシップモデル
claude-sonnet-*	すべてのsonnetティアのリクエストにマッチ	候補チャネル内のフラッグシップモデルまたは標準モデル
claude-haiku-*	すべてのhaikuティアのリクエストにマッチ	候補チャネル内の軽量モデル

ターゲットモデルの選択ルール（優先度順にフォールバック）：

1. ファミリープリセット：候補モデルに既知のファミリーキーワード（例：glm）が現れた場合、そのファミリーのフラッグシップモデル（例：glm-5.2）をopus/sonnetティアのターゲットとし、そのファミリーの軽量モデル（例：glm-4.7-flash）をhaikuティアのターゲットとします。
2. キーワードマッチング：ファミリープリセットがない場合、opus/sonnetは候補リストの最初のモデルを取り、haikuは候補の中から軽量キーワード（flash / mini / lite / air / small / turbo / haiku）にマッチする最初のモデルを取ります。
3. フォールバック：それでもヒットしない場合、3ティアすべてで候補リストの最初のモデルを取ります。

haikuティアの設定ミスは最も高くつく

Claude Codeのhaikuティアは呼び出し量が最も多いです（各会話の軽量呼び出しで使用されます）。誤ってフラッグシップモデルをhaikuティアに入れると、請求額が数倍になる可能性があります。ゲートウェイのキーワードマッチングテーブルは7種類の軽量サフィックス（flash / mini / lite / air / small / turbo / haiku）をカバーしており、重いモデルがhaikuティアに入らないようにしています。

マッピング書き込みの仕組み

引き継ぎ確認後、ゲートウェイは/admin/model-mappings APIを通じてマッピングレコードを書き込みます。各マッピングレコードには以下が含まれます：

• ソースプロトコル（source_protocol）：anthropic（Claude Codeが送信するリクエストはAnthropic形式）
• ソースモデルマッチ（source_model_pattern）：ワイルドカード、例：claude-opus-*
• ターゲットプロトコル（target_protocol）：openai（統一的にOpenAI形式に変換して上流に送信）
• ターゲットモデル（target_model）：検出によって選ばれた具体的なモデル名

書き込みは**冪等（べきとう）**です——重複して引き継いでも重複したマッピングは生成されません。書き込み前に既存のマッピングリストを取得して比較します。

実行時ルーティングルール：フェイルオーバーと降格

引き継ぎ段階で書き込まれる静的マッピングに加えて、ゲートウェイは**実行時ルーティングルール（routing rules）**もサポートしており、リクエストがゲートウェイを通過する際に動的に判断します：

ルールフィールド	役割
トリガー条件（condition_type）	いつ降格をトリガーするか、例：チャネルのクォータ枯渇（quota_exhausted）
コスト閾値（cost_threshold_usd）	任意：そのチャネルの累計コストが閾値を超えたときにトリガー
アクション（action_type）	トリガー後に何をするか、例：指定の代替チャネルに切り替え（switch_to）
ターゲットチャネル（target_channel_id）	降格先の代替チャネル
ターゲットモデル（target_model）	任意：代替チャネルに降格する際に同時にモデルを切り替え

複数のルーティングルールを組み合わせることで、チャネルAのサブスクリプションクォータが枯渇したときにチャネルBの従量課金エンドポイントに自動切り替えたり、あるチャネルの24時間コストが上限を超えたときにより安価なモデルに降格したりすることが実現できます。

負荷分散と優先度

複数の正常なチャネルが同じモデルを処理できる場合、ゲートウェイは以下の戦略で選択します：

• 優先度モード（デフォルト）：優先度が最も高いチャネルのみを選択し、同じ優先度のチャネル間ではゲートウェイが内部の重みに従って分散します。
• ラウンドロビンモード（round_robin）：すべての正常な候補チャネル間でリクエストを順番に分散します。

優先度はチャネル設定で設定します（数値が大きいほど優先度が高い）。仮想キーのallowed_channelsは選択可能なチャネルの範囲を限定します。

接続テスト

チャネルリストで個々のチャネルに対して接続テストを実行できます。テストは2つの次元に分かれます：

• エンドポイント到達性（reachable） — Base URLに接続できるか（ネットワークとアドレスが正しいか）を確認します。
• キー有効性（authenticated） — 実際にプロバイダーのインターフェースを呼び出し、API Keyが有効か検証します。API Keyを入力した場合のみ検証されます。

テスト結果には、往復遅延（ミリ秒）、ステータスバッジ、エラーメッセージが表示されます。

TIP

追加ウィザードでは、エンドポイントに到達できない場合は次のステップに進むことができません。エンドポイントに到達できるがキーが無効な場合は警告のみが表示され、続行できます（例：後でキーを補充する予定の場合）。

高度な設定

チャネルの追加または編集時に高度な設定を展開でき、コスト計算とクォータ管理に使用します：

• 料金倍率（Rate Multiplier） — プロバイダーの公式価格に倍率を掛けます。実際のコストや再販価格で計算するのに便利で、デフォルトは1.0です。
• 課金構造 — そのチャネルの課金方式を説明します。例：従量課金（pay as you go）、サブスクリプション（subscription）、パッケージ（package）。
• 残高 — 残高のソースは固定値、OSS請求書、または手動メンテナンスから選択できます。OSS請求書を選択した場合は請求書タイプも指定できます。残高と更新時刻はチャネル詳細で読み取り専用で表示されます。
• サブスクリプション有効期限 — サブスクリプション / パッケージ系チャネルは有効期限を記録できます。
• クォータ制限 — トークン数、リクエスト数、または金額で上限を設定でき、周期（毎日 / 毎週 / 毎月 / カスタム）を選択できます。クォータを使い切ると、そのチャネルは自動的にルーティングから除外されます。予期せぬ超過支出を防ぐ安全弁です。

チャネルの編集と削除

• 編集 — チャネルリストでチャネルを開くと、名前、Base URL、API Key、モデル、高度な設定を変更できます。
• 削除 — チャネルを削除すると、そのチャネルに依存する仮想キーはルーティングできなくなります。慎重に操作してください。

ヘルス状態

チャネルリストと概要ページでは、各チャネルのヘルス状態（正常 / 降格 / 利用不可）がリアルタイムで表示され、無効になったプロバイダー設定をすばやく発見できます。

よくある質問（FAQ）

• Q：チャネル追加時にログインが必要と表示される？
  • A：AIゲートウェイはServBayの付加価値機能です。チャネル / キーを追加する前にServBayアカウントにログインする必要があります。画面の案内に従ってログインしてください。
• Q：チャネル数が上限に達したと表示される？
  • A：作成できるチャネル数はアカウントプランに関連します。上限に達した場合は、使用していないチャネルを削除するか、プランをアップグレードしてください。
• Q：モデル自動検出でリストが取得できない？
  • A：まずBase URLが正しいか、API Keyが有効か（接続テストの「キー有効性」で検証可能）を確認してください。一部のプロバイダーは有効なキーがないとモデルリストを返しません。手動でモデル名を入力する方法もあります。
• Q：ローカルのOllama / LM Studioに接続するのにKeyは必要？
  • A：通常は不要です。対応するローカルサービスが起動し、デフォルトポート（Ollamaは11434、LM Studioは1234）をリッスンしていることを確認してください。

まとめ

チャネルはAIゲートウェイがリクエストをルーティングする基盤です。3ステップのウィザードで約20社のプロバイダーにすばやく接続でき、デュアルリージョン切り替え、モデル自動検出、2次元の接続テストを組み合わせて設定が正しいことを確認し、さらに料金設定やクォータなどの高度な設定でコストをきめ細かく管理できます。チャネルを設定したら、アプリやツールが使用する仮想キーを作成できます。