ypollak2/llm-router

pip install llm-routing   # PyPI name is llm-routing; the CLI command is llm-router

• 導入する理由

• RouterArena で 8 位にランクイン

• クイックスタート

• ルーティングの例

• 対応ツール

• 仕組み

• 機能

• CLI

• プロバイダー

• ルーティングポリシー

• MCP ツール

• コスト削減の仕組み

• 信頼性・プライバシー・ローカルファースト設計

• 設定

• ドキュメント

• エンタープライズ

• コントリビューション

導入する理由

AI コーディングツールは、デフォルトでプレミアムモデルにプロンプトを送りすぎます。

つまり、次のような問題が起きます:

• 単純な質問に有料トークンを浪費する

• Claude、Gemini、OpenAI のクォータを必要以上に早く消費する

• 1 つのプロバイダーがレート制限や停止になると作業が止まる

llm-router は、コーディングツールとモデルプロバイダーの間に位置します。各プロンプトを分類し、まず最も安い能力十分なモデルを試し、必要に応じて自動的にフォールバックします。

ワークフローはそのまま維持されます。ルーターが裏側でモデル選択を変更するだけです。

Related MCP server: MCP AI Router

RouterArena で 8 位にランクイン

llm-router は、RouterArena で独立したベンチマーク評価を受け、8 位にランクインしました。RouterArena は、モデルルーターをルーティング精度、レイテンシ、コスト効率、フォールバック信頼性で評価するコミュニティ型リーダーボードです。

クイックスタート

1. インストール

pip install llm-routing
llm-router install

パッケージ名: PyPI 上の llm-routing。CLI コマンド: llm-router。

2. プロバイダーの追加（任意）

export OPENAI_API_KEY="sk-..."          # GPT-4o, o3
export GEMINI_API_KEY="AIza..."         # Gemini Flash/Pro (free tier available)
export OLLAMA_BASE_URL="http://localhost:11434"  # Local models (free)
export OPENROUTER_API_KEY="sk-or-v1-…"  # 343 OpenRouter models (qwen, deepseek, grok, …)

Claude Code Pro/Max サブスクリプションでは API キーゼロで動作します。ルーティングは MCP ツールを使用し、有益な場合にのみ外部モデルを呼び出します。OPENROUTER_API_KEY を追加すると、cost_aggressive ポリシーで使用されるオープンウェイトのワークホースプールが解放されます。

3. 確認

llm-router health            # Check provider connectivity

すでに Claude Code、Codex、Gemini CLI を使用している場合は、既存のワークフローを維持したまま、llm-router にモデル選択を任せることができます。

ルーティングの例

正確なチェーンは、設定したプロバイダー、予算プロファイル、ルーティングポリシーによって異なります。

対応ツール

• 完全自動ルーティングとは、フックがプロンプトをインターセプトし、ワークフローの変更なしに自動的にルーティングすることを意味します。

• 手動 MCP ツールとは、llm_query などのツールを通じてオンデマンドでルーティングを利用できることを意味します。

llm-router install                    # Claude Code (default)
llm-router install --host codex       # Codex CLI
llm-router install --host gemini-cli  # Gemini CLI
llm-router install --host vscode      # VS Code
llm-router install --host cursor      # Cursor

各ホストの詳細は guide/HOST_SUPPORT_MATRIX.md を参照してください。

Claude Code の 5 時間クォータを保護

enforce: smart + mode: zero_claude を設定すると、プロンプトが外部で完了するか、ネイティブ Claude が実行される前に停止します。詳細は guide/GETTING_STARTED.md を参照してください。

仕組み

User prompt
    │
    ▼
┌──────────────────────┐
│ Complexity Classifier │  ← Heuristic (free, instant) or Ollama/Flash ($0.0001)
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│  Free-First Router   │  ← Tries cheapest model first, walks up the chain
│                      │
│  Ollama (free)       │
│  → Codex (prepaid)   │
│  → Gemini Flash      │
│  → GPT-4o / Claude   │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│  Guards (parallel)   │  ← Circuit breaker, budget pressure, quality check
└──────────┬───────────┘
           │
           ▼
      Response + cost logged to local SQLite

分類は、多くのタスクでは無料（正規表現ヒューリスティックで約 70% を捕捉）か、曖昧なプロンプトではローカルの Ollama や Gemini Flash を使用してほぼ無料で実行されます。

機能

「安いプロンプトを安いモデルに送る」だけではありません:

• シークレットがマシンの外に出ない。 API キー、トークン、秘密鍵を含むプロンプトはローカルモデルのみにルーティングされます。フェイルクローズ方式のため、外部プロバイダーに到達することはありません。

• コスト反転型サブスクリプションルーティング。 単純・中程度のプロンプトでは無料・ローカルを優先し、複雑なプロンプトでは有料シートを優先、クォータが逼迫するとシートを降格します。LLM_ROUTER_SUBSCRIPTION_PROVIDER でオプトインできます。

• サーキットブレーカーによる自動フォールバック。 失敗またはレート制限されたプロバイダーはスキップされ、無駄に再試行されません。

• 動作を確認できる。 ステータスライン、ターミナルタイトル、OS 通知で、最後にルーティングされたモデル、コスト削減額、健全性を表示します。ネイティブのステータスラインがないホスト向けです。

• セッション終了時のサマリー。 ベースラインとの比較による削減額、層別の割合、プロバイダー別コスト、レイテンシ p50/p95/p99、上位ルートを表示します。

• メディアとパイプラインにも対応。 llm_image / llm_video / llm_audio、および多段階リサーチ用の llm_orchestrate。

CLI

llm-router install      # wire up your host (Claude Code by default)
llm-router health       # provider connectivity
llm-router status       # savings + quota at a glance
llm-router doctor       # diagnose a broken setup

完全なコマンドリファレンス: guide/GETTING_STARTED.md

プロバイダー

20 以上のプロバイダーに対応し、無料ファーストです。Ollama（ローカル、無料）がチェーンの先頭を担い、OpenRouter（1 つのキーで 343 モデル）が最大の解放ポイント、Gemini と Groq には利用可能な無料枠があります。Anthropic は既存の Claude サブスクリプション経由で動作し、API キーは不要です。

全プロバイダー、モデル、コスト層、環境変数: guide/PROVIDERS.md

ルーティングポリシー

ポリシーは、プレミアムモデルからどれだけ積極的にルーティングするかを決定します。conservative（10〜15% 削減）から balanced（デフォルト、35〜45%）、cost_aggressive（70〜85%、OPENROUTER_API_KEY が必要）まであります。

llm-router policy set cost_aggressive

全 6 ポリシー、しきい値、YAML スキーマ: guide/POLICIES.md

MCP ツール

ルーティング、分析、コード、メディア、予算、診断にわたる 60 のツールを、任意の MCP ホストに公開します。デフォルトの consolidated サーフェスでは 11 のフロントドアツールを表示し、LLM_ROUTER_SLIM=full を設定すると全 60 ツールを表示します。

全ツールとシグネチャ: guide/TOOLS.md

コスト削減の仕組み

コスト削減額は、実際の支出を、すべてのタスクを Claude Sonnet/Opus にルーティングした場合のベースラインと比較して計算されます。

方法論:

1. ルーティングされた各タスクが記録: 使用モデル、消費トークン、推定コスト

2. 同じトークンがチェーン内で最も高価なモデルで処理された場合のベースラインコストを計算

3. 削減額 = (ベースライン - 実際) / ベースライン

前提と制限:

• ベースラインは、すべてに Opus/Sonnet を使用した場合を想定（最悪ケース）

• トークン推定は len(text) / 4 の近似を使用し、正確なトークナイザー数ではない

• コストデータは LiteLLM の価格テーブルに基づく（プロバイダーの価格変更に遅れる可能性あり）

• 削減額はワークロードによって大きく変動 — コード中心のセッションでは安いモデルへのルーティングが増える

• ルーター自体にもわずかなオーバーヘッドがある（曖昧なタスクの分類コストは約 $0.0001）

観測範囲: ポリシーとタスク構成に応じて 35〜80% の削減。一部のドキュメントにある「87%」という数字は、特定の開発期間における単一ユーザーのピーク値であり、保証された結果ではありません。

信頼性・プライバシー・ローカルファースト設計

llm-router は完全にあなたのマシン上で動作します。ホスト型プロキシ、テレメトリ、アカウント登録は一切ありません。

私たちが行うこと:

• 構造化ログからAPIキーを除去します

• インストール前にフックのデッドロックを検出します

• すべてのデータを~/.llm-router/にローカル保存します

• プロバイダーのレート制限と利用規約（TOS）を尊重します

知っておくべきこと:

• プロンプトはルーターが選択したプロバイダーに送信されます — プロバイダーのプライバシーポリシーを確認してください

• 使用ログ（SQLite）は保存時に暗号化されていません — 必要に応じてフルディスク暗号化を使用してください

• ルーターはプロバイダーレベルでのモデルの脱獄（ジェイルブレイク）やプロンプトインジェクションを防ぐことはできません

責任ある開示ポリシーについてはSECURITY.mdを参照してください。

設定

すべては環境変数で管理されます — 開始に設定ファイルは不要です:

export OPENROUTER_API_KEY="sk-or-v1-..."          # biggest single unlock
export OLLAMA_BASE_URL="http://localhost:11434"   # local, free
export LLM_ROUTER_POLICY="cost_aggressive"        # routing policy
export LLM_ROUTER_ENFORCE="smart"                 # off | advise | smart | hard

完全なリファレンス、設定ファイルのスキーマ、ホストごとの上書き設定: guide/GETTING_STARTED.md

ドキュメント

完全なインデックス: guide/README.md

エンタープライズ

llm-routerは個人開発者と小規模チーム向けに作られています: ローカルでのコスト削減、運用オーバーヘッドゼロ、ホスト型サービスは一切不要です。チーム全体のポリシー適用、監査エクスポート、SSO、組織ごとの予算管理が必要な場合は、Chuzom がそのためのツールです。

コントリビューション

コントリビューションを歓迎します。詳細なガイドラインについてはCONTRIBUTING.mdを参照してください。

git clone https://github.com/ypollak2/llm-router.git
cd llm-router
uv sync --extra dev
uv run pytest tests/ -q         # Run tests (1900+)
uv run ruff check src/ tests/   # Lint

-|-----------| | llm-routing | 現在のPyPIパッケージ（pip install llm-routing） | | llm-router | CLIコマンドおよびGitHubリポジトリ名 | | claude-code-llm-router | 非推奨のレガシーパッケージ（llm-routingにリダイレクト） |