Routing DSL - OrcaRouter

組み込み戦略 —— cheapest, quality, balanced, adaptive —— は価格と品質でモデルを選びます。Routing DSL はその下のティアで、 適切な モデルがリクエストの実際の中身に依存する場合のためのものです: 長いエージェント的コーディングのターン、安価な分類呼び出し、ビジョンリクエスト、テスト失敗後のリトライなど。ルールを書けば、ゲートウェイがリクエストごとに評価し、それに従ってルーティングします。これは名前付きルーターの dsl 戦略です —— アプリは引き続き orcarouter/{name} を呼び出し、ルーティングロジックはダッシュボードに置かれ、再デプロイなしにバージョン管理・編集できます。

DSL を使うべきとき

「最安のライブモデル」や「最高品質」で意図が表現できるなら組み込み戦略を使ってください。リクエストの内容やコンテキストにルーティングが依存する場合に DSL を使います:

タスク特化 —— コードはコーディングモデルへ、ビジョンはビジョンモデルへ、安価なチャットは安価なモデルへ送る。
難易度を意識したルーティング —— 難しいリクエストだけを高価なモデルへエスカレートし、簡単なものは安く保つ。
エージェントを意識したルーティング —— セッション状態 (エージェントがどのツールを使ったか、テストが今失敗したか、何ターン目か) に基づいて異なるルーティングを行う。
時間 / テナント / ヘッダのルール —— 時間帯、ユーザーグループ、またはリクエストヘッダによる異なるルーティング。

有効化

ダッシュボードの Routing でルーターを開き、その Strategy を DSL に設定します。これでこのルーター用の DSL エディタが現れます。ルーターに関するその他のすべては引き続き適用されます —— Allowed models の glob、Default model のセーフティネット、orcarouter/{name} での呼び出しです。

エディタ

エディタは、意図から動作するルールセットへ素早く到達できるように作られています:

テンプレート はあなたのワークスペースの実モデルでシードされます (一度きりのティアマッピングダイアログ経由)。空のファイルから始めたり「未知のモデル」の壁にぶつかることはありません。
Insert —— 識別子を手で打つ代わりに、オートコンプリートから Model、Router (orcarouter/<name>)、Pool を挿入します。
Generate —— 欲しいルーティングを平易な言葉で記述すると、あなたの実モデルに基づいた、コンパイル済みでリント済みの DSL が返ってきます。
Explain —— 現在のルールセットが何をするかの平易な英語による言い換え。
インラインリント —— すべてのエラーが {line, column, message} を報告し、すべてのリントコードに ? の説明があります。優先順位 (first-match-wins) と一般的な CEL パターンがその場で示されます。

ファイル構造

ルールセットは 3 つのトップレベルキーを持つ YAML です:

version: 1              # required — currently must be 1
rules: [...]            # required — 1 to 30 rules, evaluated in order
default: {...}          # required — the effect when no rule matches

ルールは when: 条件と use: 効果です:

rules:
  - id: hard_code              # required: ^[a-z][a-z0-9_]{0,39}$, unique
    when: |                    # optional CEL boolean; absent ⇒ always matches
      task_class == "code" && difficulty > 0.6
    use:
      model: "anthropic/claude-sonnet-4-6"
default:
  delegate: balanced           # fall back to a built-in strategy

ルールは上から下へ評価され、when: が真になる最初のルールが勝ちます。 どれもマッチしない場合は default: が適用されます。ルールは最も具体的なものから順に並べてください —— 早い位置にある広範なルールは、その下のすべてを覆い隠してしまいます。

`when:` —— 条件

条件は CEL (Common Expression Language) で記述します: 設計上安全です —— ループなし、 I/O なし、マイクロ秒での評価、RE2 正規表現のみ。次の 6 つのパターンが実際のルールの大半をカバーします:

Pattern	Example
Field access	`task_class == "agent"`
Numeric compare	`difficulty > 0.6 && request.input_tokens < 50000`
Boolean logic	`agent_state.has_edited && !agent_state.has_run_tests`
List membership	`"Edit" in agent_state.tools_used`
Regex macro	`system_prompt_matches("(?i)planning agent")`
Tool macro	`tool_calls_present_any(["Edit","Write","apply_patch"])`

変数

リクエストの形状

Variable	Type
`model`	string
`request.input_tokens`	int
`request.output_max_tokens`	int
`request.stream`	bool
`request.vision`	bool
`request.message_count`	int
`request.has_system_prompt`	bool
`request.has_tools`	bool

分類 (ゲートウェイがリクエストごとに計算)

Variable	Type	Meaning
`task_class`	string	`chat` / `code` / `agent` / `vision` / `audio` / `rag` / `creative`
`difficulty`	double	`0.0`–`1.0`
`code_keyword_density`	double	`0.0`–`1.0`
`reasoning_cue_count`	int	プロンプト内で検出された推論の手がかり数
`tool_count`	int	リクエスト上の個別のツール定義数

エージェントセッション (agent_state.*、会話をまたいで永続化)

Variable	Type
`agent_state.turn`	int
`agent_state.tools_used`	list<string>
`agent_state.files_read`	list<string>
`agent_state.has_edited`	bool
`agent_state.has_run_tests`	bool
`agent_state.last_test_failed`	bool
`agent_state.consecutive_errors`	int
`agent_state.elapsed_seconds`	int
`agent_state.models_tried`	list<string>

コンテキスト

Variable	Type
`headers["x-foo"]`	string
`user.id` / `user.group`	int / string
`token.id` / `token.name`	int / string
`time.hour` / `time.weekday`	int (UTC)
`workspace.id`	int

マクロ

一般的な「リクエストの中身を見る」チェックのために登録された CEL 関数:

Macro	Returns
`system_prompt_matches(regex)`	結合されたシステムメッセージに対する RE2
`user_message_matches(regex)`	最後のユーザーメッセージに対する RE2
`tool_definitions_include(name)`	あるツールがリクエスト上で宣言されている
`tool_calls_present_any(list)`	リクエストがこれらのツール呼び出しのいずれかを含む
`tool_results_from_any(list)`	リクエストがいずれかからの tool ロールメッセージを持つ
`header_matches(name, regex)`	ヘッダ値に対する RE2

`use:` —— 効果

use: ブロックは destination (ちょうど 1 つ) と、任意の数のオプションの呼び出し単位の knob を指定します。

Destination

use:
  model:    "anthropic/claude-sonnet-4-6"   # one upstream model
  models:   ["openai/gpt-4o-mini", "..."]   # load-balance across a list
  pool:     "@pool:<name>"                   # an admin-curated pool
  delegate: balanced                         # hand off to a built-in
                                             #   strategy: cheapest |
                                             #   quality | balanced |
                                             #   linucb | gated_adaptive

delegate: dsl は拒否されます (再帰してしまうため)。特定のチャネルへの固定 (channels: / @channel:) は現在利用できず、未対応としてリントされます —— 代わりに model、models、pool でルーティングしてください。

呼び出し単位の knob

任意の destination と組み合わせて上流呼び出しを形作ります:

use:
  reasoning_effort:       low | medium | high     # OpenAI o-series, Gemini
  thinking_budget_tokens: 1024..64000             # Claude / Gemini thinking
  samples:                1..16                    # the n parameter
  temperature:            0.0..2.0
  param_override:         { ... }                  # merged into upstream params
  header_override:        { ... }                  # merged into upstream headers
  reason_tag:             "<[a-z0-9_]+>"           # shows up in logs/telemetry
  affinity_ttl:           "5m"                      # channel stickiness window
  model_rewrite:          "<upstream-model>"       # send under a different name

param_override と header_override はデニーリストを強制します —— model、messages、stream、tools、認証ヘッダなどはオーバーライドできません (それらは課金、監査、エージェント状態を覆してしまうため)。

信頼度カスケード & アンサンブル (高度)

2 つの高度な効果により、ルールが弱い最初の回答に反応したり、複数のモデルにファンアウトしたりできます。他のどのルールとも同じように記述します。 カスケード —— 低信頼度シグナルでより強力な効果へリトライします:

rules:
  - id: code_with_repair
    when: task_class == "code"
    use:
      model: "openai/gpt-4o-mini"
    on_low_confidence:
      signals: [patch_invalid, self_doubt, next_turn_test_failed]
      use:
        model: "anthropic/claude-sonnet-4-6"   # repair attempt

アンサンブル —— 複数のレッグを並列に発行し、アービターに選ばせます:

use:
  parallel:
    - { model: "anthropic/claude-sonnet-4-6" }
    - { model: "openai/gpt-4o-mini", samples: 2 }
  arbiter:
    strategy: best_of_n        # or majority | first | tests_pass
    model:    "anthropic/claude-sonnet-4-6"   # judge (best_of_n only)
  max_latency_ms: 120000

アンサンブル / カスケードのランタイムはゲートされており、既定ではオフです。 各並列レッグと各カスケード修復はそれぞれ独立した呼び出しとして課金されるため、レッグ単位の課金が検証されるまで、ファンアウトランタイムはサーバーフラグの背後にあります。オフの状態では、parallel: ルールは最初のレッグのみを提供し、カスケードはシグナルを記録するものの再ディスパッチはしません —— ルールセットは引き続き通常どおりリント・保存され、その主効果をルーティングします。ワークスペースでアンサンブルランタイムを有効化するにはお問い合わせください。

安全にロールアウトする

新しいルールセットは、保存した瞬間にトラフィックを引き継ぐわけではありません:

シャドウモード —— 最初の保存後の一定期間、DSL は評価されますが使われません: 以前の戦略が引き続きトラフィックを処理し、その間にゲートウェイは DSL が行ったであろうことを記録します。ダッシュボードは差分レポートを表示します —— ルートが異なる割合、予測されるコスト差分、ルール別の発火回数、default: に落ちた頻度です。ルールを信頼する前にこれを読んでください。
カナリア —— DSL をライブトラフィックの一定割合 (5 → 25 → 50 → 100) に段階投入し、スライス別メトリクスを監視しながら、割合を 0 にスライドすることで即座にロールバックできます。

また、エディタ内で合成リクエスト (タスククラス、難易度、エージェント状態、リクエスト形状) に対してルールセットを dry-run し、トレースとマッチしたルールを確認することもできます —— トラフィックなし、何も永続化されません。

制限と検証

すべての保存で厳格なリントが実行され、無効なルールセットは {line, column, message, rule} とともに拒否されます:

スキーマ —— 必須キー、正しい型/列挙、未知のフィールドなし。
サイズ —— ルール ≤ 30、YAML ≤ 16 KiB、when: 1 つあたり ≤ 200 文字。
CEL —— パースされ、変数環境に対して型チェックされ、未知の識別子がなく、when: は bool に評価される必要があります。
効果 —— use: ブロックごとにちょうど 1 つの destination; すべての model / models / @pool: 参照がワークスペース内で解決できること。
knob の範囲 —— thinking_budget_tokens ∈ [1024, 64000]、 temperature ∈ [0, 2]、samples ∈ [1, 16]。
予約 —— _ で始まるルール id は予約済み; ルール id としての default は拒否されます (トップレベルの default: ブロックを使用)。

すべての保存とロールバックは監査行を書き込みます; 同時編集は検出され、 2 番目の保存は最新の状態に対してリトライするよう求められます。

完全な例

version: 1
rules:
  - id: vision
    when: request.vision
    use: { model: "openai/gpt-4o" }

  - id: cheap_chat
    when: task_class == "chat" && difficulty < 0.3
    use: { delegate: cheapest }

  - id: hard_code
    when: task_class == "code" && difficulty > 0.6
    use:
      model: "anthropic/claude-sonnet-4-6"
      thinking_budget_tokens: 8000
      reason_tag: hard_code

  - id: agent_after_failed_test
    when: agent_state.last_test_failed && agent_state.consecutive_errors >= 2
    use:
      model: "anthropic/claude-sonnet-4-6"
      reason_tag: repair

default:
  delegate: balanced

リクエストがどのモデルに解決されたかを確認するには、X-Orca-Router と X-Orca-Resolved-Model のレスポンスヘッダを読みます。

API リファレンス

DSL はルーター単位で管理されます; 書き込みには Developer+ が必要です。

Method & path	Role	Purpose
`GET /api/user/routers/:id/dsl`	Member	ソース + バージョン + シャドウ/カナリア状態。
`PUT /api/user/routers/:id/dsl`	Developer+	リント + 保存 (新バージョン、監査対象)。
`POST /api/user/routers/:id/dsl/lint`	Member	ドラフトをリント → `{errors:[…]}`。
`POST /api/user/routers/dsl/lint`	Member	ステートレスなリント (ルーター id なし)。
`POST /api/user/routers/:id/dsl/dryrun`	Member	合成リクエストを評価 → トレース + マッチしたルール。
`GET /api/user/routers/:id/dsl/history`	Member	バージョン履歴、新しい順。
`POST /api/user/routers/:id/dsl/rollback/:version`	Developer+	再リントして古いバージョンを復元。

FAQ

名前付きルーターの戦略とどう違いますか?

これは戦略です —— cheapest / quality / balanced / adaptive と並ぶ dsl オプションです。他の戦略は価格と品質で選びますが、DSL はリクエストの形状、分類、エージェント状態に対してあなたが書いたルールで選びます。ルールの効果として、またはデフォルトとして、引き続き組み込み戦略へ delegate: できます。

どのルールもマッチしない場合はどうなりますか?

トップレベルの default: 効果が適用されます。これは必須なので、常に定義された結果があります —— 一般的には delegate: balanced か特定のセーフティネットモデルです。

ホットパスで信頼できない CEL を実行しても安全ですか?

はい。CEL は標準ライブラリ関数のみのサンドボックス、数ミリ秒の評価デッドライン、RE2 正規表現 (線形時間、ReDoS なし)、データベース・ネットワーク・ファイルシステムへのアクセスなし、で実行されます。変数環境はスカラとリストの固定セットです。

実トラフィックに触れる前にルールセットをテストできますか?

3 つの方法があります: エディタ内で合成リクエストに対して dry-run する、シャドウモードのままにして差分レポートを読む、その後 100% へ段階投入する前にライブトラフィックの小さな割合へ カナリア する、です。

​DSL を使うべきとき

​有効化

​エディタ

​ファイル構造

​when: —— 条件

​変数

​マクロ

​use: —— 効果

​Destination

​呼び出し単位の knob

​信頼度カスケード & アンサンブル (高度)

​安全にロールアウトする

​制限と検証

​完全な例

​API リファレンス

​FAQ

DSL を使うべきとき

有効化

エディタ

ファイル構造

`when:` —— 条件

変数

マクロ

`use:` —— 効果

Destination

呼び出し単位の knob

信頼度カスケード & アンサンブル (高度)

安全にロールアウトする

制限と検証

完全な例

API リファレンス

FAQ