Switch 利用ガイド 開発中

はじめに

任意の OpenAI クライアントを Switch に接続する

Switch は起動するとローカルで OpenAI API 互換のエンドポイントを公開します。base_url を 1 行書き換えるだけで、すべてのリクエストが自動的に Switch によってルーティングされます。

クイック接続

Switch は起動するとローカルで OpenAI API 互換のエンドポイント http://localhost:19090/v1 を公開します（Switch gateway のデフォルトポートは 19090）。アプリ／SDK の base_url をこのアドレスに変更すると、すべてのリクエストが自動的に Switch によってルーティングされます。api_key には任意の値（例: switch）を入力してください。Switch は設定内の provider key を使用します。

1. クライアントの base_url をローカルの Switch エンドポイントに向け、api_key には任意の値（例: switch）を入力して、通常どおりリクエストを送信します:

   cURL

   curl http://localhost:19090/v1/chat/completions \
     -H "Content-Type: application/json" -H "Authorization: Bearer switch" \
     -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello"}]}'

   Python

   from openai import OpenAI
   
   client = OpenAI(
       base_url="http://localhost:19090/v1",
       api_key="switch",
   )
   resp = client.chat.completions.create(
       model="gpt-4o",
       messages=[{"role": "user", "content": "Hello"}],
   )
   print(resp.choices[0].message.content)

   Node.js

   import OpenAI from "openai";
   
   const client = new OpenAI({
     baseURL: "http://localhost:19090/v1",
     apiKey: "switch",
   });
   const resp = await client.chat.completions.create({
     model: "gpt-4o",
     messages: [{ role: "user", content: "Hello" }],
   });
   console.log(resp.choices[0].message.content);

2. OpenAI SDK（Python / Node.js）では base_url/baseURL と api_key を変更するだけで、その他の呼び出しは通常どおりです — Switch は設定内の provider key を使って実際のルーティングを行うため、クライアント側は下流のプロバイダーを意識する必要はありません。

なぜ api_key は任意の値でよいのか

Switch はローカルプロキシとして、設定内に保存された実際の provider key を使って下流を呼び出します。クライアント側の api_key はプレースホルダーとしてのみ使われるため、switch と入力すれば十分です。

統合

AI コーディングツールで使う

すべてのツールで API Base / インターフェースアドレスには http://localhost:19090/v1 を、API Key には switch を入力します。

AI コーディングツールで使う

すべてのツールで API Base / インターフェースアドレスには http://localhost:19090/v1 を、API Key には switch を入力します:

Cursor

設定（Ctrl+,）→「AI」を検索 →「OpenAI API Base」をこのアドレスに変更 → 保存すると、補完と対話が自動的に Switch を経由します。

Continue（VS Code）

~/.continue/config.json を編集し、各 model 項目に "provider": "openai"、"apiBase": "http://localhost:19090/v1"、"apiKey": "switch" を設定し、"model" には deepseek-chat / gpt-4o などを入力します。

Cherry Studio

設定 → API 設定 →「カスタム OpenAI 互換」を選択 → アドレスと Key を入力 →「接続テスト」。

Lobe Chat

設定 → 言語モデル → OpenAI → API Key とインターフェースアドレスを入力。

ランタイム

監視・切り替え・ストリーミング

リクエスト監視

「ログ」タブでリアルタイムのリクエストログを確認できます。フィールド: 時刻（タイムスタンプ）、モデル、プロバイダー（実際のルーティング先）、所要時間（ms）、Token（prompt/completion）、ステータス（200 / 4xx-5xx）。「CSV をエクスポート」で直近 7 日間の記録をエクスポートしてコスト集計に利用できます。

プロバイダーのワンクリック切り替え

メニューバーアイコン（macOS）／システムトレイ（Windows）をクリックすると、次の操作ができます: 「現在アクティブなプロバイダー」の切り替え、特定プロバイダーの一時無効化（デバッグ用）、本日の使用量概要の確認。

ストリーミングレスポンス

SSE ストリーミングレスポンスを完全にサポートし、下流へそのまま透過します: chat.completions.create(..., stream=True) の後に chunk.choices[0].delta.content を反復処理します。

応用

ロードバランシング

同一モデルに複数のプロバイダーを設定した場合、ラウンドロビンまたは重み付けで割り当てできます。

応用: ロードバランシング

同一モデルに複数のプロバイダーを設定した場合、ラウンドロビンまたは重み付けで割り当てできます:

{
  "routing": {
    "rules": [
      {
        "pattern": "deepseek-chat",
        "providers": [
          { "name": "Lurus API", "weight": 70 },
          { "name": "DeepSeek Official", "weight": 30 }
        ],
        "strategy": "weighted_random"
      }
    ]
  }
}

トラブルシューティング

トラブルシューティング

該当する症状を展開して対処手順を確認してください。

トラブルシューティング

"connection refused" — 接続が拒否される

Switch が起動していないか、ポートが正しくありません。プロセスとポートを確認します:

• プロセス: Windows tasklist | findstr LurusSwitch / macOS・Linux ps aux | grep lurus-switch
• ポート: curl http://localhost:19090/v1/models

401 / 403 — 認証失敗

プロバイダーの API Key の設定が誤っています。設定画面で入力し直し、「テスト」をクリックして接続性を確認してください。

レイテンシが異常に高い

1. ログで正しいプロバイダーにルーティングされているか確認します。
2. 海外プロバイダー（OpenAI / Anthropic）の高レイテンシは正常です（300-1500ms）。
3. Lurus API の国内ノードに切り替えます（通常 < 200ms）。

macOS アプリが応答しない

メニューバーで右クリック →「終了」してから再起動するか、ターミナルで実行します:

pkill -f LurusSwitch && open -a "Lurus Switch"

次のステップ

次のステップ

MCP サーバー管理コスト監視チーム設定の同期