LLMルーティングを担うOSS「Switchyard」の仕組みと特徴

エージェントからのリクエストをすべてフロンティアモデルに投げると、コストは容赦なく膨らみます。かといって小さいモデルに寄せれば、難しいターンで品質が落ちます。多くのチームがこの綱引きの真ん中で止まっているのではないでしょうか。

やっかいなのは、モデルを混ぜようとした瞬間にもう一つの壁が現れることです。OpenAI Chat Completions を前提に書いたアプリを Anthropic Messages のバックエンドへ向けるには、リクエストとレスポンスの変換を自前で書くことになります。Claude Code のようなコーディングエージェントを別のモデルで動かしたい場合はなおさらです。

さらに根本的な問題として、「どのリクエストをどのモデルに流すか」という判断ロジックそのものは、既存の LLM ゲートウェイでは設定項目として用意されていないことが多く、ロードバランスやフォールバックの範囲にとどまりがちです。判断の中身は結局アプリケーション側に染み出します。

Switchyard は、この判断ロジックそのものを型付きのアルゴリズムとして提供し、OpenAI / Anthropic の API 互換を保ったままリクエストを振り分ける Rust 製の OSS です。NVIDIA の NeMo プロジェクト配下で公開されています。

本記事では、基本情報とアーキテクチャ、ルーティングアルゴリズムの中身、導入経路、運用時の注意点、類似 OSS との守備範囲の違い、そして採用判断の軸を、公式ドキュメントと GitHub API の実測データに基づいて整理します。なお本記事はドキュメントベースの調査であり、動作検証は行っていません。また Switchyard は執筆時点で pre-alpha 段階であり、公式に「本番利用向けではない」と明記されています。この前提を先に共有したうえで読み進めてください。

Switchyardとは｜LLMルーティングとAPI変換を担うOSS

Switchyard は、README で「Switchyard is a Rust proxy and library for LLM traffic.」と定義されています。プロバイダをまたいだリクエストのルーティング、OpenAI と Anthropic の API 間の変換、運用メトリクスの記録、そして型付きで合成可能なルーティングアルゴリズムの提供という 4 つを担います。

ここでいう「ルーティング」とは、届いたリクエストをどのモデル（バックエンド）に流すかを決めることです。「プロトコル変換」は、クライアントが話す API 形式と上流のモデルが受け付ける形式が違う場合に、リクエストとレスポンスを相互に翻訳することを指します。

基本情報

GitHub API で取得したリポジトリの実測値は以下のとおりです（いずれも 2026 年 8 月 26 日時点）。

リポジトリの作成は 2026 年 5 月 19 日で、リリースは v0.0.1 と v0.1.0 が 2026 年 6 月 30 日、v0.2.0 が 2026 年 8 月 10 日に公開されています。作成から 3 か月あまりでスターが 2,445 に達し、最終 push が前日という状態は、開発が活発に動いていることを示しています。ソースと README は Switchyard の GitHub リポジトリ で確認できます。

pre-alpha であり、本番利用向けではない

採用判断の前提として最も重要な点を先に共有します。README の Maturity セクションには「Switchyard is pre-alpha software that is evolving rapidly. The API and algorithms are expected to change significantly before we reach v1.0.」と書かれ、さらに警告ボックスで「Experimental software. Not for production use.」と明記されています。

つまり、API もアルゴリズムも v1.0 到達までに大きく変わる前提の段階です。開発が活発であることと、いま本番トラフィックを預けられることは別の話です。以降のセクションも、「明日から本番のコストを下げる道具」ではなく「ルーティング設計の考え方を得るための材料」として読むと、判断を誤りにくくなります。

Switchyardが解決する課題｜モデル選択とAPI互換の分断

NVIDIA の技術ブログでは、Switchyard の出発点となる課題設定が示されています。モデルごとに強み・弱み・コストプロファイルが異なるため、すべてのリクエストを最大のモデルに送れば無駄が出て、逆に小さいモデルに寄せれば品質が落ちる、というものです（NVIDIA 公式ブログ）。

この課題に対して NVIDIA が公表している数値があります。LangChain による 145 件のマルチターンエージェントタスクのベンチマークでは、NVIDIA Nemotron 3.5 Lightning と Claude Opus 4.8 の間でルーティングした場合、フロンティアモデルのみのベースラインと比べてコストが 74% 削減され、フロンティアモデルへの呼び出しは全体の 7% にとどまり、精度のトレードオフは約 6 ポイントだったと報告されています。また Cognition の FrontierCode における導入例では、平均コスト 28% 減でフロンティア精度との差は 2.8 ポイントとされています。

ただし、これらはいずれも NVIDIA が製品としての NeMo Switchyard について公表している値であり、OSS として公開されている pre-alpha の v0.2.0 で同じ結果が出ることを保証するものではありません。効果の桁感を掴む参考値として扱うのが妥当です。

もう一つの課題が API 互換の分断です。README の「Why Switchyard?」では、Claude Code や Codex のようなコーディングエージェントをオープンソースモデルに向けられる点が最初のユースケースとして挙げられています。Switchyard が OpenAI Chat・Anthropic Messages・OpenAI Responses の各形式を翻訳するため、エージェント側はネイティブ API を話したまま、リクエストは vLLM、NVIDIA NIM、Ollama、その他の OpenAI 互換エンドポイントで処理されます。

採用判断としては、ここが自分の課題と重なるかが最初の分岐点です。「モデルは 1 つで十分だがプロバイダ障害に備えたい」という要求であれば、Switchyard の中心的な価値である判断ロジックはオーバースペックになります。

Switchyardの仕組み｜LLMクライアント・ターゲット・ルートの3層

Switchyard の設定モデルは 3 つの層に分かれています。この分離が設計思想の中心であり、既存構成に組み込めるかを判断する材料にもなります。

3層モデル

この分離によって、「プロバイダへどう転送するか」と「どのモデルに任せるか」が独立します。複数のターゲットが 1 つの LLM client を共有でき、複数のルートが同じターゲットを再利用できます。認証情報は、シークレット自体を TOML に書かず api_key_env で環境変数名を指定する設計です。詳細は公式ドキュメントの Core Concepts にまとまっています。

押さえておきたいのが、公式ドキュメントに書かれた「strong・weak・capable・efficient はアルゴリズム内の役割であり、モデル固有の属性ではない」という整理です。同じ上流モデルが、あるルートでは weak、別のルートでは strong を担えます。モデルを固定的に格付けするのではなく、ルートごとに役割を割り当てる考え方です。

リクエストが変換される流れ

リクエストは次の順に処理されます。クライアントの形式で受け取り、プロバイダ中立の型にデコードし、ルートのアルゴリズムがターゲットを決め、選ばれたターゲットの上流フォーマットにエンコードして送信し、返ってきたレスポンスをクライアントが期待する形に再変換します。

このプロバイダ中立の型を定義しているのが switchyard-protocol クレートで、リクエスト・レスポンス・メッセージ・コンテンツブロック・ツールコール・usage・ストリーミングイベントを扱います。相互変換を担当するのが switchyard-translation です。各 LLM client は上流フォーマットとして openai_chat / openai_responses / anthropic_messages のいずれか 1 つを選びます。

モデル ID の考え方

target の id は上流に送るモデル ID、route の id はクライアントが model に指定するモデル ID です。GET /v1/models はルート ID を列挙します。

ここで注意したいのが、Switchyard はモデルカタログの自動探索・自動登録を行わない点です。上流のモデルを複数そのまま見せたい場合は、モデルごとに passthrough ルートを 1 つずつ定義する必要があります。プロバイダを追加すれば自動でモデル一覧が増えるタイプのゲートウェイを期待していると、運用イメージがずれます。

Switchyardのルーティングアルゴリズム

Switchyard らしさが最も出るのがこの部分です。公式の Routing Overview では、次の戦略が一覧されています。

一点、判断材料として共有しておきたいことがあります。リポジトリ内のドキュメント間で、対応するルート種別の記述に差があります。TOML スキーマのリファレンスに見出しとして存在するのは noop / passthrough / random / llm_classifier / stage_router / hierarchical で、advisor の独立した項目は確認できませんでした。サーバークレートの README は対応アルゴリズムをさらに絞って記載しています。pre-alpha であることの具体的な現れ方でもあるため、採用を検討する際は最新のドキュメントとリリースノートで対応状況を確認することをおすすめします。

以下では、設計思想がよく表れている 2 つを取り上げます。

Stage-Router：会話のシグナルから段階を推定する

Stage-Router は、追加の分類用 LLM 呼び出しをせずに、会話に既にあるツール結果の履歴からタスクの段階を推定します。探索中・エラー回復中・難しい推論のターンには capable なモデルを、機械的な作業には efficient なモデルを割り当てるという考え方です（Stage-Router Routing）。

判断は 2 つの方向のシグナルで行われます。capable 側に引っ張る指標が、直近のエラー重大度を表す severity、読み書きが進んでいない空回りを表す spinning、成果物を出さずに読む・計画するだけの状態を表す exploring です。逆に efficient 側に引っ張るのが、直近の書き込みや編集の着地を表す recent_production_intensity です。

興味深いのは確信度の設計です。符号付きスコアを tanh で 0 から 1 の範囲に圧縮するため、単一のシグナルだけでは約 0.46 にとどまり、2 つ目の裏付けが入って初めて閾値 0.5 を明確に超えます。単独のノイズで層が切り替わらないよう、裏付けを要求する設計になっているわけです。ただし critical レベルのエラー重大度は単独でエスカレーションするハード上書きとして扱われます。

確信度が confidence_threshold を下回るターンや、ツール結果の履歴がまだ無いターンは、picker の既定層に落ちます。picker にはコスト優先の efficient_first と品質優先の capable_first があり、後者は experimental で、公開されている閾値や結果はすべて efficient_first の実行由来である点がドキュメントに明記されています。

Escalation-Router：事後判定で strong に固定する

Escalation-Router は、会話を安価な weak モデルで開始し、LLM の judge がその応答を読んで、継続的な不調を検知した時点でセッションを strong モデルに latch（固定）します。実行前に難易度を予測する LLM Classifier に対し、うまくいっているかどうかを事後に判定する点が違いです。

1 ターンの流れは、weak を呼んで応答をバッファし、その応答を含む履歴を judge に判定させ、escalate 判定なら連続カウントを加算、decline ならリセット、というものです。カウントが confirmations に達していなければバッファした weak の返答をそのまま返すため、そのターンのコストは weak 1 回と judge 1 回で済み、strong は呼ばれません。カウントが confirmations に達すると、バッファを破棄して strong で応答し直します。latch 済みのセッションは judge を呼ばず直接 strong に流れます。

ターンごとのコスト構造が明示的に決まるこの設計は、見積もりを立てやすいという意味で採用判断に効きます。設定例では escalation = { confirmations = 2, recent_turn_window = 28, window_message_chars = 500 } のように指定します。

サブエージェント別のポリシー

もう一つ、他のゲートウェイであまり見かけないのがサブエージェント単位のポリシーです。親エージェントのトラフィックは設定済みのアルゴリズムのまま流し、委譲されたサブエージェントの作業だけを別ポリシーで扱えます。passthrough と stage_router のルートで subagents テーブルとして利用でき、classify_trigger = "new_session" を指定すれば同じセッションとエージェントの組み合わせについて判定結果を再利用できます。「レビュー系のサブエージェントだけ強いモデルに寄せたい」といった要求がある場合、この粒度で書けるかどうかは実装量の差に直結します。

Switchyardの使い方｜サーバー経路とライブラリ経路

導入経路は 2 つあります。スタンドアロンのプロキシとして立てる経路と、Rust アプリケーションにライブラリとして組み込む経路です。

サーバー経路

サーバー経路では、crates.io で公開されている switchyard-server をインストールします。README には次のコマンドが示されています。

cargo install --locked switchyard-server
switchyard-server --help

出典: https://github.com/NVIDIA-NeMo/Switchyard

次に routes.toml を用意します。公式の Getting Started には、LLM classifier ルートの最小構成が掲載されています。

schema_version = 1

[llm_clients.openrouter]
format = "openai_chat"
base_url = "https://openrouter.ai/api/v1"
api_key_env = "OPENROUTER_API_KEY"

[targets.weak]
id = "openai/gpt-4o-mini"
llm_client = "openrouter"

[targets.strong]
id = "openai/gpt-4o"
llm_client = "openrouter"

[routes.smart]
id = "switchyard"
type = "llm_classifier"
mode = "capability"
classifier_target = "weak"
strong_target = "strong"
weak_target = "weak"
base_threshold = 0.5

出典: https://nvidia-nemo.github.io/Switchyard/getting_started/

先ほど触れた 3 層がそのまま TOML の構造になっているのが分かります。api_key_env はサーバーが読む環境変数の名前であり、シークレットそのものを TOML に書かない設計です。呼び出し元の資格情報をそのまま上流に転送したい場合は forward_auth = true を使えますが、別プロバイダの API 経由で呼ばれた forwarding ルートはサーバー側が拒否します。

起動前の検証と起動は次のコマンドです。

export OPENROUTER_API_KEY="your-openrouter-key"  # pragma: allowlist secret
switchyard-server --config routes.toml --dry-run
switchyard-server --config routes.toml --host 127.0.0.1 --port 4000

出典: https://github.com/NVIDIA-NeMo/Switchyard

--dry-run は、ソケットを開かずにスキーマ・環境変数参照・ターゲット参照・ルート構築を検証します。設定ミスを起動前に潰せるため、CI に組み込む対象として使いやすい部分です。起動後は /health で疎通を、/v1/models でルート一覧を確認し、/v1/chat/completions の model にルートの id を指定してリクエストを投げる流れになります。

前提として Git、ネイティブのビルドツールチェーン、Rust と Cargo が必要です。導入コストを見積もる際は、Rust ツールチェーンを扱えるかと、ルート設計を TOML で保守できるかの 2 点が実質的な入口になります。

ライブラリ経路

もう一つの経路が switchyard-libsy です。README によれば、このクレートは自分ではモデルを呼びません。アルゴリズムがどのターゲットを使うかを決め、モデル呼び出しは呼び出し側に返します。HTTP スタックを持たないため、既存のプロキシ・ゲートウェイ・エージェントランタイムの内側にルーティング判断だけを差し込めます。呼び出しも任せたい場合は switchyard-llm-client を併用する構成になります。

既に LiteLLM などのゲートウェイを運用していて、それを置き換えたくはないが判断ロジックだけ強化したい、というケースではこの経路が候補になります。ただし組み込み先が Rust であることが前提です。

セルフホストモデルを上流に置く場合

任意のターゲットを、自分で運用する OpenAI 互換のモデルサーバーに向けることもできます。Routing Overview では vLLM を例に、次のように LLM client を宣言する構成が示されています。

[llm_clients.local_vllm]
format = "openai_chat"
base_url = "http://localhost:8000/v1"

[targets.local]
id = "my-rl-qwen"
llm_client = "local_vllm"

[routes.local]
id = "local"
type = "passthrough"
target = "local"

出典: https://nvidia-nemo.github.io/Switchyard/routing_algorithms…

資格情報が不要なサーバーであれば api_key_env は省略できます。同ページには「Switchyard はモデルサーバーの起動や管理を行わず、設定済みのエンドポイントにリクエストを送るだけである」と明記されています。推論基盤そのものの面倒を見てくれるわけではない点は、構成を検討するうえで押さえておきたいところです。

運用面の特徴｜メトリクスと0.2.0の既知の制約

サーバーが公開するエンドポイントは、OpenAI Chat Completions（/v1/chat/completions）、Anthropic Messages（/v1/messages）、OpenAI Responses（/v1/responses）の 3 系統に加え、モデルを呼ばずに選択ターゲットとフォールバックだけを解決する /v1/decision、ルート一覧の /v1/models、モデル別使用量とアルゴリズム統計を返す /v1/stats、Prometheus 形式の /metrics、死活監視の /health などです。

メトリクスでは、リクエスト数・エラー数・レイテンシ・トークン数といった一般的な項目に加えて、注目に値するものが 2 つあります。

1 つは switchyard_routing_overhead_ms です。ルーティング判断そのものに要した時間をアルゴリズム別に計測するヒストグラムで、サーバー側の設定でバケットが 0.1 ミリ秒から始まります。「ルーターを 1 段噛ませて割に合うのか」という疑問に、実測で答えられる形になっています。もう 1 つが switchyard_classifier_fail_open_total で、judge が失敗して verdict なしのままルーティングした件数を数えます。判断ロジックが期待どおり働いているかを監視する指標です。

このほか、--routing-log-file を指定すると完了レスポンスごとに JSON レコードが追記され、セッション統計のエンドポイントがそのログを再走査してモデル別の呼び出し回数とトークン合計を返します。上流呼び出しのリトライは既定で 2 回、SIGTERM 受信時は新規接続を止めて既定 30 秒まで実行中リクエストをドレインします。

0.2.0 の既知の制約

公式の Known Issues には、v0.2.0 時点の既知の問題が列挙されています。採用判断に直結するものを挙げます。

• クライアントが切断した後もバッファ済みの上流処理が継続するため、キャンセルしたリクエストでもプロバイダ側の課金が発生しうる
• /v1/stats と /metrics で、judge 失敗による既定ターゲット送りやエスカレーション判断などについて、ルーティング層の属性が欠落する
• リトライが成功した後もリトライ回復カウンタが 0 のままになる
• セッション ID がネイティブのセッション統計に記録されない
• ドキュメントに記載されているバージョンヘッダーを、ネイティブサーバーが上流に送っていない

1 つ目は、コスト最適化のために導入するツールで課金が読みにくくなるという意味で、影響が最も大きい項目です。裏を返せば、これらが明文化されている点は評価できます。制約が公開されていれば、検証時に何を測るべきかを事前に決められるためです。

類似OSSとの違い｜LiteLLM・Portkey・Bifrost・semantic-router

Switchyard の位置づけを掴むには、隣接する OSS との守備範囲の違いを見るのが早道です。以下は 2026 年 8 月 26 日に GitHub API で取得した実測値です。

この比較から導ける使い分けは次のとおりです。

• プロバイダの網羅性、ガードレール、コスト上限や課金管理が要件なら LiteLLM・Portkey・Bifrost が候補になります。Switchyard はこれらをドキュメント上の主眼としていません
• vLLM を前提とした推論基盤の内側で振り分けたいなら semantic-router が近い位置にいます
• ルーター自体の学習や評価を研究対象にするなら RouteLLM が該当しますが、更新が止まっている点は考慮が必要です
• ルーティング判断そのものを型付きで設計・計測し、OpenAI 形式と Anthropic 形式をまたいで振り分けたいなら Switchyard の守備範囲です

Switchyard 固有の差分は、ルーティングを合成可能なアルゴリズムとして扱う点、3 つの API 形式を相互変換してコーディングエージェントをネイティブ API のまま別バックエンドに向けられる点、HTTP スタックを持たないライブラリ経路を用意している点、ルーティング自体のオーバーヘッドを分離計測するメトリクス設計を持つ点の 4 つに集約されます。逆に担わない領域は、プロバイダカタログの自動探索、コスト上限や課金管理、ガードレール、モデルサーバー自体の起動・管理です。優劣ではなく、そもそも守備範囲が違うと捉えるのが正確です。

もう一点、「LLM ルーター」という言葉には別系統のツールも含まれるため、切り分けておきます。9router や OmniRoute のように、Claude Code や Cursor といったコーディング CLI から複数のプロバイダを束ね、手元の開発環境でレート制限や利用コストを回避することを主眼に置いたゲートウェイです。これらは個人開発者が自分の作業環境を整えるための道具であり、本記事の Switchyard のように、本番の LLM アプリケーションが流すトラフィックをモデル・プロバイダ間でコストとレイテンシーの観点から配分し、その判断自体を計測しながら運用するライブラリ／プロキシとは、対象読者も活用シーンも異なります。

Switchyardの採用を判断する観点

ここまでの内容を、判断の軸として整理します。

向いているケースは次のような状況です。ルーティング方針を自分たちで設計し、その効果を計測したい。コーディングエージェントを別のバックエンドに向けたい。既存ゲートウェイの内側に判断ロジックだけを足したい。あるいは、まず検証環境でモデル構成を A/B 比較して知見を貯めたい。

向いていないケースも明確です。今すぐ本番のコストを下げる必要がある。プロバイダの網羅性とガードレール・課金管理が必須要件である。Rust を扱う運用体制がない。これらに当てはまる場合は、実績のある汎用ゲートウェイを選ぶほうが合理的です。

本番トラフィックを預けずに評価する方法も、ドキュメントの機能説明から読み取れます。1 つは random ルートで固定比率のトラフィック分割を行い、モデル構成の A/B をベースラインと比較する方法です。もう 1 つは、モデルを呼ばずに選択ターゲットとフォールバックだけを返す /v1/decision を使い、ルーティング判断だけを既存構成の外側で観察する方法です。判断の質を先に確かめてから、トラフィックを流すかを決める順序が取れます。いずれも公式ドキュメントの記述に基づく進め方の提案であり、本記事で検証したものではありません。

まとめ

Switchyard は、LLM クライアント・ターゲット・ルートという 3 層でプロバイダ転送とルーティング方針を分離し、Stage-Router や Escalation-Router といった型付きのアルゴリズムで「どのモデルに任せるか」を設計可能にし、OpenAI Chat・OpenAI Responses・Anthropic Messages の相互変換によってクライアントを書き換えずにバックエンドを差し替えられるようにした OSS です。

一方で、2026 年 8 月 26 日時点のリポジトリは pre-alpha であり、本番利用向けではないと公式に明記されています。クライアント切断後も上流処理が続いて課金が発生しうるといった既知の制約も残っています。

それでも、いまこのリポジトリを読む価値はあります。ツール結果のシグナルから段階を推定する、単一シグナルでは閾値を超えさせない、事後判定で strong に latch する、ルーティングのオーバーヘッドを分離計測する——こうした設計の語彙は、Switchyard を採用するかどうかとは別に、自分たちのモデル振り分けを設計する際の判断材料になります。

まずは Core Concepts で 3 層モデルを掴み、Routing Overview でアルゴリズムの選択肢を確認し、Known Issues で現時点の制約を把握する、という順で読み進めるのがおすすめです。

関連情報

LLM を組み込んだプロダクト開発や、既存システムへの AI 機能追加をご検討中の方は、お問い合わせフォーム からご相談ください。技術選定や要件の整理段階からご相談いただけます。