Switchyard AI Gatewayとは？完全ガイド（2026）

Claude CodeやCodexからモデルを切り替えるたびに、API形式、認証情報、ツール呼び出しの設定まで直していますか。

2026年8月14日時点の最短解は、SwitchyardをLLMトラフィックの変換・ルーティング・統計用ゲートウェイとして試し、Python proxyと独立したRust serverを用途別に選ぶことです。

最終更新：2026年8月14日。NVIDIA-NeMo公式リポジトリ、公式インストール文書、アーキテクチャ文書、Rust server構成を確認しています。

このガイドを読むべき人と、読まなくてよい人

Claude CodeやCodexを複数のモデルバックエンドへ接続したい開発者に向いています。社内の統一AI Gatewayを構築するプラットフォームチームや、PythonサービスとRustサービスの配置を比較するエンジニアにも役立ちます。

単一のモデルへ直接接続するだけなら、Switchyardを追加する必要はありません。認証、形式変換、ルーティング、統計を一か所へ集約したい場合に検討してください。

Switchyard AI Gatewayは何を解決するのか

Claude系クライアントはAnthropic Messages形式を使う場合があり、別のクライアントや推論サーバーはOpenAI Chat Completions、OpenAI Responses、またはOpenAI互換形式を受け付けます。クライアントとバックエンドの形式が一致しないと、単純なURL変更だけでは接続できません。

Switchyardはクライアントとモデルバックエンドの間に入り、受信、正規化、ルーティング、実行、応答変換を担当します。公式文書では、OpenAI Chat、Anthropic Messages、OpenAI Responsesの形式変換と、複数のルーティング方式が示されています。(nvidia-nemo.github.io)

課題	直接接続で起きやすいこと	Switchyardで確認できること
API形式の違い	エンドポイントとJSON構造を個別調整する	クライアント形式と上流形式を変換する
複数モデルの切り替え	CLI設定や環境変数を毎回変更する	ルート名をモデルIDとして選択する
障害時の切り替え	各アプリに再試行処理を実装する	設定したフォールバックを適用する
利用状況の把握	各プロバイダーの管理画面を確認する	リクエスト、遅延、トークン、コストを記録する

ただし、形式変換があるからといって、すべての機能が完全互換になるわけではありません。ストリーミング、推論出力、画像、ツール呼び出し、MCP連携は、クライアントと選択したバックエンドの組み合わせごとに検証が必要です。

Rust製なのか、Python製なのか

結論として、Switchyard全体を「完全なRust製」と説明するのは正確ではありません。公式READMEは主要なSwitchyardをLLMトラフィック用のPython proxyとして説明しており、PythonのCLI、ライブラリ、サーバー実行経路が用意されています。一方で、リポジトリには独立したswitchyard-serverを含むRustコンポーネントがあります。(github.com)

構成	主な役割	向いている用途
Python proxy / CLI	設定、Agent Launcher、Pythonライブラリ、HTTPプロキシ	Claude CodeやCodexの検証、素早い導入
Python server	ルーティングプロファイルを読み込む常駐プロキシ	OpenAI互換クライアントをまとめて接続
Rust server	LLMクライアント、ターゲット、アルゴリズムをTOMLで定義する独立サーバー	Rustベースのサービス境界や将来の共通契約を検討する場合

RustのコードやCargoファイルが存在することだけを根拠に、CLIからすべての変換処理までRustで動作すると判断してはいけません。現在の導入判断では、まずPythonの標準経路を確認し、Rust serverは別の構成として評価するのが安全です。

公式ドキュメントでも、Rust側は専用のTOMLスキーマを使う別サーバーとして説明されています。(github.com)

対応プロトコルは広いが、互換性は段階的に確認する

Switchyardが扱う主な入口と上流形式は次のとおりです。ここで重要なのは、「対応している形式」と「接続先がその機能を実装していること」は別条件だという点です。

クライアント側の形式	上流形式	判定
OpenAI Chat Completions	`/v1/chat/completions`	OpenAI互換サーバーで使いやすい
Anthropic Messages	`/v1/messages`	Anthropic形式の上流に接続可能
OpenAI Responses	`/v1/responses`	Responses API対応上流が必要
OpenAI互換API	接続先の互換エンドポイント	バックエンドの実装範囲に依存

公式アーキテクチャ文書では、OPENAI、ANTHROPIC、RESPONSES、AUTOというバックエンド形式が説明されています。AUTOは起動時に能力を確認しますが、上流への確認リクエストが発生します。管理された環境では、対応形式を明示したほうが契約が分かりやすく、起動時の余分な確認も避けられます。(nvidia-nemo.github.io)

特にClaude Codeでツールを使う場合は、モデルの返答だけでなく、ツール名、引数形式、ストリーミング、コンテキスト上限まで確認してください。公式READMEには、Bedrock経由のClaude CodeとMCPでツール名の長さ制限に起因するエラーが発生する注意点も記載されています。(github.com)

固定ルートと自動ルートをどう使い分けるか

Switchyardには、単一モデルへの透過、ランダムルーティング、LLM分類器によるルーティング、ステージルーター、独自ルーターがあります。自動ルーティングは便利ですが、品質向上やコスト削減を必ず保証する機能ではありません。

方式	判断材料	最初の用途
単一モデル透過	固定したモデル名	接続確認、障害切り分け
ランダムルーティング	重みや確率	A/B比較、基準値の取得
LLM分類器	リクエスト内容	強力なモデルと軽量モデルの振り分け
ステージルーター	ツール結果、進行状況、エラー	コーディング作業の段階別制御
セッション親和性	会話単位の固定	複数ターンの一貫性確保

ステージルーターは、探索やエラー復旧のターンを高能力モデルへ、機械的な編集を効率的なモデルへ送る考え方です。ただし、判定のしきい値やエージェントの作業パターンによって結果は変わります。導入前に自分のリポジトリでログを取り、品質、遅延、トークン使用量を比較してください。(nvidia-nemo.github.io)

「自動ルートにすれば安くなる」とは判断しないでください。分類器そのものの呼び出し、再試行、フォールバック、長い会話のコンテキスト処理が追加されるためです。

Claude Codeへ接続する最短手順

Python CLIのAgent Launcherを使う場合、公式の基本経路はローカルプロキシを起動し、そのプロキシ経由でClaude CodeやCodexを開始する方法です。導入時は次の順序で確認すると、問題の場所を切り分けやすくなります。(nvidia-nemo.github.io)

Python 3.12以上とuvまたはpipを用意します。
nemo-switchyardをCLI付きでインストールします。
接続先のAPIキーとベースURLを環境変数または設定へ登録します。
最初は単一モデル透過でClaude Codeを起動します。
/v1/modelsまたはテスト用リクエストで、プロキシが応答することを確認します。
通常のテキスト生成、ストリーミング、ツール呼び出しを別々に試します。
問題がなければYAMLルーティングプロファイルへ移行します。
常駐運用では認証情報、ヘルスチェック、ログ保存、再起動方式を決めます。

bash

pip install "nemo-switchyard[cli,server]"

export PROVIDER_API_KEY="your-key"
export PROVIDER_BASE_URL="https://example.invalid/v1"

switchyard launch claude \
  --model "your-model" \
  --api-key "$PROVIDER_API_KEY" \
  --base-url "$PROVIDER_BASE_URL"

APIキーが正しくても、モデルがツール呼び出しや必要な出力形式を処理できるとは限りません。Agent Launcherは接続作業を簡略化しますが、モデル互換性の検証までは代行しません。

独立した代理サービスとして運用できるか

できます。Pythonのserve経路では、ルーティングプロファイルを読み込んだ長期稼働プロキシとして起動できます。公式の例では、ルート名がモデルIDとして公開され、クライアントはmodelフィールドでそのルートを選択します。(nvidia-nemo.github.io)

試験環境では、同一ホスト上でプロセスを起動し、/healthと簡単なチャットリクエストを確認すれば十分です。運用環境では、APIキーを環境変数や秘密管理機構へ分離し、設定ファイルをリポジトリへそのまま保存しないでください。

また、セッション親和性を使う場合は、複数ターンが同じモデル階層へ送られることを確認します。単発の成功だけでは、長いAgent実行時の挙動を判断できません。

注意：公式ドキュメントは実験的な機能や既知の制限も案内しています。リリース番号、CLIオプション、Rust serverの設定形式は、導入時に必ず対象コミットの文書で再確認してください。

本番投入前に確認する運用項目

Switchyardを常駐AI Gatewayとして使う場合、転送できることだけでは合格にしないでください。次のチェックを一つずつ実行してください。

[ ] クライアント側のAPI形式と、上流に指定したformatが一致している
[ ] 単一モデル透過で通常応答とストリーミング応答を確認した
[ ] ツール呼び出しの名前、引数、エラー応答を確認した
[ ] APIキーを設定ファイルやシェル履歴へ平文で残していない
[ ] /healthの監視とプロセス再起動方法を決めた
[ ] ルーティング変更時のロールバック手順を作った
[ ] リクエスト数、遅延、入力・出力トークンを記録できる
[ ] フォールバック発生時に、品質低下を検知できる
[ ] 複数ターンのセッション親和性を実際のAgent作業で確認した
[ ] Rust serverを使う場合、Python CLIと同じ設定が使えると仮定せず、TOMLを別途検証した

Switchyardの公式READMEでは、リクエストごとの遅延、トークン、コスト統計が主要機能として挙げられています。ただし、統計が取得できることと、チームの監視基盤へ適切に連携できることは別です。保存期間、個人情報の扱い、ログのマスキングまで決めてください。(github.com)

2026年の導入判断

今週は、まずPython proxyで単一モデル透過を試してください。その後、Claude Codeのツール呼び出しと長いセッションを通し、問題がなければランダムルート、分類器、ステージルーターの順に比較するのが安全です。

Rust serverは、Rustベースのサービス境界や独立した運用プロセスが必要な場合に検討します。ただし、Python側のLauncher、設定、統計、プロトコル変換がそのまま同じ形で利用できるとは限りません。

現在の構成がクライアントごとの個別設定、手作業のAPIキー配布、モデル障害時の手動切り替えに依存しているなら、運用負担と切り分け時間が増えます。長時間動かすゲートウェイには、安定したCPU・メモリ、常時稼働、ログ保全、再起動管理が必要です。

短期間の検証やClaude Code用の隔離環境を用意するなら、HashvpsのMacレンタル環境を使って実行場所を分ける方法もあります。まずはClaude Codeのスキル構成を確認するガイドや、AIコーディングエージェントの選び方でクライアント側の要件を整理してください。

物理GPUで長期的に大規模推論を続ける用途や、特定の物理インターフェースが必要な用途では、専用サーバーや自社設備のほうが適しています。一方、Switchyardの接続検証、Agent Launcherの評価、短期のAI Gateway試験を安全に切り出したいなら、HashvpsのMac環境を使うほうが、手元の開発環境を変更せずに試しやすい選択肢になります。