NVIDIA NeMo Relay と NeMo Switchyard を AI Gateway としてどう使うか考えてみた
はじめに
こんにちは、クラスメソッド製造ビジネステクノロジー部の森茂です。
AI Gateway という言葉を聞くと、AI への接続口を一つにまとめる製品を思い浮かべるのではないでしょうか。実際には、モデルの振り分け、利用者認証、予算管理、監査まで、かなり幅広い機能がこの言葉に含まれます。全部入りを一度に用意しようとすると、普段の coding agent の環境にはどうしても重い。モデルを使い分けたいのか、ファイル操作やコマンド実行まで記録したいのか、チームごとの利用量を制限したいのか。欲しい機能によって、置く部品は変わります。
これまで NeMo Relay と NeMo Switchyard は、それぞれ単体で試してきました（Relay は 2026-08-06、Switchyard は 2026-08-12 時点の記事です）。Relay の記事では 0.6.0 を coding agent の実行を記録・制御するランタイムとして、Switchyard の記事では v0.2.0 を複数モデルへの振り分けと API 形式の変換を担うサーバーとして紹介しています。Relay はその後 0.8 系へ進んでいて、今回は 0.8.1 を使います。
ここで気になるのが、この二つを普段の AI 開発環境でどう使うかです。どちらかを単体で置けばよいのか、直列につなぐと何が増えるのか。利用者認証や予算管理のように、どちらも持っていない機能は何で補えばよいのか。整理してみると、「Relay と Switchyard で AI Gateway を作る」というより、「足りない機能を専用の部品で必要な場所へ足す」話に落ち着きました。
この記事では、NeMo Relay 0.8.1 と NeMo Switchyard v0.2.0 を初めて知る方でも追えるよう、まず一つの依頼がモデルへ届くまでの流れを紹介します。そのうえで、単体と直列の使い分けと、不足する機能を外側の部品で補う構成案を整理します。構築コマンドではなく、普段の環境へ何を足すかを決めるための記事です。
まず Relay と Switchyard をざっくりつかむ
先に二つの役割を、日常の言葉に置き換えておきます。
Switchyard は、AI モデルへの交換台です。coding agent からは switchyard/auto のような共通の接続名で呼び出しを受け、内容や進行段階に応じて接続先のモデルを選びます。Switchyard の設定では、この接続名を route と呼びます。OpenAI Chat、OpenAI Responses、Anthropic Messages の 3 形式を受けて、接続先に合わせて変換するのも Switchyard の仕事ですね。
Relay は、対応している coding agent の作業記録と制御を担当します。ユーザーの依頼を受けてから、どの LLM を呼び、どのファイルを読み、どのコマンドを実行したか。この一連の流れを一つの実行として記録します。途中に処理を差し込む middleware があり、LLM や tool の呼び出しを検査したり書き換えたりもできます。
| 道具 | 一言で表すと | 答えてくれること | 単体では担当しないこと |
|---|---|---|---|
| NeMo Switchyard | モデルへの交換台 | この依頼をどのモデルへ送ったか | coding agent が実行したファイル操作やコマンド |
| NeMo Relay | agent 実行の記録・制御レイヤー | この作業で LLM と tool がどう動いたか | 複数モデルから接続先を選ぶこと |
| API Gateway など | チーム利用の受付 | 誰が利用でき、どこまで使えるか | agent の実行記録とモデルの内容ベース routing |
用語を 4 つだけ。provider は OpenAI や Anthropic のようなモデル API の提供先、tool は coding agent が行うファイルの読み書きやコマンド実行です。session は一つの作業、trace はその作業から発生した通信を追うための識別情報、と捉えておけば以降は読めます。
一つの依頼がモデルへ届くまでを見る
両方を使う場合、coding agent のすぐ近くに Relay を置き、その先に Switchyard を置きます。
たとえば、coding agent へ「失敗しているテストの原因を調べて」と頼んだとします。流れはこうなります。
- Relay が一つの agent 作業として記録を始める
- coding agent がファイルを読むと、Relay が tool 実行として記録する
- coding agent が LLM を呼ぶと、Relay が request を Switchyard へ渡す
- Switchyard が低コスト側と高性能側などの候補から接続先を選ぶ
- Switchyard は選んだモデルと token 数を記録し、Relay は LLM 呼び出しを agent 作業へ結び付ける
Switchyard だけを置いた場合でも、3 から 5 のモデル選択と利用量の記録はできます。ただし 1 と 2 の agent 作業や tool 実行は見えません。Relay だけを置いた場合は、1 と 2 に加えて LLM 呼び出しまでは記録できますが、request の行き先は OpenAI 系と Anthropic 系でそれぞれ固定で、モデルごとの振り分けはしません。
つまり、二つを最初からセットで入れる必要はないわけです。
欲しい機能から三つの構成を選ぶ
普段の環境なら、まず次の三つから選べます。
| 構成 | 向いている場面 | 具体的に増えるもの |
|---|---|---|
| Switchyard 単体 | 接続先を一つにし、複数モデルを使い分けたい | API 形式変換、モデル選択、retry、選んだモデルと token の記録 |
| Relay 単体 | モデル選択は変えず、coding agent の作業内容を記録・制御したい | agent、LLM、tool の記録、処理の差し込み、記録の外部出力 |
| local Relay → Switchyard | tool 実行の前後と、実際に選ばれたモデルを同じリクエスト経路で確認したい | 上記二つの機能。ただし識別情報まで自動統合されるわけではない |
両方を置く意味が出るのは、「テストを読み終えた後にどのモデルへ送ったか」「同じ作業の中でモデルが切り替わったか」を agent の動きと一緒に見たい場合です。個人的には、最初から二つを常駐させるより、先に困っている側から入れるのが現実的かなと思っています。
直列につないで基本動作を確かめた
ここからが本題です。macmini に Relay 0.8.1、DGX Spark に Switchyard v0.2.0 と合成 provider を置き、SSH tunnel で直列につなぎました。合成 provider にしたのは、実在の API key を使わずに済ませたかったのと、429 を狙った回数だけ返すなど provider 側の挙動を固定したかったからです。見ているのは、request と記録が各層でどう扱われるかです。
主な結果は次のとおりです。
| 確認したこと | 結果 |
|---|---|
| API 形式 | OpenAI Chat、Responses、Anthropic Messages と各 streaming が同じ Switchyard route で応答した |
| tool call | OpenAI Chat 形式で保持された。他の 2 形式の tool call は未検証 |
| 一時エラーからの復旧 | 合成 provider の 429 → 429 → 200 に対し、1 回の呼び出しを 3 attempts で回復した |
| provider の API key | Switchyard に設定した API key が provider へ送られた |
| Relay の作業記録 | 3 LLM calls から、イベント形式の記録（ATOF）10 件と作業の時系列記録（ATIF）6 step が生成された |
| PII の扱い | 合成 email は Relay の記録から消えたが、provider が受け取った本文には残った |
いちばん目を引いたのは attempts と calls の差です。Switchyard の retry を含めると、完了した 12 calls に対して provider への attempts は 14 回。利用量を見るときは、ユーザーから見た呼び出し回数と、retry を含む provider への試行回数を分けて数える必要がありますね。
API 形式の変換、routing、retry、そして Relay の作業記録を同じ経路へ置けることは、これで確認できました。一方で、二つをつないだだけでは揃わない情報もあります。
組み合わせるときは四つのズレを押さえる
細かい header 名より先に、運用で何が起きるかを表にしておきます。
| 確認点 | 直列接続で起きたこと | 補う方法 |
|---|---|---|
| 作業の識別子 | Relay の session ID はログに見えるが、Switchyard v0.2.0 の session 集計へつながらない | header adapter で Switchyard が読む名前へコピーする |
| 通信の追跡 | Relay が新しい trace の起点になり、その内側の LLM calls をまとめる | Relay を起点として OpenTelemetry Collector へ集約する |
| API key | Switchyard の provider 用 API key へ置き換わる | 利用者認証は Switchyard の前段へ追加する |
| PII | Relay の観測データから消えても、provider へ送る本文には残る | 送信前の DLP または sanitize middleware を Relay 側へ追加する |
作業の識別子は、荷物に付ける伝票番号のようなものです。Relay と Switchyard が違う欄を見ていると、同じ文字列が request log に残っていても、Switchyard の session 集計には使われません。v0.2.0 では、同じ ID を proxy_x_session_id という名前で渡せば session 集計に載ることを確認しました。Relay の x-nemo-relay-session-id をこの名前へコピーする header adapter を間に置けば接続できますが、adapter 自体は今回作っていません。
Switchyard 単体では、入力した traceparent がそのまま provider まで届きました。Relay を前段に置くと Relay が新しい trace の起点になり、今回の 3 LLM calls はその内側にまとまります。Relay より前の trace が素通りする構成ではない、という点は押さえておきたいところです。
API key は、Switchyard に置いた provider 用の値が provider へ送られました。coding agent に provider key を直接置かずに済む一方で、「Switchyard を呼んだ人が誰か」は判定していません。共有するなら、利用者認証を前段へ足すことになります。
PII は特に誤解しやすいところです。Relay の組み込み PII redaction が伏せるのは、外部の観測基盤へ送るデータのほうです。provider へ送る prompt の本文は変えません。今回も合成 email は Relay の記録からは消えて、provider が受け取った本文には 1 件そのまま残っていました。送信前に伏せたいデータは、別の middleware で処理します。
足りない機能は専用の部品で補う
Relay と Switchyard が担当しない機能を、まとめて別の LLM Gateway へ任せる必要はありません。既存の API 基盤や観測基盤から、必要な部品だけを足せます。この表の部品は今回の実測には含めていない構成案で、実測で確認したのは前章までの Relay と Switchyard の挙動だけです。
| 欲しい機能 | 追加する部品 | 置く場所 | 得られること |
|---|---|---|---|
| 利用者認証と接続先ごとの認可 | API Gateway または ingress と Identity Provider | Relay と共有 Switchyard の間 | 誰がどの接続先を呼べるか判定する |
| 利用者別の呼び出し頻度制限 | ingress の rate limiter | Switchyard の前段 | user、team、project 単位で呼び出し速度を制限する |
| 利用量と予算の上限 | 利用量集計、利用台帳、制御ルールのサービス | API Gateway と Switchyard の間 | 利用者 ID、token、金額を蓄積し、上限到達後の request を止める |
| provider key の保管と rotation | AWS Secrets Manager や Vault などの secret manager | Switchyard の起動時に環境変数として注入 | API key を設定ファイルやクライアントから分離する |
| provider 送信前の PII と秘密の除去 | Relay request middleware と Presidio などの DLP（機密データ検出）service | coding agent と Switchyard の間 | prompt が端末や信頼境界を出る前に検査・加工する |
| 観測の集約 | OpenTelemetry Collector と trace、metrics、logs の backend | Relay の OTLP を受信し、Switchyard を scrape | agent の作業記録と model routing の記録を一か所で検索する |
| 長期監査 | ATOF、ATIF の保存先と object storage | Relay の観測出力 | イベント記録と作業の時系列記録を保持期間に合わせて保存する |
| session の接続 | reverse proxy または Relay plugin による header adapter | Relay と Switchyard v0.2.0 の間 | Relay の一作業と Switchyard の model 利用量を同じ ID で検索する |
| provider の接続先制限 | Switchyard へ登録する target の限定と egress firewall | Switchyard と network の出口 | 許可した provider 以外へ通信できない状態を作る |
利用量と予算は、記録するだけでは制限になりません。認証済みの利用者 ID と、Switchyard が返す token 数、モデル選択の記録を利用量集計で結び付けて、利用台帳へ蓄積します。次の request を受ける前に API Gateway 側が制御ルールへ照会すれば、上限を超えた利用を止められます。
Switchyard v0.2.0 の provider key は、api_key_env で指定した環境変数から読みます。secret manager と組み合わせるなら、値を環境変数へ注入する方法に加えて、key の rotation 時に Switchyard をどう更新・再起動するかも運用に含めておきたいところです。
既存の AI Gateway があるなら役割を重ねない
すでに利用者ごとの仮想 API key、予算上限、呼び出し頻度制限を持つ AI Gateway があるなら、そのまま使えます。既存 Gateway のモデル振り分けで要件を満たせるなら、local Relay → 既存 AI Gateway → providers として、Switchyard を足さない構成のほうが小さくなります。
Switchyard の本文によるモデル分類や、agent の進行段階によるモデル選択を使いたいときは、local Relay → 既存 AI Gateway → Switchyard → providers です。このとき既存 Gateway は利用者認証と利用制御、Switchyard はモデル選択に役割を絞ります。二つの層がそれぞれモデルを書き換えると、最終的な選択理由を追いにくくなるからです。
利用規模に合わせて構成を増やす
追加部品まで含めたチーム向けの構成を図にすると、次のようになります。
個人利用は一つの困りごとから始める
自分の端末だけで使うなら、Switchyard か Relay の単体で足りることが多そうです。困っている側を loopback で動かして、両方の情報が必要になったら直列にする、という順番ですね。
チーム利用は受付を Switchyard の前へ置く
チームで Switchyard を共有するなら、API Gateway または ingress を前段に置いて Identity Provider と連携します。利用者の ID を rate limit、budget、監査記録の共通キーにします。provider key は secret manager から Switchyard へ渡し、クライアントには配布しません。
Relay は各開発者の端末側に残します。共有 Relay を一つ置いても、各 coding agent の hook で取る tool 実行は集まらないからです。実行はローカル、model routing と利用制御は共有、観測 backend は中央、という分け方になります。
観測の合流点は OpenTelemetry Collector です。Relay の OTLP と Switchyard の Prometheus metrics をここで受けますが、前章で見たとおり trace の起点と session header は自動では揃いません。user ID や project ID を metadata として足して、検索の軸を明示しておきます。
機密データを扱うなら端末を出る前に検査する
prompt に個人情報や秘密情報が入り得るなら、local Relay の request middleware から Presidio のような DLP service を呼び、検出した値を削除・置換してから Switchyard へ渡します。API Gateway や Switchyard へ届いてから消すのではなく、信頼境界を出る前に検査する配置です。Relay の PII redaction は観測用として残して、二つを別の目的で使い分けます。
この構成でも、DLP の誤検知と見逃し、加工後の prompt 品質は別に評価が要ります。Relay に middleware を置けることと、採用した DLP の精度は分けて考えたいところです。
現行版の先には二段 proxy 以外の形が見える
今回確かめたのは、Relay 0.8.1 と Switchyard v0.2.0 を別々のサーバーとして直列にする構成です。ただ、最新版の動きを見ていると、この二段構成が今後も唯一の組み方とは限らなさそうです。
Relay 0.8 では、Switchyard server へ接続する従来の組み込み機能が削除されました。Relay の release notes には、Switchyard 0.3.0 が Switchyard 側で管理する dynamic plugin を配布・文書化する予定だと書かれています。Switchyard のモデル選択を Relay の process 内で動かす方向ですね。Relay 自体も 0.8 系で plugin と middleware の拡張を進めています。
現在使えるものと今後の方向を分けると、次のようになります。
| 区分 | 使い方 |
|---|---|
| Relay 0.8.1 と Switchyard v0.2.0 | Relay から Switchyard server へ HTTP で接続する |
| Switchyard main | session header の整理と呼び出し元 API key の転送機能が進んでいる |
| Switchyard 0.3.0 に向けた案内 | Relay の中で動く Switchyard-owned dynamic plugin が予定されている |
Switchyard main では、通常の session header が x-switchyard-session-id に変わり、proxy_x_session_id は fallback になっています。呼び出し元の API key を provider へ渡す forward_auth も main 側の機能です。どちらも v0.2.0 の機能として扱わないよう注意してください。
2026 年 8 月 29 日時点で Switchyard 0.3.0 は未リリースです。今は二段構成を使いながら、前述の header adapter や API Gateway を交換できる部品として置いておくのがよさそうです。将来 plugin へ統合されたとしても、モデル選択、agent 実行、利用者管理を分ける考え方は残ります。
まとめ
NeMo Relay と NeMo Switchyard を、AI Gateway として普段の環境にどう置くかを整理してみました。
Switchyard は共通の接続口から依頼を受けてモデルを選ぶ交換台、Relay は coding agent が行った LLM と tool の実行を記録・制御する層です。モデルの使い分けが目的なら Switchyard、coding agent の作業を追いたいなら Relay から始めて、両方が必要になったときに直列につなげます。実測では 3 種類の API と streaming、retry、API key の置換、Relay のイベント記録と作業の時系列記録を同じ経路で確認できました。一方で、作業の識別子と trace は自動では揃わず、PII redaction も provider 送信前のマスキングではありません。
利用者認証、利用量と予算、秘密管理、送信前のデータ保護、観測の集約は、Relay と Switchyard に詰め込むのではなく、専用の部品を必要な場所へ足します。この分け方なら、個人利用からチーム利用へ、必要な機能だけを順に増やせます。
Switchyard 0.3.0 の dynamic plugin が出たら、二段構成との違いをあらためて試してみたいところです。
参考リンク
- NeMo Relay Overview
- NeMo Relay Release Notes — 0.8 での Switchyard 連携の削除と 0.3.0 dynamic plugin の予告
- NVIDIA/NeMo-Relay
- NVIDIA-NeMo/Switchyard v0.2.0 server README
- NVIDIA-NeMo/Switchyard main server README — main の未リリース仕様を確認
- OpenTelemetry Collector
- Presidio — Microsoft から Data Privacy Stack へ移管された PII 検出・匿名化の OSS
- AI Gateway を自作して得た知見と選定ポイント — 要件を先に並べて部品を割り当てる整理の仕方を参考にしました
