omni-combos-routing

概要

19 種類の戦略（優先順位、重み付け、ラウンドロビン、Auto-combo など）を使用して、ルーティングコンボを作成・管理します。フォールバックチェーンを設定し、ルーティング結果をテストして、コンボのメトリクスを取得できます。

認証

すべてのリクエストには、有効な Bearer トークンまたはセッション Cookie が必要です。POST /api/auth/login でトークンを取得するか、ローカル開発用に REQUIRE_API_KEY=false を設定してください。

エンドポイント

GET /api/combos

ルーティングコンボの一覧を取得

curl http://localhost:20128/api/combos \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

POST /api/combos

ルーティングコンボを作成

curl -X POST http://localhost:20128/api/combos \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

GET /api/combos/{id}

ID でコンボを取得

curl http://localhost:20128/api/combos/{id} \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

PUT /api/combos/{id}

コンボを更新

部分更新：リクエストボディは保存済みのコンボにマージされるため、省略されたフィールドは現在の値を維持します。送信された配列は、保存済みの配列を完全に置き換えます。

curl -X PUT http://localhost:20128/api/combos/{id} \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

PATCH /api/combos/{id}

コンボを更新

部分更新：リクエストボディは保存済みのコンボにマージされるため、省略されたフィールドは現在の値を維持します。送信された配列は、保存済みの配列を完全に置き換えます。

curl -X PATCH http://localhost:20128/api/combos/{id} \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

DELETE /api/combos/{id}

コンボを削除

curl -X DELETE http://localhost:20128/api/combos/{id} \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

GET /api/combos/metrics

コンボのメトリクスを取得

curl http://localhost:20128/api/combos/metrics \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

POST /api/combos/test

コンボ設定をテスト

curl -X POST http://localhost:20128/api/combos/test \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

GET /api/fallback/chains

フォールバックチェーンの一覧を取得

モデルルーティング用に登録されたすべてのフォールバックチェーンを返します。

curl http://localhost:20128/api/fallback/chains \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

POST /api/fallback/chains

フォールバックチェーンを作成

モデル用のフォールバックルーティングチェーンを登録します。

curl -X POST http://localhost:20128/api/fallback/chains \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

DELETE /api/fallback/chains

フォールバックチェーンを削除

curl -X DELETE http://localhost:20128/api/fallback/chains \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

GET /api/combos/auto

コンボ › 自動を取得

curl http://localhost:20128/api/combos/auto \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

GET /api/combos/builder/options

コンボ › ビルダー › オプションを取得

curl http://localhost:20128/api/combos/builder/options \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

POST /api/combos/duplicate

コンボ › 複製を作成

curl -X POST http://localhost:20128/api/combos/duplicate \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

POST /api/combos/reorder

コンボ › 順序を変更

curl -X POST http://localhost:20128/api/combos/reorder \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

ペイロード

リクエスト／レスポンスのスキーマの詳細は、完全な OpenAPI 仕様 GET /api/openapi/spec または docs/openapi.yaml を参照してください。

OmniRoute — ルーティングとコンボ

OMNIROUTE_URL と OMNIROUTE_KEY が必要です。セットアップについては、エントリーポイントの SKILL を参照してください。

コンボとは？

コンボは、ルーティング戦略を指定したプロバイダー／モデルの名前付きグループです。コンボ経由のリクエストはすべて自動的に分散され、フェイルオーバーと負荷分散が行われます。呼び出し元は my-combo のような単一のモデル ID を使用します。

既存のコンボを一覧表示する

curl $OMNIROUTE_URL/api/combos \
  -H "Authorization: Bearer $OMNIROUTE_KEY"

レスポンスには、id、name、strategy、enabled と、ターゲットごとの統計情報が含まれます。

コンボを作成する

curl -X POST $OMNIROUTE_URL/api/combos \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-combo",
    "strategy": "priority",
    "targets": [
      { "provider": "anthropic", "model": "claude-opus-4-7", "weight": 1 },
      { "provider": "openai",    "model": "gpt-4o",           "weight": 1 }
    ]
  }'

19 種類の公開ルーティング戦略

戦略	説明
priority	常に target[0] を使用し、エラー時にフォールバックします
weighted	重みの割合に応じて分散します
round-robin	ターゲットを順番に切り替えます
context-relay	非常に長いコンテキスト向けにモデルを連鎖させます
fill-first	target[0] のクォータを使い切ってから、次のターゲットに移ります
p2c	二択方式：2 つのターゲットをサンプリングし、より適した候補を選びます
random	均等な確率でランダムに選択します
least-used	使用状況の観測値が最も低いターゲットにルーティングします
cost-optimized	トークン推定量に対して利用可能なターゲットのうち、最も低コストのものを選びます
reset-aware	クォータのリセット状態に基づいてターゲットを優先します
reset-window	設定されたリセット期間に基づいてターゲットを並べ替えます
headroom	クォータの残り容量が多いターゲットを優先します
strict-random	すべてのターゲットを使い切るまで、同じターゲットを繰り返さずにランダムに選択します
auto	16 個の要素に基づいて Auto-Combo でスコアを付けます
lkgp	最後に正常だったプロバイダーへのスティッキールーティング
context-optimized	リクエストのコンテキストサイズに最適なモデルを選びます
cache-optimized	キャッシュ親和性の高いターゲットを優先します
fusion	複数のモデルを並列実行し、評価した結果を統合して 1 つのレスポンスを生成します
pipeline	設定されたターゲットの順序をパイプラインとして実行します

Auto-combo（本番環境に推奨）

Auto-combo は、リクエストごとに各候補を 16 個の要素に基づいてスコアリングします。

curl -X POST $OMNIROUTE_URL/api/combos \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-auto",
    "strategy": "auto",
    "targets": [
      { "provider": "anthropic", "model": "claude-sonnet-4-6" },
      { "provider": "openai",    "model": "gpt-4o-mini" },
      { "provider": "google",    "model": "gemini-2.0-flash" }
    ]
  }'

続いて、次のように呼び出します。

curl -X POST $OMNIROUTE_URL/v1/chat/completions \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "prod-auto", "messages": [{ "role": "user", "content": "Hello" }] }'

コンボを有効化／無効化する

# Activate
curl -X PUT $OMNIROUTE_URL/api/combos/{id}/toggle \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -d '{ "enabled": true }'

コンボのメトリクスを取得

curl $OMNIROUTE_URL/api/combos/{id}/metrics \
  -H "Authorization: Bearer $OMNIROUTE_KEY"

p50／p95／p99 レイテンシ、成功率、コスト、およびターゲットごとの内訳を返します。

ルーティングをシミュレート（ドライラン）

curl -X POST $OMNIROUTE_URL/api/routing/simulate \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "comboId": "{id}", "messages": [{ "role": "user", "content": "test" }] }'

実際の API 呼び出しは行わず、選択されるプロバイダーとその理由を返します。

MCP 経由（OmniRoute が MCP サーバーの場合）

omniroute_list_combos     → list all combos
omniroute_switch_combo    → enable/disable a combo
omniroute_set_routing_strategy → change strategy at runtime
omniroute_simulate_route  → dry-run routing decision
omniroute_best_combo_for_task → get recommendation by task type

エラー

• 404 combo not found → /api/combos の id を確認してください
• 400 invalid strategy → 上記の 19 個の戦略のいずれかを使用してください
• 409 name conflict → コンボ名はすでに存在します